Hey Alex,
Thanks for pushing forward on this.
Overall:
1.) It seems that, if we go the route of supporting multiple formats
for the PDP, we would have to choose the "multipart/related" option
in Anish's outline of CAMP-3
(https://www.oasis-open.org/apps/org/workgroup/camp/email/archives/201304/msg00118.html).
2.) Though it's not as bad as supporting both XML and JSON for the
resource serialization, supporting both YAML and JSON for the
Deployment Plan serialization is still a bad idea. Choosing either
one would be better than supporting both. If people feel that
passionately about JSON (or YAML if we decide to go with JSON) they
can write a conversion script or utility.
~ gp
On 5/9/2013 8:03 AM, Alex Heneveld
wrote:
Hi folks-
I've redrafted the first part of chapter 4 on the PDP (CAMP-65
[1]) to take account of the issues discussed during the 1 May call
-- in paticular the advantages and limitations of the various
archive formats.
My suggestion is to support multiple formats for the PDP -- ZIP,
TAR, TGZ -- and also to support upload of the DP YAML directly.
This places the burden on the platform developer, but in reality
it is easy enough to do. The more important think is to be
user-friendly and encourage adoption by supporting the most common
formats.
Also I have added a paragraph which says platforms SHOULD support
an OVF-style validation scheme, as Adrian's suggestion is
unsurprisingly a good and lightweight one.
What do people think?
I include specifics in draft text [2] below. I would appreciate
feedback on this before inflicting Word on myself and others,
before Tuesday if at all possible. Some things I wasn't sure
about are indicated with "???". Provided this is the direction we
want to go I will submit a Word proposal on the basis of this and
comments on Tuesday which I hope we can discuss on the next call.
Best,
Alex
[1] https://tools.oasis-open.org/issues/browse/CAMP-65
[2] proposal / draft:
CHAPTER 4
===
The Platform Deployment Package (PDP) and the Deployment Plan (DP)
define the formats for onboarding new applications into a CAMP
system. These may be generated by an Application Development
Environment, by a human, or by an export from another Platform
instance. By POSTing a valid PDP or DP to a Platform URI, a
client can create new AssemblyTemplate resources in the platform
which can subsequently be used to instantiate new Assemblies.
SUPPORTED POST FORMATS
(could put this section last in the chapter???)
A platform MUST support the following content bodies on a POST to
the Platform URI:
* A PDP as a ZIP archive [ZIP], when the MIME type is
(application/x-zip???)
* A PDP as a TAR archive [TAR], when the MIME type is
(application/x-tar???)
* A PDP as a GZIP-TAR archive [TGZ], when the MIME type is
(application/x-tar-gz???)
* A DP in YAML format [YAML], when the MIME type is
(application/x-yaml???)
* A DP in JSON format [JSON], when the MIME type is
(application/x-json???)
(not sure about JSON???)
A platform MAY support additional formats.
The response from the platform to such a POST to the Platform URI
MUST be as follows:
* On success, status code 200 and message body consisting of the
AssemblyTemplate resource created
(should we allow 201/202 ???)
Right now Section 6.12 of the spec says (a) return a 201, (b) use
the HTTP "Location" header in the response to carry the URI of the
newly created AssemblyTemplate. Section 5.4 also states that "
In addition, they might include a response message body
containing a representation of the requested information." I think,
as an editorial issue, Section 6.12 should reiterate this point and
specifically call out that a platform may *optionally* return a
representation of the AssemblyTemplate in the body of the response.
* On error, status code and message body as described
in Section 5.4
PDP PACKAGE STRUCTURE
The PDP MUST be an archive containing a DP file called "camp.yaml"
in its root directory. This DP MUST be comprised of valid YAML in
accordance with the structure and semantics described in the
subsequent section. The PDP archive MAY include other files
related to the deployment, including but not limited to
application content files such as web archives, database schemas,
scripts, source code, localization bundles, and icons; and
metadata files such as manifests, checksums, signatures, and
certificates.
A platform SHOULD support a validation scheme whereby either or
both:
* A manifest file "camp.mf" is provided in the root of the archive
containing SHA256 digests for one or more files in the archive.
Such a file, if present SHOULD include the digest for "camp.yaml".
It MAY contain digests for any other file in the archive. A
platform SHOULD reject any PDP where the manifest includes a
digest for a file which does not match the digest as computed for
that file.
* A certificate file "camp.cert" is provided in the root of the
archive containing signed SHA256 digests for files in the archive
and an X.509 certificate: Such a file, if present SHOULD include
either the signed digest for "camp.mf" if that file is present or
the signed digest for "camp.yaml". It MAY contain digests for any
other file in the archive. A platform SHOULD reject any PDP where
the certificate file includes a signed digest for a file which
does not match the digest as computed for that file or where the
digest is incorrectly signed.
The format of the manifest file and the certificate file and the
SHA256 algorithm SHOULD be as defined by the OVF specification
[OVF]. A platform MAY require a certificate file but in such
cases it SHOULD permit the certificate file to refer either to a
manifest file or to a deployment plan.
While I agree that using OVF to define the formats of the manifest
file and certificate file saves us a lot of work, this will add a
normative reference to the OVF spec - something we shouldn't do
without careful consideration. Another possibility would be to do
what OVF does, but use YAML for the manifest and certs files.
Also, if we do use OVF's formats, could we narrow the scope a bit
and refer to Section 5, "OVF Packages"? I realize this doesn't
change the nature of the reference, but it would help readers locate
the format descriptions.
A platform MAY impose additional archive validation mechanisms or
constraints. To facilitate PDP portability, it is recommended
that any such mechanism be designed with consideration for the OVF
scheme recommended above as well as other common conventions.
(do we want to remove this para ???)
I think we should remove this para. We say enough about
extensibility in other sections that developers should grok that the
PDP is extensible as well. If we aren't going to define what it
means to "design something with consideration for the OVF scheme",
and we aren't going to provide any specific mechanisms for
advertising and describing the PDP extensions, then we're not really
saying anything of value here.
(ELSEWHERE)
1.8 include normative references to YAML, JSON, ZIP, TAR, TGZ, and
OVF
END
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC
that generates this mail. Follow this link to all your TCs in
OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
|