OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

camp message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [camp] PDP structure CAMP-65


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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]