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 "
    
    
    
    
    
    
    
    
    
  X-NONE
  X-NONE
  
   
   
   
   
   
   
   
   
   
  
  MicrosoftInternetExplorer4
  
   
   
   
   
   
   
   
   
   
   
   
  

    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