Topology and Orchestration Specification
for Cloud Applications (TOSCA):
Cloud Service Archive (CSAR)
– Version 0.1 –
May 2012
Authors
Gerd Breiter, IBM
Frank Leymann, IBM
Thomas Spatzier, IBM
Copyright Notice
© 2012 International Business Machines Corporation. All rights reserved.
Licence
Permission 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, nondiscriminatory 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).
Status
The 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:
1
Introduction............................................................................................................... 3
2
Manifest File .............................................................................................................. 5
3
Signature Files............................................................................................................ 7
4
Example ..................................................................................................................... 7
5
References ............................................................................................................... 10
Page 2 of 10
1
Introduction
In 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).
/Meta-Inf
/Service-Template
/Types
/Plans
/...
/VirtualImages
/JARs
Figure 1 - Structure of the CSAR
A 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 2 - Structure of the Manifest File
Page 3 of 10
The 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 3 - Providing Metadata For Artifacts
Artifacts 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 4 - Signing Artifacts
Page 4 of 10
A 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 /MetaInf 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.
2
Manifest File
Description: 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.digit
CSAR-Version: digit.digit
Created-By: string
Entry-Service-Template: filename
Sealed: [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.
Page 5 of 10

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_1
Sealed: [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_k
Sealed: [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.
…
Page 6 of 10
3
Signature Files
Description: 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.digit
x-Digest-Manifest: base64 encoding of digest of artifact’s manifest block
name: <path-name>
x-Digest: base64 encoding of the digest of the artifact
...
The name/value pairs are as follows:





4
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
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 (https://ec2.amazonaws.com/?Action=RunInstances); but the
details of this REST API are specified with the operation of the Application Server node type.
Page 7 of 10
start
Payroll.ear
Payroll
Application
...
payrolladm
.jar
deployed_on
installApp
amiedf2cf99
Deployment Artifacts
Application runInstances
Server
...
Payroll.ste
wsadmin
.py
Implementation Artifacts
Figure 5 - Sample Service Template
The 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:
1 <ServiceTemplate id="Payroll"
2
targetNamespace="http://my.com/ste"
3
xmlns:pay="http://my.com/ste/Types">
4
5
<Import namespace="http://my.com/ste/Types"
6
location="http://my.com/ste/Types/PayrollTypes.ste"
7
importType=" http://docs.oasis-open.org/ns/tosca/2011/12"/>
8
9
<Types>
10
...
11
</Types>
12
13
<TopologyTemplate ID="Payroll Template">
14
15
<NodeTemplate id="Payroll Application"
16
nodeType="pay:ApplicationNodeType">
17
...
18
19
<DeploymentArtifacts>
20
<DeploymentArtifact name="PayrollEAR"
21
type="http://docs.oasis-open.org/
22
ns/tosca/2011/12/
23
DeploymentArtifactTypes/CSARref">
24
EARs/Payroll.ear
25
</DeploymentArtifact>
26
</DeploymentArtifacts>
27
28
<ImplementationArtifacts>
29
<ImplementationArtifact operationName="start"
30
type="http://docs.oasis-open.org/
31
ns/tosca/2011/12/
32
ImplementationArtifactTypes/CSARref">
33
JARs/payrolladm.jar
34
<ImplementationArtifact>
35
</ImplementationArtifacts>
36
37
</NodeTemplate>
38
39
<NodeTemplate id="Application Server"
40
nodeType="pay:ApplicationServerNodeType">
Page 8 of 10
41
...
42
43
<DeploymentArtifacts>
44
<DeploymentArtifact name="ApplicationServerImage"
45
type="http://docs.oasis-open.org/
46
ns/tosca/2011/12/
47
DeploymentArtifactTypes/AMIref">
48
ami-edf2cf99
49
</DeploymentArtifact>
50
</DeploymentArtifacts>
51
52
<ImplementationArtifacts>
53
<ImplementationArtifact operationName="installApp"
54
type="http://docs.oasis-open.org/
55
ns/tosca/2011/12/
56
ImplementationArtifactTypes/CSARref">
57
Python/wsadmin.py
58
<ImplementationArtifact>
59
</ImplementationArtifacts>
60
61
</NodeTemplate>
62
63
<RelationshipTemplate id="deployed_on"
64
relationshipType="pay:deployed_on">
65
<SourceElement id="Payroll Application"/>
66
<TargetElement id="Application Server"/>
67
</RelationshipTemplate>
68
69
</TopologyTemplate>
70
71 </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 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 Figure 6): The MANIFEST.MF file is
contained in the Meta-Inf directory. The Payroll.ste file itself is contained in the ServiceDefinitions directory. Also, the PayrollTypes.ste file is in this directory. The content of
the other directories has been sketched before.
Page 9 of 10
/Meta-Inf
MANIFEST.MF
/Service-Definitions
Payroll.ste
PayrollTypes.ste
/Plans
AddUser.bpmn
/EARs
Payroll.ear
/JARs
Payrolladm.jar
/Python
wsadmin.py
Figure 6 - Structure of CSAR Sample
The MANIFEST.MF file is as follows:
Manifest-Version: 1.0
CSAR-Version: 1.0
Created-By: Frank
Entry-Service-Template: /Service-Definitions/Payroll.ste
Sealed: false
Name: Service-Definitions/Payroll.ste
Content-Type: application/vnd.oasis.service_template
Name: Service-Definitions/PayrollTypes.ste
Content-Type: application/vnd.oasis.service_template
Name: Plans/AddUser.bpmn
Content-Type: application/vnd.oasis.bpmn
Name: EARs/Payroll.ear
Content-Type: application/vnd.oasis.ear
Sealed: true
Name: JARs/Payrolladm.jar
Content-Type: application/vnd.oasis.jar
Sealed: true
Name: Python/wsadmin.py
Content-Type: application/vnd.oasis.py
Sealed: true
5
References
[SDN]
Service Template Specification (TOSCA)
[JAR]
JAR File Specification
http://docs.oracle.com/javase/6/docs/technotes/guides/jar/jar.html#JAR%20Manifest
[MF]
Java Manifest File
http://java.sun.com/developer/Books/javaprogramming/JAR/basics/manifest.html
Page 10 of 10