Nonnormative Implementer's Recommendations for Interoperable TOSCA Implementations Version 1.0

squealingmunsterΛογισμικό & κατασκευή λογ/κού

30 Οκτ 2013 (πριν από 4 χρόνια και 14 μέρες)

79 εμφανίσεις

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
1

of
31

Non
-
normative I
mplementer's Recommend
ations for Interoperable
TOSCA
Implementations

Version
1.0

Working Draft
01

Revision

0
5

20

May

201
3

Technical Committee:

OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA) TC

TC Chairs:

Paul Lipton (
paul.lipton@ca.com
),
CA Technologies

Simon Moser (
smoser@de.ibm.com
),
IBM

Subcommittee:

Chairs:

Matt Rutkowski (
mrutkows@us.ibm.com
),
IBM

Richard Probst

(
richard.probst@sap.com
),
SAP AG

Editors
:

Dale Moberg (
dmoberg@us.axway.com
),
Axway

Matt Rutkowski

(
mrutkows@us.ibm.com
),
IBM

Related work:

This
provides non
-
normative guidance for implementer interoperability against t
he
specification:



Topology and Orchestration Specification for Cloud Applications Version 1.0
. Latest version.
http://docs.oasis
-
open.org/tosca/TOSCA/v1.0/TOSCA
-
v1.0.html
.

Abstract
:

This document defines non
-
normative guidance and recommendations for cloud providers,
developers and architects that wish to produce interoperable TOSCA


service templates.
Specifically, it will provide information on describing some commonly encountered

Implementation
Artifacts or Deployment Artifacts along with for non
-
normative processing expectations,
properties, schema and samples.

Status:

T
his
Working Draft

(WD) has been produced by one or more TC Members; it has not yet been
voted on by the TC or
approved

as a Committee Draft (Committee Specification Draft or a
Committee No
te Draft). The OASIS document
Approval Process

begins officially with a TC vote
to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and
re
-
approve it any number of times as a Committee Draf
t
.

Initial URI pattern:

http://docs.oasis
-
open.org/tosca/implement/v1.0/csd01/implement
-
v1.0
-
csd01.html

(Ma
naged by OASIS TC Administration; please don’t modify.)


Copyright © OASIS Open

201
3
. All Rights Reserved.


All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual
Property Rights Policy (the "OASIS IPR Poli
cy"). The full
Policy

may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that
comment on or otherwise explain

it or assist in its implementation may be prepared, copied, published,
and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice
and this section are included on all such copies and derivative works. H
owever, this document itself may
implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
2

of
31

not be modified in any way, including by removing the copyright notice or references to OASIS, except as
needed for the purpose of developing any document or deliverable produced by an OASIS Technical
Committee (in which ca
se the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must
be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its suc
cessors
or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRING
E ANY
OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE.

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
3

of
31

Table of Contents

1

Introduction

................................
................................
................................
................................
4

1.1 Termi nol ogy
................................
................................
................................
..............................
4

1.2 Normati ve
References

................................
................................
................................
...............
4

1.3 Non
-
Normati ve References
................................
................................
................................
........
4

2

Describi ng interoperabl e arti facts

................................
................................
................................
.
5

2.1 Variant and i nvariant Artifact Properties

................................
................................
......................
5

2.2 Identity informati on on artifacts
................................
................................
................................
...
6

2.3 Archi ve arti fact

................................
................................
................................
..........................
6

2.3.1 Artifact Type Definition
................................
................................
................................
........
6

2.3.2 Artifact Properties

................................
................................
................................
...............
7

2.3.3
Artifact Context Properties

................................
................................
................................
..
9

2.3.4 Artifact defi nition example

................................
................................
................................
.

11

3

Script invocation conventions

................................
................................
................................
....

14

3.1 Script artifact defi nition
s
................................
................................
................................
...........

14

3.2 Parameter passing conventions for bash scripts

................................
................................
........

15

3.2.1 Passing parameters to scripts implementing Node Type operations

................................
.....

15

3.2.2 Passing parameters to scripts implementing Relationship Type operati ons

..........................

17

3.2.3
Invocati on
conventions for bash s
cri pts

................................
................................
................

18

3.3 Restrictions and Assumptions

................................
................................
................................
..

19

4

Interoperabl e TAR fil es
................................
................................
................................
..............

20

4.1 Prerequisite assumptions
................................
................................
................................
.........

20

4.2 TAR Descriptor

................................
................................
................................
.......................

21

5

TOSCA Model Extraction and Processing Gui dance

................................
................................
...

23

5.1 XML Navigation
................................
................................
................................
.......................

23

5.1.1 Illustration of Navi gation for SugarCrm Initial Model

................................
............................

26

5.2 Sequencing Operati on Invocation
................................
................................
.............................

28

Appendix A.

Acknowledgements
................................
................................
................................
...

30

Appendix B.

Revision History
................................
................................
................................
........

31


implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
4

of
31

1

Introduction

[All
text is norm
ative unless otherwise labeled]

1.1

Terminology

The key words “
MUST

,

MUST NOT

,

REQUIRED

,

SHALL

,

SHALL NOT

,

SHOULD

,

SHOULD
NOT

,

RECOMMENDED

,

MAY

, and

OPTIONAL
” in this document are to be interpreted as described
in
[RFC2119]
.

1.2

Normative References

[RFC2119]

Bradner,

S.,


Key words for use in RFCs to Indicate Requirement Levels

,
BCP
14,
RFC 2119, March 1997.

http://www.ietf.org/rfc/rfc2119.txt
.

[TOSCA
-
1.0]

OASIS Topology and Orchestration Specification for Cloud Applications

Version
1.0, Committee Specification 02
,

09 May 2013.

http://docs.oasis
-
open.org/tosca/TOSCA/v1.0/cs02/TOSCA
-
v1.0
-
cs02.pdf

1.3

Non
-
Normative References

[GNU
-
TAR]

GNU Basic Tar Format:
http://www.gnu.org/software/tar/manual/html_node/Standard.html

[GNU
-
BASH]

GNU Bash Reference Manual:
http://www.gnu.org/software/bash/manual/bashref.html



implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
5

of
31

2

Describing interoperable artifacts

TOSCA makes use of artifacts in two different ways:
Implementation Artifacts

define the executable
artifacts that implement the operations of Node
-

and Relationship Type interface operations, such as
scripts or web appli
cations implementing REST interfaces;
Deployment Artifacts

define the artifacts used
for materializing the real
-
world instances of components of a TOSCA Service Template, for example the
software installable for an “Application Server” Node Template define
d in a Service Template.

An artifact for use is TOSCA Service Templates is a re
-
usable entity, i.e. an artifact like a file or software
installable gets created and defined once and can then be used in many different contexts, for example
for many software

installations. Artifacts have a certain type and are typically described by a set of
specific properties. In addition, an artifact definition typically points to the actual artifact proper, for
example a file contained in a TOSCA Cloud Service Archive. In

some cases, the XML definition of an
artifact might also contain the artifact proper inline (such as an inline definition of a script) instead of
pointing to a separate artifact file. The former style, i.e. providing a reference to a separate file, is the

preferred option, though.

Each type of artifact requires specific processing and handling of its properties. The way in which different
types of artifacts have to be interpreted and processed is described further down in this document for a
core set of Ar
tifact Types.

2.1

Variant and invariant Artifact Properties

Properties of an artifact can be distinguished between such that are invariant for an artifact


i.e. those
properties do not change across the different contexts in which the artifact is used


and s
uch that are
variant across different contexts. For example, an archive containing
some installable

s
oftware might
also
contain properties defining the version of the software or the size of the install footprint. Such properties
would be considered invari
ant since they are the same for each installation of the respective software. In
contrast, the path where the software gets installed would be considered variant information, since for
each installation the desired install path can be selected.

Invariant p
roperties are defined in the Properties element of ArtifactTemplate elements, since the TOSCA
specification defines Artifact Templates are the means for describing concrete, re
-
usable artifacts. The
structure of the properties of an Artifact Template is de
fined by the
PropertiesDefinition

element of
the
ArtifactType

element defining the type of the Artifact Template.

Variant properties are defined at the place where an artifact described by an Artifact Template gets used.
In cases where an artifact is used as an Implementation Artifact for a Node
-

or Relationship Type
interface operations, the variant properties would
be specified
included in
the body of an
ImplementationArtifact

element. In cases where an artifact is a Deployment

Artifact, the variant
properties would be defined in the body of a
DeploymentArtifact

element of a NodeTemplate
element or a NodeTypeImplemen
tation element. The structure of the variant properties that are valid
inside
DeploymentArtifact

or
ImplementationArtifact

elements is not explicitly defined in a
TOSCA Definitions document, but is dependent on the type of Artifact Template the respective
Deployment
-

or Implementation Artifact refers to. For each type of artifact, the structure or valid variant
and invariant properties is specified
provided
by this document.

NOTE:
By
convention
, the properties elements to appear in Artifact Templates (i.
e. invariant properties)
will end with the name “Properties”, and the properties elements to appear inside Deployment Artifacts or
Implementation Artifacts will end with the name “ContextProperties”. For example, the invariant properties
element for the “A
rchiveArtifact” Artifact Type defined further down in this document will be called
“ArchiveArtifactProperti es”, while the variant properties element will be called
“ArchiveArtifactContextProperti es”.

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
6

of
31

2.2

Identity information on artifacts

Some properties of art
ifacts are typically used for describing the identity of the artifact, such as the
product name and version of the software contained in an artifact. Such information allows for describing
and the later selecting the appropriate artifact for a
particular
u
se case. Since such identity information
applies to each use of an artifact, it is considered part of the invariant properties of an artifact. Identity
information will thus appear in the invariant properties element contain in Artifact Templates.

The foll
owing pseudo
schema
defines the structure of identity properties:


<IdentityProperties>



<Property name="xs:string" value="xs:anySimpleType"/> *


</IdentityProperties>


The
IdentityProperties

element itself is optional in each properties element of an

Artifact Template.
Each identity property is defined by a separate
Property

element.


The
Property

element has the following properties:


Property Name

Property Description

name

This attribute
contains

a descriptive name of the property and should be
unique within the containing
IdentityProperties

element.

value

This attribute
contains

the value of the property.

cor exampleI the following identity properties describe the software product name and version of
慮a

imaginary


software installable:

01

<IdentityProperties>

02


<Property name="ProductName" value="ExampleSoftware"/>

03


<Property name="ProductVersion" v
alue="1.0.1"/>

04

</IdentityProperties>

2.3

Archive artifact

Archives can be used to extract complete file hierarchies which can then be deployed in many
environments. In special cases, archives can also be used for extracting installed software component file

hierarchies and deploying the same component in different virtual machines, avoiding the need for
cloning and maintaining entire images and cleanly separating the distribution of software component files
from open source and other 3rd party files.

Archive

Artifacts provide some general information, like the type of archive (e.g. ZIP or TAR), the base
path under which the archive has been created, or the path to which the archive is to be extracted when
used in a specific context. In addition, archives migh
t provide metadata such as user or group ownership
or permissions for single files within the archive.

Archive Artifacts are typically used as Deployment Artifacts for Nodes defined in TOSCA Service
Templates.

2.3.1

Artifact Type Definition

The following XML snippet shows the definition of the
ArchiveArtifact

Artifact Type:

<ArtifactType name="ArchiveArtifact">


<PropertiesDefinition element="ArchiveArtifactProperties"/>

</ArtifactType>

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
7

of
31

2.3.2

Artifact Properties

The following pseudo schema
shows
t
he structure of invariant properties of Archive Artifacts that are valid
inside Artifact Templates referring to the
ArchiveArtifact

Artifact Type:

01

<ArchiveArtifactProperties>

02


03


<IdentityProperties> ... </IdentityProperties> ?

04



05


<ArchiveIn
formation archiveReference="xs:anyURI"

06


archiveType="xs:string">

07



08


<UserMap>

09


<User name="xs:string" id="xs:unsignedInt"/> +

10


</UserMap> ?

11


12


<GroupMap>

13


<Group name="xs:string" id="xs:unsigne
dInt"/> +

14


</GroupMap> ?

15



16


<ContentSourceLocation path="xs:string">

17


<Segment name="xs:string"

18


userID="xs:unsignedInt"?

19


groupID="xs:unsignedInt"?

20


permissions="xs:string"?/> *

21


</ContentSourceLocation> ?

22


23


</ArchiveInformation> *

24


25

</ArchiveArtifactProperties>

The
ArchiveArtifactProperties

element provides descriptive information about the actual content
of the artifact proper. This information can be used by an i
mplementation to appropriately process the
artifact.

The
ArchiveArtifactProperties

element has the following properties:



IdentityProperties
:
This element
is optional
contains a list of descriptive properties a
bout the
identity of the artifact (see also
section 1.2).



ArchiveInformation
: This element provides metadata about one archive referenced by the
ArtifactTemplate

element containing the
ArchiveArtifactProperties

element. The
ArchiveInformation

element has the following properties:



archiveReference
: T
his attribute
provides,
by means of a URI
,

the actual archive described by
the
ArchiveInformation

element. Its value corresponds to a file included in the
ArtifactReferences

section of the
ArtifactTemplate

element containing the
ArchiveArtifactProperties

e
lement.



archiveType
: This attribute
contains

the type of the referenced archive, e.g. “tar” or “zip”.



UserMap
: This element
is optional
contains a list user name to user ID mappings (in terms of
standard Unix operating system users) that are relevant for t
he archive, i.e. for
providing
exactly
the ownership of directories and files inside the archive.

If
this

information
is provided, it
would
be used during deployment of the archive to make sure the
respective operating system users exist (ideally with the
same numeric IDs) to allow for proper
use of the deployed content. If it is not possible to allocate the same numeric IDs during
deployment, and implementation will have to update the numeric IDs of deployment paths and
archive content with the ones it was

able to allocate.

Some packaging formats like TAR allow for preserving file attributes like ownership or
permissions when extracting content from the source system, so during deployment it has to be
made sure that a mapping to respective identities on the

target system is possible.



implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
8

of
31

Each entry is
a

separate, nested
User

element. The
User

element has the following properties:



name
: This attribute
contains
the symbolic name of the user.



id
: This attribute
contains
the numeric id of the user.



GroupMap
: This
element contains a
n optional

list group name to user ID mappings (in terms of
standard Unix operating system user groups) that are relevant for the archive, i.e. for
providing
the
exact ownership of directories and files inside the archive.

If
provided
, th
is information
would
be used during deployment of the archive to make sure the
respective operating system groups exist (ideally with the same numeric IDs) to allow for proper
use of the deployed content. If it is not possible to allocate the same numeric
IDs during
deployment, and implementation will have to update the numeric IDs of deployment paths and
archive content with the ones it was able to allocate.

Each entry is a separate, nested
Group

element. The
Group

element has the following
properties:



name
: This attribute
contains
the symbolic name of the group.



id
: This attribute
contains
the numeric id of the group
.




ContentSourceLocation
: This element
optionally
defines the location on the source system
from which the content of the archive has been
extracted.

If
provided
, this location
would
also be used as default deployment location of the content on any
target system.


The
ContentSourceLocation

element has the following properties:



path
: This attribute specifies the absolute filesystem path from
which the content of the
archive has been extracted. For example a value of “/usr/mypath” would indicate that all
content of the archive has been extract from within directory “/usr/mypath”.



S
egment
: This element specifies a segment (path segment) of the c
ontent source location
and allows for capturing detailed ownership and permissions for each segment. If specified,
this information
would
be used during deployment to make sure the same ownership and
permissions get applied to the target system where the a
rchive content gets deployed.

For each
segment

of the path specified in the
path

attribute of the
ContentSourceLocation

element, a corresponding
Segment

element
would
be present.
For example, for a path value of “/a/b/c” three
Segment

elements (with
name

v
alues of “/a”,
“/a/b”, or “/a/b/c” respectively) would be specified. If no
Segment

element is specified for one
of the path segments, default ownership and permissions
would be

assumed during
deployment.


The
Segment

element has the following properties:



n
ame
: This attribute
contains
the name of the segment, e.g. “/usr/mypath”.



userID
: This attribute
contains
the owning user of the segment by means of the numeric
ID of the user. The corresponding symbolic name can be resolved by means of the
UserMap

element.



groupID
: This attribute
contains
the owning group of the segment by means of the
numeric ID of the group. The corresponding symbolic name can be resolved by means of
the
GroupMap

element.

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
9

of
31



permissions
: This attribute
contains
the filesystem permis
sion for the segment in terms
of standard Unix permissions (i.e. read, write and execute permission for the owning
user, owning group and others).

2.3.3

Artifact Context Properties

Context properties of an Archive Artifact take effect during the use and deployment of an
a
rchive in a
particular

context. In many cases, information provided with the Archive Artifact Template in the form of
the
ArchiveArtifactProperties

element is also u
sed as default settings for the deployment of
archives (e.g. the content of an archive will be default be deployed to the same location from which the
content has been extracted on the source system as
provided
in the
ContentSourceLocation

element).

Archi
veArtifact
Context
Properties

allow for overriding some of these settings. For example,
other symbolic user or group names can be defined for

numeric IDs used in the archive, or a deployment
location different from the source location can be
provided
.

The fo
llowing pseudo schema
shows
the structure of variant properties of Archive Artifacts that are valid
inside Deployment
-

or Implementation Artifacts referring to Artifact Templates of Artifact Type
ArchiveArtifact
:

01

<ArchiveArtifactContextProperties>

02


0
3


<ArchiveDeploymentInformation archiveReference="xs:anyURI">

04



05


<UserMap>

06


<User name="xs:string" id="xs:unsignedInt"/> +

07


</UserMap> ?

08


09


<GroupMap>

10


<Group name="xs:string" id="xs:unsignedInt"/> +

11


</GroupM
ap> ?

12



13


<ContentDeploymentLocation path="xs:string">

14


<Segment name="xs:string"

15


userID="xs:unsignedInt"?

16


groupID="xs:unsignedInt"?

17


permissions="xs:string"?/> *

18


</ContentDeployme
ntLocation> ?

19


20


</ArchiveDeploymentInformation> *

21


22

</ArchiveArtifactContextProperties>

The
ArchiveArtifactContextProperties

element provides descriptive information for deployment
of an artifact. This information

can

be used by an implementation to appropriately deploy the artifact. The
ArchiveArtifactContextProperties

element has the following properties:



ArchiveDeploymentInformation
: This element provides directives for the deployment of one
archive referenced by the ArtifactTemplate referenced by the Deployment
-

or Implementation Artifact
containing the
ArchiveArtifactContextProperties

element. The
ArchiveDeploymentInformation

eleme
nt has the following properties:



archiveReference
: This attribute
provides,
by means of a URI
,

the actual archive described by
the
ArchiveDeploymentInformation

element. Its value corresponds to a file included in the
ArtifactReferences section of the Artif
actTemplate element referenced by the Deployment
-

or
Implementation Artifact containing the
ArchiveArtifactContextProperties

element.



UserMap
: This element
optionally
contains a list user name to user ID mappings (in terms of
standard Unix operating system

users) that are relevant for the deployment of the archive.

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
10

of
31

If

supplied
, this information
would
override

the

mappings defined by a corresponding
ArchiveInformation

element in the Artifact Template referenced by the Deployment
-

or
Implementation Artifact c
ontaining the
ArchiveArtifactContextProperties

element and
would
be used during deployment of the archive to make sure the respective operating system
users exist (ideally with the same numeric IDs) to allow for proper use of the deployed content
.


Each entry
would be
a separate, nested
User

element. The
User

element has the following
properties:



name
: This attribute
contains
the symbolic name of the user.



id
: This attribute
contains
the numeric id of the user.



GroupMap
: This element
optionally
conta
ins a list group name to user ID mappings (in terms of
standard Unix operating system user groups) that are relevant for the archive, i.e. for
declaring
exactly the ownership of directories and files inside the archive.

If
supplied
, this information overri
des mappings defined by a corresponding
ArchiveInformation

element in the Artifact Template referenced by the Deployment
-

or
Implementation Artifact containing the
ArchiveArtifactContextProperties

element and
would
be used during deployment of the archive
to make sure the respective operating system
groups exist (ideally with the same numeric IDs) to allow for proper use of the deployed content.


Each entry is separate
d by a

nested
Group

element. The
Group

element has the following
properties:



name
: This at
tribute
contains
the symbolic name of the group.



id
: This attribute
conta
i
ns
the numeric id of the group.



ContentDeploymentLocation
: This element
optionally
defines the location to which the
content of the archive has to be extracted. If specified, this information overrides the location
specified in the
ContentSourceLocation

element in a corresponding
ArchiveInformation

element in the Artifact Template refere
nced by the Deployment
-

or Implementation Artifact
containing the
ArchiveArtifactContextProperties

element.

Note
: If neither
ContentSourceLocation

nor
ContentDeploymentLocation

are
provided
for an archive, an implementation
might

choose to deploy the conte
nts of the
archive to a custom location or it
might
reject the respective TOSCA Definitions
document.

The
ContentDeploymentLocation

element has the following properties:



path
: This attribute
contains
the absolute filesystem path to which the content of the

archive
has to be extracted.



Segment
: This element
contains
a segment (path segment) of the content deployment
location and allows for
providing
detailed ownership and permissions for each segment.

If
provided
, this information

would

be used during deployment to make sure the same
ownership and permissions get applied to the system where the archive content gets
deployed.


The
Segment

element has the following properties:



name
: This attribute
contains
the name of the segment, e.g. “/
usr/mypath”.

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
11

of
31



userID
: This attribute
contains
the owning user of the segment by means of the numeric
ID of the user. The corresponding symbolic name can be resolved by means of the
UserMap

element.



groupID
: This attribute
contains
the owning group of the se
gment by means of the
numeric ID of the group. The corresponding symbolic name can be resolved by means of
the
GroupMap

element.



permissions
: This attribute
contains
the filesystem permission for the segment in terms
of standard Unix permissions (i.e. read
, write and execute permission for the owning
user, owning group and others).

2.3.4

Artifact definition e
xample

The following example outlines the use of an Archive Artifact as a Deployment Artifact for the database
content of an imaginary application. The appli
cation “MyApplication” makes use of a database
“MyDatabase”, the content of which is deployed in a directory “/myapplication/mydatabase”. The content
of the database is captured as a TAR file so it can be used as pre
-
canned content for each deployment of
t
he sample application.

The following XML snipped shows the definition of the respective
ArtifactTemplate

element
with a
base

type

ArchiveArtifact


for the database content component of an overall TOSCA model:

01

<Definitions id="MyDefinitions" name="My De
finitions"

02


targetNamespace="http://www.example.com/ArchiveArtifactExample"

03


xmlns="http://docs.oasis
-
open.org/tosca/ns/2011/12"

04


xmlns:my="http://www.example.com/ArchiveArtifactExample"

05


xmlns:tbase="http://docs.oasis
-
open.org/tosca/ns/2011/12
/ToscaBaseTypes">

06



07


<ArtifactTemplate id="MyDatabaseContentArchive"

08


type="tbase:ArchiveArtifact">

09


<Properties>

10


<ArchiveArtifactProperties>

11


<ArchiveInformation archiveReference="files/MyDatabaseConte
nt.tar"

12


archiveType="tar">

13


<UserMap>

14


<User name="myappadm" id="1001"/>

15


</UserMap>

16


<GroupMap>

17


<Group name="myappgrp" id="1001"/>

18


</GroupMap>

19


<ContentSourceLocation path="/myapplication/mydatabase">

20


<Segment name="/myapplication"

21


userID="1001"

22


groupID="1001"

23


permissions="755"/>

24


<Segment name="/myapplica
tion/mydatabase"

25


userID="1001"

26


groupID="1001"

27


permissions="754"/>

28


</ContentSourceLocation>

29


</ArchiveInformation>

30


</ArchiveArtifactProperties>

31


</Properties>

32


33


<ArtifactReferences>

34


<ArtifactReference reference="files/MyDatabaseContent.tar"/>

35


</ArtifactReferences>

36


37


</ArtifactTemplate>

38


39

</Definitions>

The
Artifact
Template

“MyDatabaseContentArchi ve” declares that it is of
base
type

ArchiveArtifact

.

It is assumed that this Artifact Type is defined in namespace “http://docs.oasis
-
open.org/tosca/ns/2011/12/ToscaBaseTypes” which is prefixed with “tbase” in the current example.

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
12

of
31

The
ArtifactTemplate

references a TAR file “MyDatabas
eContent.tar” contained in the “files”
directory of the
TOSCA defined Cloud Service Archive (
CSAR
)

containing the shown TOSCA Definitions
document. Inside the
ArchiveArtifactProperties

element, additional metadata for this TAR file is
provided. A
User

and
G
roup

(“myappadm” and “myappgrp”) are required to exist when using the content
of the archive, since files inside the archive are owned by this user, and since the overall application
assumes that access right are set appropriately.

I
f i
t is further
shown
,

that the content of the TAR file stems from a location “/myapplication/mydatabase”

and b
oth
S
egments

of this path are owned by the user with numeric ID “1001” (which maps to
“myappadm”) and group with numeric ID “1001” (which maps to “myappgrp”). The top
-
level segment has
permission flags of “755” set; the second segment has permission flags “754” set.

The TAR file itself has been packaged in a way that filesystem ownership and permissions of contained
content are persisted as found in the source system (e
.g. by invoking the tar command with options “
--
numeric
-
owner” and “
-
p”). This way it can be ensured that all attributes of content are exactly as expected
by the application when the database content is deployed in another environment.

The following XML s
nippet shows a
NodeTypeImplementation

for the “MyDatabaseContent” Node
Type that uses the Artifact Templat
e defined above as a
Deployment
Artifact

and uses all the
information provided in the Artifact

Template as default deployment settings:

01

<Definitions

id="MyDefinitions" name="My Definitions"

02


targetNamespace="http://www.example.com/ArchiveArtifactExample"

03


xmlns="http://docs.oasis
-
open.org/tosca/ns/2011/12"

04


xmlns:my="http://www.example.com/ArchiveArtifactExample"

05


xmlns:tbase="http://docs.oasis
-
open.org/tosca/ns/2011/12/ToscaBaseTypes">

06



07


<NodeTypeImplementation name="MyDatabaseContentImpl"

08


nodeType="my:MyDatabaseContent">

09


...

10


<DeploymentArtifacts>

11


<Deploy
mentArtifact name="DatabaseContent
-
Archive"

12


artifactRef="my:MyDatabaseContentArchive"

13


artifactType="tbase:ArchiveArtifact"/>

14


</DeploymentArtifacts>

15


</NodeTypeImplementation>

16


17

</Def
initions>

The Deployment Artifact “DatabaseContent
-
Archi ve” references the Artifact Template
“MyDatabaseContentArchi ve” defined earlier. It does not include any additional context properties.
Therefore, the archive content will be deployed to the same loca
tion as
provided
in the
ArchiveArtifactProperties element of the referenced Artifact Template, i.e. “/myapplication/mydatabase”.

During deployment, a user “myappadm” and group “myappgrp” with numeric IDs of “1001” w
ould

be
created and filesystem ownership

and permissions of the deployment location will be set accordingly.
Finally, the referenced TAR file will be extracted with the option to keep ownership ship and permission
settings as persisted within the archive (for example by invoking the tar command
with options “
--
same
-
user”).

The following XML snippet shows a variation of the
NodeTypeImplementation

for the
“MyDatabaseContent” Node Type that uses the Artifact Template defined above as a Deployment
Artifact, but overrides some settings for deployment:

01

<Definitions id="MyDefinitions" name="My Definitions"

02


targetNamespace="http://www.example.com/ArchiveArtifactExample"

03


xmlns="http://docs.oasis
-
open.org/tosca/ns/2011/12"

04


xmlns:my="http://www.example.com/ArchiveArtifactExample"

05


xmlns:tba
se="http://docs.oasis
-
open.org/tosca/ns/2011/12/ToscaBaseTypes">

06



07


<NodeTypeImplementation name="MyDatabaseContentImpl2"

08


nodeType="my:MyDatabaseContent">

09


...

10


<DeploymentArtifacts>

11


<
DeploymentArtifact name="DatabaseContent
-
Archive2"

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
13

of
31

12


artifactRef="my:MyDatabaseContentArchive"

13


artifactType="tbase:ArchiveArtifact">

14


<ArchiveArtifactContextProperties>

15


<Archive
DeploymentInformation

16


archiveReference="files/MyDatabaseContent.tar">

17


<ContentDeploymentLocation path="/myapp/mydb">

18


<Segment name="/myapp"

19


userID="1001"

20


groupID="1001"

2
1


permissions="755"/>

22


<Segment name="/myapp/mydb"

23


userID="1001"

24


groupID="1001"

25


permissions="754"/>

26


</ContentDeploymentLocation>

27


</Arch
iveDeploymentInformation>

28


</ArchiveArtifactContextProperties>

29


</DeploymentArtifact>

30


</DeploymentArtifacts>

31


</NodeTypeImplementation>

32


33

</Definitions>

The Deployment Artifact “DatabaseContent
-
Archi ve2” references the Art
ifact Template
“MyDatabaseContentArchi ve” defined earlier. It includes additional context properties inside the
ArchiveArtifactContextProperties

element to
declare
that the archive content has to be
deployed to a different location “/myapp/mydb”. For each
segment of the new deployment path, the
respective ownership and permissions are
provided
(using the same user and group as defined in the
Artifact Template).

During deployment, a user “myappadm” and group “myappgrp” with numeric IDs of “1001” will be crea
ted,
a directory “/myapp” and sub
-
directory “mydb” will be created and filesystem ownership and permissions
will be set accordingly. Finally, the referenced TAR file will be extracted with the option to keep ownership
ship and permission settings as persis
ted within the archive (for example by invoking the tar command
with options “
--
same
-
user”).




implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
14

of
31

3

Script invocation conventions

The current interoperability use case based on SugarCRM provides simple scripts as Implementation
Artifacts for lifecycle operations of Node Types. In order to invoke those scripts in an interoperable
manner, conventions need to be followed by the differen
t TOSCA container implementations.

For example, it has to be defined how references to individual scripts in a CSAR are made, how
parameters are passed between a script and an invoker, how such parameters are identified in a service
template etc..

Each script language will require the definition of such a “binding”. Because the interoperability use case
only makes use of bash scripts, this recommendation at hand describes conventions for bash scripts only.

3.1

Script artifact definitions

The following
Artifact Type called ScriptArtifact defines the type of artifacts that are scripts:


<ArtifactType name="ScriptArtifact">


<documentation>Script Artifact</documentation>


<DerivedFrom typeRef="RootArtifactType"/>


<PropertiesDefinition element="S
criptArtifactProperties"/>


</ArtifactType>

The
ScriptArtifactProperties

element is defined as follows

and

assumes
that a script always has
a script language and a primary script:

<xs:element name="ScriptArtifactProperties">


<xs:complexType>


<xs:comp
lexContent>


<xs:extension base="tScriptArtifactProperties"/>


</xs:complexContent>


</xs:complexType>


</xs:element>



<xs:complexType name="tScriptArtifactProperties">


<xs:complexContent>


<xs:extension base="tExtensibleElements">


<xs:
sequence>


<xs:element name="ScriptLanguage" type="xs:anyURI"/>


<xs:element name="PrimaryScript" type="xs:string"/>


</xs:sequence>


</xs:extension>


</xs:complexContent>


</xs:complexType>

The actual value of the
ScriptLanguage

element has
impact on the invocation convention, parameters
passing, etc. The
PrimaryScript

specifies the “entry script” to be invoked in cases where multiple files
are referenced by an
ArtifactTemplate

(e.g. if the main script brings with it additional helper or libr
ary
files).

By referring to the
“ScriptArtifact”
Artifact Type in its type attribute, th
e following defines an
Artifact
Template

that is a script:

<ArtifactTemplate id="at
-
c1ab1a58
-
91f1
-
49ec
-
a3e0
-
57f46e3d72e1“


type="ns1:ScriptArtifact">


<Properties>


<n
s1:ScriptArtifactProperties


xmlns:ns1="http://docs.oasis
-
open.org/tosca/ns/2011/12/ToscaBaseTypes"


xmlns="http://docs.oasis
-
open.org/tosca/ns/2011/12/ToscaBaseTypes">


<ScriptLanguage>sh</ScriptLanguage>

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
15

of
31


<PrimaryScript>scripts/MySQL/configure.sh
</PrimaryScript>


</ns1:ScriptArtifactProperties>


</Properties>


<ArtifactReferences>


<ArtifactReference reference="scripts/MySQL">


<Include pattern="configure.sh"/>


</ArtifactReference>


</ArtifactReferences>

</ArtifactTemplate>

The script is a s
hell scripts as indicated by the “sh” value of the
ScriptLanguage

element. The primary
script is the

scripts/MySQL/configure.sh
” (
i.e. the configure.sh shell script stored in the

scripts/MySQL


directory of the actual CSAR file
)
. The script defined by t
he actual Artifact Template is the
“configure.sh”
script itself, as defined by the
ArtifactReference

element; this element uses an Ant file
-
set like
notation. The value of the reference attribute can specify a file or directory. If the reference attribute
points
to a directory, files in the directory to be referenced by the
ArtifactTemplate

are specified thru include
and exclude patterns. Relative URIs in
ArtifactTemplate

elements are interpreted relative to the
CSAR root directory.


3.2

Parameter p
assing
conventions for bash s
cripts

3.2.1

Passing
p
arameters to
s
cripts
i
mplementing Node Type
o
perations

Parameters are passed to a script as environment variables. The invoker of the script has to make the
parameter values required by the script available from the pr
operty values of the node instance the script
implements an operation from. These property values are copied into environment variables in the
environment of the invoked script. “Context parameters” that are required by most scripts (like
PublicIP
)
are not

expected to be modeled explicitly as properties. Nevertheless, the invoker of the script has to
make such context variables available as corresponding environment parameters. The script can access
these parameters by name using the
$<name>

notation. The s
cripts are assumed to be executed on the
target environment, i.e. within the virtual machines created during service instantiation.

For example, the

configure.sh


script within the

scripts/SugarCRMApplication


subdirectory
of the SugarCRM CSAR contains
the following lines of code:

...

sed
-
i
-
e 's/YOURKEY/'${
SugarCRMKey
}'/' $ResponseFile

sed
-
i
-
e 's/SITEADMINPWD/'${
AdminPassword
}'/' $ResponseFile

sed
-
i
-
e 's/SITEADMINUNAME/'${
AdminUser
}'/' $ResponseFile

...

The highlighted environment variables used b
y the script are the elements of the property definition of the

SugarCRMApplication


node type:

Recommendation
s
:


Use the
ScriptArtifact

Artifact Type to define the scripts you need as Artifact
Templates referring to these scripts.


The nested
ScriptLanguage

element has to indicate the script language used by the
primary script.


The
PrimaryScript

element must also be s
pecified in case the artifact template
includes a single script only.


References to artifacts are either dereferencable URLs or relative URIs with the root
directory of the CSAR encompassing the element using this relative URI.


implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
16

of
31


<NodeType name="SugarCRMApplication">


<DerivedFrom typeRef="ns1:ApacheWebApplication"/>


<PropertiesDefinition element="tns:SugarCRMApplicationProper
ties"/>


...


</NodeType>

The

SugarCRMApplicationProperties


is defined as the following structure:


<xs:complexType name="tSugarCRMApplicationProperties">


<xs:sequence>


<xs:element name="
SugarCRMKey
" type="xs:string">


</xs:element>


<xs:element default="admin" name="
AdminUser
" type="xs:string">


</xs:element>


<xs:element default="admin" name="
AdminPassword
" type="xs:string">


</xs:element>


...


</xs:element>


</xs:sequence>


</xs:complexType>

The f
ollowing node type implementation of the

SugarCRMApplication


node type includes an
implementation artifact of the
configure

operation of the
lifecycle

interface:

<NodeTypeImplementation name="SugarCRMApplicationImplementation"



nodeType="tns:SugarCRMApplication">


...


<ImplementationArtifact


artifactRef="tns:at
-
7ccb9ba4
-
edd6
-
4ed8
-
9c11
-
5f912f1c31a6"


artifactType="ns2:ScriptArtifact"


interfaceName="h
ttp://docs.oasis
-
open.org/tosca/ns/2011/12/


interfaces/
lifecycle
"


operationName="
configure
"/>


...


</NodeTypeImplementation>

This implementation artifact is exactly the

configure.sh


script within the

scripts/
SugarCRMApplication

subdirectory that contains the references to the corresponding
properties definition:

<ArtifactTemplate id="at
-
7ccb9ba4
-
edd6
-
4ed8
-
9c11
-
5f912f1c31a6"


type="ns2:ScriptArtifact">


<Properties>


<
ns2:ScriptArtifactProperties ...>


<ScriptLanguage>sh</ScriptLanguage>


<PrimaryScript>
scripts/SugarCRMApplication/configure.sh


</PrimaryScript>


</ns2:ScriptArtifactProperties>


</Properties>


<ArtifactReferences>


<A
rtifactReference reference="scripts/
h
SugarCRMApplication">


<Include pattern="configure.sh"/>


<Include pattern="config_si.php"/>


<Include pattern="config.php"/>


</ArtifactReference>


</ArtifactReferences>


</ArtifactTemplat
e>


implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
17

of
31


3.2.2

Passing
p
arameters to
scripts i
mplementing
Relationship Type
o
perations

In case the script to be invoked implements on operation of a source interface or a target interface of a
Relationship Type, the parameters passed to the script as environment parameters are as

before all
properties of the relationship instance. These parameters have the name of the corresponding properties
definition of the relationship type. The script can access these parameters by name using the
$<name>

notation.

In addition, all properties as well as context parameters of the source node instance as well as that of the
target node instance are passed to the script as environment parameters. The names of the environment
parameters corresponding to the source node i
nstance are prefixed by
Source_
, those corresponding to
the target node instance are prefixed by
Target_
. The script can access these parameters by name
using the
$Source_<name>

notation and the
$Target_<name>

notation

The following example is from the

co
nnectToDatabase.sh


script of the directory

scripts/MySQLDatabaseConnection


subdirectory:

...

sed
-
i
-
e 's/YOURDBHOST/'
${Target_
PublicIP}:${Target_mySqlPort}'/'
$ResponseFile


sed
-
i
-
e 's/YOURDBNAME/'
${Target_
DBName}'/' $ResponseFile



sed
-
i

-
e 's/YOURDBUSER/'
${Target_
DBUser}'/' $ResponseFile

...


Recommendation
s
:


Parameters are passed to a script as environment variables.


Each property value (i.e. instance of the properties definition of the corresponding node
type) is passed to the script.


These environment parameters have the same name
as the elements of the properties
definition.


In addition, special context parameters required by most scripts are passed as
environment variables.
ToDo: Define these context variables for V1.0!


The script can access the parameters as
$<name>
.

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
18

of
31


3.2.3

Invocation
conventions for bash s
cripts

The script to be
invoked
(typically the
PrimaryScript

of an
ArtifactTemplate
) has to be made
available in the target environment, i.e. where it has to be invoked. The same is true for all potential files
(scripts, html,
etc.)

that are required by the script to be invoked (so
-
called “helper files”). Then, a new
bash is created and
all parameters are passed to the scripts as environment parameters (see before).
Next, the script to be executed is invoked. On return of the script, potential return parameters are
processed; such return parameters may have been written to environment var
iables by the script itself.


Recommendation
s
:


Parameters are passed to a script as environment variables.


Each property value of the relationship instance (i.e. values of the properties definition
of the corresponding relat
ionship type) is passed to the script.


These environment parameters have the same name as the elements of the properties
definition.


The script can access the parameters as
$<name>
.


Each property value of the source node instance (i.e. instance of the pr
operties
definition of the corresponding node type) is passed to the script.


These environment parameters have the same name as the elements of the properties
definition of node type but prefixed by
Source_


In addition, required context parameters of the

source node instance are passed as
environment variables.


These parameters have the same name as they have in the scope of the source node
instance but prefixed by
Source_


The script can access the parameters as
$Source_<name>
.


Each property value of the
target node instance (i.e. instance of the properties definition
of the corresponding node type) is passed to the script.


These environment parameters have the same name as the elements of the properties
definition of node type but prefixed by
Target_


In

addition, required context parameters of the target node instance are passed as
environment variables.


These parameters have the same name as they have in the scope of the target node
instance but prefixed by
Target_


The script can access the parameters a
s
$Target_<name>
.


Recommendation
s
:


Make script (incl. potential helper files) available on target environment.


Create a new bash.


Pass all parameters to script as environment variables.


Invoke script.


Process

the
return parameters that the s
cript may have written to environment
variables.

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
19

of
31

3.3

Restrictions and Assumptions

The above conventions are based on the following assumptions made for ensuring interoperability:

Operations

of interfaces support the definition of signatures, i.e. input and output parameters of
operations. Such operation signatures are not used, but all exchange of data with a script occurs by
passing properties of node instances or relationship instances.


Properties
Definitions can refer to arbitrary complex structures. The above recommendations assume that
properties are “flat”, i.e. a
PropertiesDefinitio
n

element has a structure of
xs:sequence

the
nested elements of which are of simple types.


Asynchronous communication with a script requires much more care like dealing with session faults,
passing call
-
back information to the script etc. The above recommendations assume that scripts are
invoked synchronously.


Similarly, remote invocation of a script requires additional handling. The above recommendations assume
local invocation of scripts.


Invocation of scripts in arbit
rary environments requires additional handling in both the invoker as well as
the script itself. The above recommendations assume that scripts run on the target virtual machine.


Because signatures ar
e not used based on our recommendations, it must be avoided that context specific
parameters are defined as properties to be passed to a script. This would pollute domain specific
properties definitions with generic context parameters. The above recommend
ations assume a separate
definition of a fixed set of context parameters known to both, the script as well as its invoker.

Assumption
:


Operation signatures are ignored. Echange of data with a script is based on properties.

Assumption
:


Properties definitions are sequences of simple types.

Assumption
:


Scripts are invoked

synchronously.

Assumption
:


Scripts are invoked locally on managed virtual machines.

Assumption
:


Scripts are executed on the target VM.

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
20

of
31

4

Interoperable TAR files

UNIX
-
style TAR archives can be used to extract installed software component file hierarchies which can
be ap
plied to new installations, e.g. in deploying the same component in another Virtual Machine,
avoiding the need for cloning and maintaining entire images and cleanly separating the distribution of
software component files from open source and other 3rd part
y files.

Note
: within this section
,

the term “TAR process” refers to the creation of a TAR file and

TAR
extract process” refers to the extraction of the TAR content into the target’s
filesystem.

4.1

Prerequisite assumptions

The following assumption s are

made when
invoking

the “TAR” utility:



The TAR process knows the locations of the files of the software component



The TAR process invokes the tar command in a way that enable mapping of the user and group IDs
from the source system to the target system. F
or example:

“tar
--
one
-
file
-
system
--
numeric
-
owner
-
C <baseDir> <excludesString>
-
czf
<localArchivePath> <path>”



The
TAR
extract process knows the extraction location of the archive and how to create the
containing directory with the correct permissions,
user IDs and group IDs.

Note
:
If the archive contents are always found in the same location, absolute paths could
be used although archives with a relative path are preferred.

Complete directory metadata must be extracted for each segment of the path of
the archive location in
the source filesystem so it can be reconstructed in the target.

Each segment represents a directory. For each segment, the permissions, user ID and group ID are
provided. For example, if the location location is

/a/b/c

, the
metadata might look like:

Segment

Permission

UID

GID

a

755

0

0

b

755

0

0

c

555

501

30

Note
:

the archive may not necessarily be extracted to the same path it was in the source
filesystem, although most often it will be. In this case the implementation must decide
how to extrapolate the metadata accordingly.



The
TAR
extract process has the rights
needed to update the filesystem and control file metadata in
the target system



The
TAR
extract process is able to map the user and group IDs from the source system to
appropriate values on the target system.

Specifically, the user and group IDs of the fil
es in the expanded TAR archive must be mapped in

/etc/passwd


and

/etc/groups


in the target system. It is assumed that the
TAR
expand process has
sufficient knowledge to create users and groups and that the encoding of the required information out of
th
e scope of this specification. A simple solution is to include required entries from the source

/etc/passwd


and

/etc/group


files if we want this information to be part of the TAR Descriptor.

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
21

of
31

Note

that it is the symbolic name of the user or group that defines its semantics and the
numeric values in file metadata is used to map back to the symbolic values.

For example, l
et’s assume we have files in our archive which correspond to the user

cr1adm


which we
must ensure exists in the target system. The same general approach applies to mapping group IDs.
When and where the IDs are updated is an implementation detail. This leads to the following scenarios:



If the symbolic name

cr1adm


already exists in

the target system, look up its user ID value and
update all files in the archive with the new value. If it’s the same as in the source, do nothing



If the symbolic name

cr1adm


does not exist in the target system,
it should be created
. If
possible
, it sho
uld be created
with the same user ID value as in the source system to avoid
having to update the IDs in the archives files

4.2

TAR Descriptor

A TAR descriptor containing the necessary information to support the TAR expand process, as described
a
b
ove, should co
ntain the following sections:

Section

Description

Identity

A set of name value pairs describing the contents of the archive. E.g.
productID, componentID, versionID, etc.

Extraction Location

A filesystem path where the archive is to be extracted. This
path is
assumed to be compatible with the way the paths in the archive were
created (relative or absolute). This path is absolute when archive
contents are always placed in the same location or relative when archive
contents are placed relative to some oth
er varying location. No path
implies a relative path of ‘.’ For each segment of the path the
permissionsI user fa and group fa must be provided

rser fa mapping
table

qhis section consists of a set of user fa to symbolic user name pairsI
such as EcrNadmI R
MNF covering all the user fas found in the archive

droup fa mapping
table

qhis section consists of a set of group fa to symbolic group name pairsI
such as EsapsysI RMOF covering all the group fas found in the archive


qhe pseudo
-
uji for this q^o descript
or would look something like thisW

<TarDescriptor>


<IdentitySection>


<Identity name=”product” value=”CRM”/>


<Identity name=”component” value=”XYZ”/>


<Identity name=”version” value=”1.0.1”/>





</IdentitySection>


<ExtractionLocation>


<Segment name=”/sapdb” userID=”501” groupID=”502” permissions=”755”/>





</ExtractionLocation>


<UserMap>


<User userName=”cr1adm” userID=501/>





<UserMap>


</GroupMap>


<Group groupNname=”sapsys” groupID=502/>





</GroupMa
p>

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
22

of
31

</TarDescriptor>


implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
23

of
31

5

TOSCA Model Extraction and Processing Guidance

The TOSCA specification provides an XML exchange format intended to promote
software interoperability

between model
-
producing and model
-
consuming software modules. In the following, some o
f the
conventions that enable model
-
consuming software to extract and reconstruct a model that can guide
sequencing invocations of operations will be described. These conventions will in turn be connected with
the XML information items that express the ord
ering constraints. Finally, some limitations of available
information items will be mentioned.

The initial management services of interest to model
-
consuming modules are those provided by the
Operations

in the
Interfaces

element found in
NodeTypes
. The ope
rations are associated with
implementation artifacts (for example, executable shell scripts) that must be discovered. Because a Tosca
model has structure in which some operations have precondition constraints, the services must in general
be sequenced so
that various dependencies are honored when carrying out management operations.


The TOSCA interoperability SC's current

SugarCRM


model is richly navigable using standard
referencing mechanisms: IDREF values point to relata of
RelationshipTemplates
,
Qnam
es

allow
Xxx
Templates

to be connected with their Types,
Qnames

indicate derivation linkages in type
hierarchies, artifacts are referenced within NodeTypes by
Qnames
, and so on. The XML information items
themselves can be navigated at the XML layer. The cur
rent example has sufficient information and
navigational connections to support finding artifacts to be executed. There may also be sufficient
information to sequence execution, but understanding the semantic postulates about dependencies are
also needed,
as will be eventually be shown. It is first important to inventory those XML information items
currently expressing information that enable a processor to explore the declarative model and arrive at a
sequencing of operations.


5.1

XML Navigation

TOSCA's schem
a defines elements that are types and elements that are typed by those types. In
addition, the element information items are navigable in connection with many relational/graph structures:




typed
-
type relations



type derivation hierarchies



explicit relationships of
NodeTemplate/Requirements (within RelationshipTemplates)



requirement to capability relations



references to artifacts



and others


Implementers are expected to understand the XML mechanisms that are used to indicate these relational

structures. Mainly, the basic relational structures leverage the use of attributes with XML types of ID,
IDREF, and QNames. Occasionally XPath expressions are used as well as directory paths.


IDs are used in
id
attributes, and element items with these
i
d
attributes values are referenced from
another element with various attributes of type IDREF. IDREFs are formally
constrained to

contain values
that are used within the document as ID values. Semantically sensible IDREF values are constrained by
specifica
tion descriptions; for example,
SourceElement

and
TargetElement

in
RelationshipTemplates

are semantically constrained to reference only ID values of
NodeTemplates

or of ID values of
Requirements

within
NodeTemplates
.


For QNames the situation is a bit more

complex. An attribute contains a QName value consisting of a
namespace prefix followed by an NCName (an identifier without a colon). That value serves to reference
an element that has both a
targetNamespace
attribute value that is

equal to the URI bound t
o the prefix
(at the context it occurred); also note that this element must have a
name

attribute whose value equals
implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
24

of
31

the NCName identifier portion of the QName

value. Creators of TOSCA documents are strongly
encouraged to announce prefix bindings that remain unchanged throughout the document, but
implementers must be cautioned to always check the current prefix to namespace association table in
scope when faced
with using the QName value to find a referenced element.


For both QNames and IDREFs (to ID values), the element referenced is unique. While in principle the
same element could be referenced from multiple contexts, there is not at present a mechanism that
allows a multiplicity of alternative items to be referenced.


Tables 1 to 5
(below)
summarize most of the referential/navigational apparatus that is needed when
processing the declarative model for discovering sequencing of operations done for an installat
ion
operation, for example.


Table
1
-

ID IDREF Map

Element having an IDREF
-
based
reference

Attribute of type IDREF containing the
ID value

Element Type Referenced

Rel ati onshi pTempl ate/SourceEl ement

../@ref

NodeTempl ate or
NodeTempl ate/Requi rement wi th
@i d val ue equal to IDREF val ue

Rel ati onshi pTempl ate/TargetEl ement

../@ref

[al so, ../@external Ref QName ]

NodeTempl ate or
NodeTempl ate/Requi rement wi th
@i d val ue equal to IDREF val ue

BoundaryDefi ni ti ons/Properti es/
Propert
yMappi ng

../@targetObjectref

Node Templ ate, NodeTempl ate
/Requi rement ,
NodeTempl ate/Capabi l i ty, or
Rel ati onshi pTempl ate.


Requi rements/Requi rement

@ref

Requi rementType

Capabi l iti es/Capability

@ref

Capabi l ityType


Table
2

-

Requirement and Capability Map

Element Referring Context

QName attribute

Referenced Element

Identifying values of
Referenced Element

Requi rementType

../@requi redCapabi l i tyType

Capabi l ityType

@targetNamespace, @name

Rel ati onshi pType/Val i dSource

./@typeRef

Requi rementType

@targetNamespace, @name

Rel ati onshi pType/Val i dTarget

./@typeRef

Capabi l ityType

@targetNamespace, @name

Requi rementDefi ni ti on

@requi rementType

Requi rementType

@targetNamespace, @name

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
25

of
31

Capabi l ityDefi ni tion

@capabi li tyType

Capabi l ityType

@targetNamespace, @name


Table
3

-

Ar
tifact References

Referring context

Attribute

Item Type Referenced

Mechanism

Arti factTempl ate/Arti factRefere
nces/Arti factReference

@reference


[rel ati ve URI base i s CSAR
di rectory path]

Resource

anyURI

NodeType/Interfaces/Impl ement
ati onArti facts/Impl ementati onAr
ti fact

../@arti factRef

Arti factTempl ate

QName

NodeType/Depl oymentArti facts/
Depl oymentArti fact

../@arti factRef

Arti factTempl ate

QName


Table
4

-

Typed Element to Typing Element Map

Typed element

Attribute with QName

referring value

Element providing type

Identifying values in
referent

NodeTempl ate

NodeTempl ate/@type

NodeType

@targetNamespace, @name

Rel ati onshi pTempl ate


Rel ati onshi pTempl ate/@type

Rel ati onshi pType

@targetNamespace, @name

Requi rement

Requi rement/@type

Requi rementType

@targetNamespace, @name

Capabi l ity

Capabi l ity/@type

Capabi l ityType

@targetNamespace, @name

Impl ementati onArti fact

Impl ementati onArti fact/@arti
factType

Arti factType

@targetNamespace, @name

Depl oymentArti fact

Depl oymentArti fact/@arti fact
Type

Arti factType

@targetNamespace, @name

Arti factTempl ate

Arti factTempl ate/@type

Arti factType

@targetNamespace, @name

Pol i cy

../@po
l i cyType

Pol i cyType [>v13]

@targetNamespace, @name

PropertyConstrai nt

../@constrai ntType

[none]

Val ue of type anyURI

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
26

of
31

Pl an

../@pl anType

[none]

Val ue of type anyURI

Rel ati onshi pConstraint

../@constrai ntType


[none]

Val ue of type anyURI


Table
5

-

Type Hierarchy: Type Element to Supertype Element Map

Type

Element with Referencing
QName Value

Supertype

Identifying values for
supertype found in:

NodeType

Deri vedFrom/@typeRef

NodeType

@targetNamespace, @name

Rel ati onshi pType

Deri vedFrom/@typeRef

Rel ati onshi pType

@targetNamespace, @name

Requi rementType

Deri vedFrom/@typeRef

Requi rementType

@targetNamespace, @name

Capabi l ityType

Deri vedFrom/@typeRef

Capabi l ityType

@targetNamespace, @name

Arti factType

Deri vedFr
om/@typeRef

Arti factType

@targetNamespace, @name


5.1.1

Illustration

of Navigation for SugarCrm Initial Model

Before turning to consider how operation sequencing information is derived from
TOSCA

models, it is
worth showing simple reference chasing for finding the shell script to run for the
install

op
eration for the
example “SugarCrmDb”
element:


<NodeTemplate id="SugarCrmDb" name="SugarCRM DB" type="ns4:SugarCrmDb">



<Properties>


<ns7:
SugarCrmDbProperties
xmlns:ns7="http://www.example.com/ToscaComponents/SugarCrmTypes/SugarCrmDbProp
erties"
xmlns="http://www.example.com/ToscaComponents/SugarCrmTypes/SugarCrmDbProperti
es">


<DBName>sugardb</DBName>


<DBUser>sugaradmin</D
BUser>


<DBPassword>sugaradmin</DBPassword>


<mySqlPort>3306</mySqlPort>


</ns7:SugarCrmDbProperties>



</Properties>



<Requirements>


<Requirement id="SugarCrmDb_container" name="container"
type="ns1
:MySqlDbContainerRequirement"/>


</Requirements>



<Capabilities>


<Capability id="SugarCrmDb_dbclients" name="dbclients"
type="ns1:MySqlDatabaseCapability"/>


</Capabilities>


</NodeTemplate>

implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
27

of
31


We first find the QName referenced element

ns4:Sug
arCrmDb

,

which is the
NodeType

elemen
t
defined as:


<NodeType name="SugarCrmDb"
targetNamespace="http://www.example.com/ToscaComponents/SugarCrmTypes">


<documentation>SugarCRM DB</documentation>


<PropertiesDefinition element="ns7
:SugarCrmDbProperties"/>


<RequirementDefinitions>


<RequirementDefinition lowerBound="1" name="container"


requirementType="ns1:MySqlDbContainerRequirement" upperBound="1"/>


</RequirementDefinitions>


<CapabilityDefinitions
>


<CapabilityDefinition


capabilityType="ns1:MySqlDatabaseCapability" lowerBound="0"


name="dbclients" upperBound="unbounded"/>


</CapabilityDefinitions>


<Interfaces>


<
Interface name="http://docs.oasis
-
open.org/tosca/ns/2011/12/interfaces/lifecycle">


<Operation name="install">


<ScriptOperation/>


</Operation>


<Operation name="start">


<ScriptOperation/>


</Oper
ation>


<Operation name="uninstall">


<ScriptOperation/>


</Operation>


<ImplementationArtifacts>


<ImplementationArtifact


artifactRef="sugar:at
-
72044c27
-
809b
-
417b
-
827b
-
41ff178f4622"



artifactType="ns8:ScriptArtifact" operationName="install"/>


<ImplementationArtifact


artifactRef="sugar:at
-
fc28e181
-
c7fa
-
4d13
-
bf00
-
ca680ccb8aad"


artifactType="ns8:ScriptArtifact" operationName="start"/>



<ImplementationArtifact


artifactRef="sugar:at
-
50879401
-
6975
-
49f8
-
9ab9
-
617af5bd0550"


artifactType="ns8:ScriptArtifact" operationName="uninstall"/>


</ImplementationArtifacts>


</Interface>


</Interfaces>



</NodeType>


Next we find the element referenced by

sugar:at
-
72044c27
-
809b
-
417b
-
827b
-
41ff178f4622

,

which is:



<ArtifactTemplate id="at
-
72044c27
-
809b
-
417b
-
827b
-
41ff178f4622"
type="ns8:ScriptArtifact">


<Properties>


<ns8
:ScriptArtifactProperties


xmlns:ns8="http://docs.oasis
-
open.org/tosca/ns/2011/12/Artifacts"
xmlns="http://docs.oasis
-
open.org/tosca/ns/2011/12/Artifacts">


<ScriptLanguage>sh</ScriptLanguage>


<PrimaryScript>scripts/SugarCrmDb/i
nstall.sh</PrimaryScript>


</ns8:ScriptArtifactProperties>


</Properties>




</ArtifactTemplate>


implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
28

of
31

and therein discover the script directory path:

scripts/SugarCrmDb/install.sh

; this script is
executed with environment variables, using

names and values such as “DBName” with value “sugardb.”

5.2

Sequencing Operation Invocation

The XML conventions adopted in TOSCA XML instances enable
NodeTemplates

and
RelationshipTemplates

to be connected with each other in a system
T
opology, and to be conn
ected
with their Types and Type hierar
chies that define the Interface’s
Operations. A further structural aspect of
a TOSCA model is the existence of a specification plane (the Topology as a graph of
NodeTemplates

and
RelationshipTemplates
) and the implemen
tation plane (
ArtifactTemplates
,
Implementation

and
DeploymentArtifacts
, and their Types). The information in the
RelationshipTemplates

is relevant to arriving at a sequencing of Operations when converting the
declarative model into an implementation.

In general, for TOSCA interoperability, the sequencing information is implicitly found in the relations given
in the (declarative)
RelationshipTemplates

deriving from the base types: “
hostedOn
”, “
dependsOn
”,
and “
connectsTo
”.

For a given operation of inter
est, for example, the Install operation, the
RelationshipTemplates

pertaining to
NodeTemplates

whose types define the Install operation, can be topologically sorted. It is
an assumption in TOSCA that the ordered pairs (of
NodeTemplates
) in Relationships de
riving from type

hostedOn
” have no cycles.

For these “
hostedOn
” directed graphs that are free from cycles, there must be at least one node whose
edges are all “outgoing” (For relations deriving from the

hostedOn


type, these will be the nodes that
host,
but are not themselves hosted.) There may, of course, be several such nodes within the nodes
restricted to the operation of interest.

Topological sort procedures typically involve preliminary determination of the outgoing
-
only set and then
an arbitrary se
lection of each of these hosting
-
yet
-
unhosted nodes to determine a sequence for
installation. Slightly different sequences of installation operations may then be generated for different
choices of elements of the out
-
going only set when using a topological

sort. However, each such
sequence should be a workable installation sequence.

During interoperability testing, participants building T
OSCA

model
-
consuming software encountered
problems tied to the generality and expressiveness of the Tosca XSD metamodel.
Settling on some basic
RelationshipTypes

increased the definiteness of the processing problem because all types would
derive from the three basic types:
connectsTo
,
hostedOn
, and
dependsOn
. Even so, the XML defined
constraints for NodeTemplates and
Relatio
nshipTemplates

remain very general. Assuming that
qname and idref well
-
formedness is adhered to still sets little bounds on the problem of processing the
model so as to be able to run the operations defined within the
NodeType

of a Node. Software that
prod
uced models of well
-
understood and simple test cases was helped by the “real world” to be
represented; consuming software had to work from the often faint traces of the systems captured in the
model.

For example, there are 7 nodes
:


[VmApache, ApacheWebSer
ver, SugarCrmApp, PhpModule, VmMySql, MySql, SugarCrmDb]


and 7

pairs
:


[Apache_HostedOn_VmApache,


SugarCrmApp_HostedOn_Apache
,


PhpModule_HostedOn_Apache,


SugarCrmApp_DependsOn_PhpModule
,


MySqlHostedOnVmMySql,


SugarCrmDb_HostedOn_MySql
,


SugarCrmApp_ConnectsTo_SugarCrmDb]


implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
29

of
31


in the SugarCRM model.


Neglecting the multiplicative factors created by adding types, from an extensional point of view, a 7 node
domain yields 7^2 choose 7, or
85900584,
directed graph objects. Certainly most of thes
e logically
possible graphs have no modeling usage. Semantic constraints of various kinds can perhaps help define
the processing problem to make it more manageable. Provisional semantics for interoperability will then
constrain the kinds of models that con
suming
-
software needs to be prepared to handle in carrying out
processing tasks needed for correct management of the Tosca
-
modeled system. Many of these
constraints will be expressed using simple and basic graph theory terminology. For simplicity, the
inst
all
operation will be a focal illustration in the discussion.


The
hosts
relation is between a container and its contents. The term “container” is generalized so that an
Apache VM is regarded as a container for an Apache Web Server, and the web server can be a container
for a PhP module. Provisionally, the
hosts
relation is pre
sumed to not allow “diamond” containment; in
other words, no content is spread across multiple containers. Containers can, of course, host multiple
contents, such as a web server hosting PhP module and hosting the

SugarCrm


application also. More
exotic c
onstraints are that there are no reflexive hosting relations, and no cyclical hosting relations in a
model. Also it is assumed that, without distortion of representation, a system as a whole can be always
treated as being “single
-
rooted.” Even when there a
re multiple tiers (such as a database tier and a web
server tier), a node may be introduced (“the system”) that hosts these tiers. This node will not need to be
expressed literally in the exchanged T
OSCA

descriptions.
Therefore,
multi
-
rooted directed graph
s can
always be placed under a system node when processing the model. (Algorithms can directly consider a
forest of directed graphs; this is regarded as a matter of variable implementation detail.)


When considering ordering the nodes, so as to sequence in
vocation of operations such as
install,
the
main processing is some implementation of topological sort. The node pairs explicitly in a “hosts” relation
(which is, of course, the inverse of the relation of type
hostedOn)
provide core constraints for this so
rting.
However, in general relation pairs of type
dependsOn
need to be added to the mix of a topological sort.
Consider that there may be sequencing needed for installation of sibling contents of a single container. In
the initial interoperability example,

the PhP module of the webserver needs to be installed prior to
installing its sibling, the SugarCrm application. So pairs from
dependsOn

relations are needed to augment
the sequencing constraints in arriving at the procedural flow of the declarative model
.

Provisionally, it is presumed that
RelationshipTemplates

of type
dependsOn
will not form cycles on
their own or when combined with those of type
hostedOn
. At present, no other constraints on dependsOn
information have been formulated.

Finally, relations

(or pairs) of type
connectsTo

are allowed to form cycles. It is presumed that they are not
relevant for installation operation ordering. [If they were relevant, a separate dependsOn pair would need
to be added to reflect that constraint.] More detailed se
mantics for
connectsTo
will probably emerge as
more operations and more complex system configurations are considered by the interoperability
subcommittee. How the
connectsTo
constraints impact Tosca processing will be an active topic of
discussion going fo
rward.


implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
30

of
31

Appendix A.

Acknowledgements

The following individuals have participated in the creation of this specification and are gratefully
acknowledged:

Contributors
:

Frank Leymann, IBM

Thomas Spatzier, IBM

Derek Palma, Vnomic

Dale Moberg, Axway Software


Subcommittee
Participant
s:


Dale Moberg, Axway Software

Tad Deffler, CA Technologies

Paul Lipton, CA Technologies

Douglas Neuse, CA Technologies

Ken Zink, CA Technologies

Alex Heneveld, Cloudsoft Corporation Limited

Fumi Iikura, Fujitsu Limited

Hitoshi
Komori, Fujitsu Limited

Travis Tripp, Hewlett
-
Packard

Kevin Wilson, Hewlett
-
Packard

Aaron Zhang, Huawei Technologies Co., Ltd.

Paul Zhang, Huawei Technologies Co., Ltd.


Gerd Breiter, IBM

Davis, Mr. Doug
, IBM

Matthew Rutkowski,
IBM

Thomas Spatzier,
IBM

Kri
shna Raman,
Red Hat

Georg Dittmar,
SAP AG

Richard Probst,
SAP AG

Steve Fanshier,
Software AG, Inc.

Derek Palma,
Vnomic



implement
-
v1.0
-
wd01

Working Draft

01

20

May

201
3

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
31

of
31

Appendix B.

Revision History


Revision

Date

Editor

Changes Made

WD1,
Rev
. 01

201
3
-
01
-
1
1

Matt Rutkowski

Initial Version
, sections 1 & 2 added

WD1,

Rev. 02

2013
-
01
-
14

Matt Rutkowski

Section 3 added

WD1, Rev. 03

2013
-
04
-
29

Matt Rutkowski

Merged existing content into new
“specification” template as provided by OASIS.
^djusted styles and layouts to conform to those
provided in template.

taNI oev. MQ

㈰ㄳ
-

-


aale joberg

^ppended uji kavigation and jodel
mrocessing notes.

taNI oev. MR

㈰ㄳ
-

-


jatt outkowski

fnclusion of new referencesI deneral cleanupI
formatting of tables and code samples.

^dded
pC jembers to ^cks.