OASIS | Advancing open standards for the information society



Topology and Orchestration Specificationfor Cloud Applications (TOSCA):Cloud Service Archive (CSAR)– Version 0.1 –May 2012AuthorsGerd Breiter, IBMFrank Leymann, IBMThomas Spatzier, IBMCopyright Notice? 2012 International Business Machines Corporation. All rights reserved.LicencePermission to copy and display the TOSCA Cloud Service Archive specification (the “Specification), in any medium without fee or royalty is hereby granted, provided that you include the following on ALL copies of the Specification, or portions thereof, that you make:A link or URL to the Specification at one of the Authors’ websites.The copyright notice as shown in the Specification.IBM (the “Author”) agree to grant you a license, under royalty-free and otherwise reasonable, non-discriminatory terms and conditions, to their respective essential patent claims that they deem necessary to implement the Specification.THE SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.THE AUTHOR WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THE SPECIFICATION.The name and trademarks of the Author may NOT be used in any manner, including advertising or publicity pertaining to the Specification or its contents without specific, written prior permission. Title to copyright in the Specification will at all times remain with the Author.No other rights are granted by implication, estoppel or otherwise.Abstract: The Cloud Service ARchive is a container file using the ZIP file format. Besides the service template of a cloud application it includes all artifacts required to manage the lifecycle of the corresponding cloud application (i.e. the implementation artifacts of the operations of the node types) as well as all artifacts to execute the cloud application (i.e. the deployment artifacts of the node types like virtual images, EJBs, WSDL files, SQL DDL etc). StatusThe TOSCA Cloud Service Archive (CSAR) specification is provided as-is and for review and evaluation only. The authors hope to solicit your contributions and suggestions in the near future. The authors make no warrantees or representations regarding the specifications in any manner whatsoever.Table of Contents: TOC \o "1-3" 1Introduction PAGEREF _Toc314234745 \h 32Manifest File PAGEREF _Toc314234746 \h 53Signature Files PAGEREF _Toc314234747 \h 74Example PAGEREF _Toc314234748 \h 75References PAGEREF _Toc314234749 \h 10IntroductionIn order to support in a certain environment the execution and management of the lifecycle of a cloud application all corresponding artifacts must be available in that environment. This means that beside the service definition of the cloud application the deployment artifacts and implementation artifacts must be available in that environment. To ease the task of ensuring the availability of all these, this specification defines a corresponding archive format called CSAR (Cloud Service ARchive). Figure SEQ Figure_ \* ARABIC 1 - Structure of the CSARA CSAR is a container file, i.e. it contains multiple files of possibly different file types. These files are typically organized in several subdirectories each of which contains related files (and possibly other subdirectories etc). The current version of the specification supports CSARs that are zip files, typically compressed. Each CSAR must contain a subdirectory called Meta-Inf. This subdirectory must contain a so-called manifest file. This file is named MANIFEST and has the file extension .MF. It represents metadata of the other files in the CSAR. These metadata are given in the format of name/value pairs. These name/value pairs are organized in blocks. Each block provides metadata of a certain artifact of the CSAR. An empty line separates the blocks in the manifest file. Figure SEQ Figure_ \* ARABIC 2 - Structure of the Manifest FileThe first block of the manifest file (Block_0 in the figure) provides metadata of the CSAR itself (e.g. its version, creator etc). Each other block begins with a name/value pair that points to an artifact within the CSAR by means of a pathname. The remaining name/value pairs in a block are the proper metadata of the pointed to artifact. For example, a corresponding name/value pair specifies the MIME-type of the artifact. Figure SEQ Figure_ \* ARABIC 3 - Providing Metadata For ArtifactsArtifacts in a CSAR may be sealed, i.e. all artifacts referred to in such a CSAR are actually contained in the CSAR and they are not just referred to. Sealing is specified at a per artifact level but may be specified globally with a default value; exceptions to the default can be defined on a per artifact level by specifying a corresponding value of the artifact specific property.Figure SEQ Figure_ \* ARABIC 4 - Signing ArtifactsA CSAR or a selective artifact within a CSAR may be signed. When signing an artifact of a CSAR the digest of this artifact as well as the public key of the entity signing the artifact is included in the CSAR together with a corresponding certificate; all of this is included in the so-called signature block file for the signed artifact. The signature block file has an extension dependent on the algorithm used for computing the digest (e.g. .RSA, .DSA), has the name of the signed artifact and is stored in the /Meta-Inf directory. For each signed artifact a second file is stored in the /Meta-Inf directory called the signature file. This file has the name of the signed artifact and an .SF extension. The file contains a digest of the whole manifest file as well as the digest of the block corresponding to the signed artifact. In addition, the block corresponding to the signed artifact contains the digest of the signed artifact too. The reason for this cyclic digests is to improve verifiability of signing artifacts in CSARs. Manifest FileDescription: A CSAR include metadata that allows interpreting the various artifacts within the CSAR properly. This metadata is available in the MANIFEST.MF file of the /Meta-Inf directory of the CSAR. A manifest file contains name/value pairs. The name-part of a name/value pair is followed by a colon, followed by a blank, followed by the value-part of the name/value pair. Neither the name nor the value must contain a colon. Each name/value pair is in a separate line. <name>: <value>Values that represent binary data (like digests, for example) must be base64 encoded. The structure of the manifest file is as follows: Manifest-Version: digit.digitCSAR-Version: digit.digitCreated-By: stringEntry-Service-Template: filenameSealed: [true | false]...The name/value pairs are as follows:Manifest-Version: This is the version number of the manifest file. The value must be “1.0” in the current version of the CSAR specification. CSAR-Version: This is the version number of the CSAR specification. The value must be “1.0” in the current version of the CSAR specification.Created-By: The entity (person, vendor,…) who created the CSAR. Entry-Service-Template: The service template from the /Service-Template directory of the CSAR that is the entry point for the overall cloud application. Note, that a CSAR may contain multiple Service Definition files. One reason for this is completeness, e.g. a Service Definition containing node types referred to by the entry service template might be included in the /Service-Definitions directory to avoid importing it from external locations. Sealed: This is the default value of the Sealed property for the individual entries. The Sealed property defined in the corresponding block of a particular artifact may locally override this default value. Sealing an artifact means that all of its nested artifact definitions refer to artifacts that are included in the CSAR. …In addition, a manifest file contains name/value pairs describing the other files packaged in the CSAR. All name/value pairs describing a particular file of the CSAR are consecutively listed in the manifest. Each name/value pair appears in a separate line of the file. An empty line separates lists of name/value pairs describing different files of the CSAR. The first line of a list of name/value pairs describing a particular file of the CSAR must be a name/value pair that has the name “Name” and the value of which is the path-name of the file described. The second line must be a name/value pair that has the name “Content-Type” describing the type of the file described; the format is that of a MIME type with type/subtype structure. This line may be followed by a name/value pair that has the name “Sealed” specifying (and possibly overriding the default value set globally by the manifest) whether or not the artifact is sealed, i.e. if it all artifacts referred to by the actual artifact are included in the CSAR. Valid values of the “Sealed” pair are ‘true’ or ‘false’. The next line may hold a name/value pair with name “x-Digest” the value of which is the base64 encoded digest of the signed artifact. The other name/value pairs that consecutively follow are file-type specific. Name: <path-name_1>Content-Type: type_1/subtype_1Sealed: [true | false]x-Digest: base64-encoded digest<name_11>: <value_11><name_12>: <value_12>...<name_1n>: <value_1n> ...Name: <path-name_k>Content-Type: type_k/subtype_kSealed: [true | false]x-Digest: base64-encoded digest<name_k1>: <value_k1><name_k2>: <value_k2>...<name_km>: <value_km>The name/value pairs are as follows:Name: The pathname of the file described within the actual CSAR.Note, that the file located at this file may be a reference to an external file. Such a reference is given by a URI that is of one of the URL schemes “file”, “http”, or “https”. Content-Type: The type of the file described. This type is a MIME type complying to the type/subtype structure. Vendor defined subtypes should start as usual with the string “vnd.”. Sealed: If the value is set to ‘true’, all artifacts nested in the artifact that is sealed must be found in the sealed artifact.Note, that an artifact may override the value of the Sealed property defined at the CSAR level. …Signature FilesDescription: A signature file within a CSAR provides metadata about a signed artifact of a CSAR. This metadata is available in the x.MF file of the /Meta-Inf directory of the CSAR, where x is the name of the signed artifact. As like the manifest a signature file contains name/value pairs. The structure of a signature file is as follows: Signature-Version: digit.digitx-Digest-Manifest: base64 encoding of digest of artifact’s manifest blockname: <path-name>x-Digest: base64 encoding of the digest of the artifact...The name/value pairs are as follows:Signature-Version: This is the version number of the signature.x-Digest-Manifest: This is the base64 encoding of the manifest block of the artifact signed. Here, ‘x’ is the name of the algorithm used for computing the digest of the manifest block.name: The pathname of the file signed. x-Digest: This is the base64 encoding of the artifact signed. Here, ‘x’ is the name of the algorithm used for computing the digest of the manifest block.…Example REF _Ref187062822 \h Figure 5 depicts a sample service template of an application, named Payroll.ste. The application is a payroll application written in Java that must be deployed on a proper application server. The service template of the application defines the node template Payroll Application, the node template Application Server, as well as the relationship template deployed_on. The Payroll Application is associated with an EAR file (named Payroll.ear) which is provided as corresponding deployment artifact of the Payroll Application node template. An Amazon Machine Image (AMI) is the deployment artifact of the Application Server node template; this deployment artifact is a reference to the image in the Amazon EC2 environment. The implementation artifacts of some operations of the node templates are provided too; for example, the start operation of the Payroll Application is implemented by a Java API supported by the payrolladm.jar file, the installApp operation of the Application Server is realized by the Python script wsadmin.py, while the runInstances operation is a REST API available at Amazon for running instances of an AMI. Note, that the runInstances operation is not related to a particular implementation artifact because it is available as an Amazon Web Service (); but the details of this REST API are specified with the operation of the Application Server node type. Figure SEQ Figure_ \* ARABIC 5 - Sample Service TemplateThe corresponding node types and relationship types have been defined in the PayrollTypes.ste document, which is imported by the Payroll service template. The following listing provides some of the details:<ServiceTemplate id="Payroll" targetNamespace="" xmlns:pay=""> <Import namespace="" location="" importType=" "/> <Types> ... </Types> <TopologyTemplate ID="Payroll Template"> <NodeTemplate id="Payroll Application" nodeType="pay:ApplicationNodeType"> ... <DeploymentArtifacts> <DeploymentArtifact name="PayrollEAR" type=" ns/tosca/2011/12/ DeploymentArtifactTypes/CSARref"> EARs/Payroll.ear </DeploymentArtifact> </DeploymentArtifacts> <ImplementationArtifacts> <ImplementationArtifact operationName="start" type=" ns/tosca/2011/12/ ImplementationArtifactTypes/CSARref"> JARs/payrolladm.jar <ImplementationArtifact> </ImplementationArtifacts> </NodeTemplate> <NodeTemplate id="Application Server" nodeType="pay:ApplicationServerNodeType"> ... <DeploymentArtifacts> <DeploymentArtifact name="ApplicationServerImage" type=" ns/tosca/2011/12/ DeploymentArtifactTypes/AMIref"> ami-edf2cf99 </DeploymentArtifact> </DeploymentArtifacts> <ImplementationArtifacts> <ImplementationArtifact operationName="installApp" type=" ns/tosca/2011/12/ ImplementationArtifactTypes/CSARref"> Python/wsadmin.py <ImplementationArtifact> </ImplementationArtifacts> </NodeTemplate> <RelationshipTemplate id="deployed_on" relationshipType="pay:deployed_on"> <SourceElement id="Payroll Application"/> <TargetElement id="Application Server"/> </RelationshipTemplate> </TopologyTemplate></ServiceTemplate>The Payroll Application node template specifies the deployment artifact PayrollEAR. It is a reference to the CSAR containing the Payroll.ste file, which is indicated by the …/CSARref type of the <DeploymentArtifact> element. The type specific content is a path expression in the directory structure of the CSAR: it points to the Payroll.ear file in the EARs directory of the CSAR (see REF _Ref187322792 \h Figure 6 for the structure of the corresponding CSAR). The Payroll Application node template also contains an <ImplementationArtifact> element. This element contains information about the implementation of the start operation by pointing to the payrolladm.jar file in the JARs directory of the CSAR. The Application Server node template has a <DeploymentArtifact> called ApplicationServerImage that is a reference to an AMI (Amazon Machine Image), indicated by an .../AMIref type. It provides a Python script (the wsadmin.py file in the Python directory of the CSAR) as implementation of the install operation; the type of the implementation artifact is again a CSAR reference. The corresponding CSAR has the following structure (see REF _Ref187322792 \h Figure 6): The MANIFEST.MF file is contained in the Meta-Inf directory. The Payroll.ste file itself is contained in the Service-Definitions directory. Also, the PayrollTypes.ste file is in this directory. The content of the other directories has been sketched before. Figure SEQ Figure_ \* ARABIC 6 - Structure of CSAR SampleThe MANIFEST.MF file is as follows: Manifest-Version: 1.0CSAR-Version: 1.0Created-By: FrankEntry-Service-Template: /Service-Definitions/Payroll.steSealed: falseName: Service-Definitions/Payroll.ste Content-Type: application/vnd.oasis.service_templateName: Service-Definitions/PayrollTypes.ste Content-Type: application/vnd.oasis.service_templateName: Plans/AddUser.bpmn Content-Type: application/vnd.oasis.bpmnName: EARs/Payroll.ear Content-Type: application/vnd.oasis.earSealed: trueName: JARs/Payrolladm.jar Content-Type: application/vnd.oasis.jarSealed: trueName: Python/wsadmin.py Content-Type: application/vnd.oasis.pySealed: trueReferences[SDN]Service Template Specification (TOSCA)[JAR]JAR File Specification [MF]Java Manifest File ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download