PDP structure CAMP-65

[Alex Heneveld <alex.heneveld@cloudsoftcorp.com>]

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 ???)
* 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.

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 ???)


(ELSEWHERE)

1.8 include normative references to YAML, JSON, ZIP, TAR, TGZ, and OVF

END