Topology and Orchestration Specification for Cloud ...



Non-normative Implementer's Recommendations for Interoperable TOSCA Implementations

Working Draft 01

Revision 021

14 January 2013

Technical Committee:

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

Subcommittee: Interoperability SC

Chairs:

Paul Lipton (paul.lipton@), CA Technologies

Simon Moser (smoser@de.), IBM

Editors:

Matt Rutkowski (mrutkows@us.), IBM

Related work:

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

• Topology and Orchestration Specification for Cloud Applications Version 1.0. Latest version. .

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:

This 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 Note Draft. The OASIS document Approval Process begins officially with a TC vote to approve a WD as a Committee Note Draft. A TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Note Draft.

Copyright © OASIS Open 2013. 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 Policy"). 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. However, this document itself may 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 case 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 successors 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 INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Table of Contents

1 Introduction 4

1.1 Statement of Purpose 4

1.2 References (non-normative) 4

2 Describing interoperable artifacts 5

2.1 Variant and invariant Artifact Properties 5

2.2 Identity information on artifacts 7

2.3 Archive artifact 7

2.3.1 Artifact Type Definition 8

2.3.2 Artifact Properties 8

2.3.3 Artifact Context Properties 10

2.3.4 Artifact definition example 13

3 Script invocation conventions 16

3.1 Script artifact definitions 16

3.2 Parameter passing conventions for bash scripts 17

3.2.1 Passing parameters to scripts implementing Node Type operations 17

3.2.2 Passing parameters to scripts implementing Relationship Type operations 19

3.3 Invocation conventions for bash scripts 21

3.4 Restrictions and Assumptions 21

Appendix A. Acknowledgments 23

Appendix B. Revision History 24

1. Introduction

1 Statement of Purpose

TBD

2 References (non-normative)

[TOSCA-CSD-1.0]

OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA), Version 1.0, Committee Specification Draft (CSD) 06 / Public Review Draft 01, 29 November 2012,

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 applications 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 defined 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 Artifact Types.

3 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 such that are variant across different contexts. For example, an archive containing a software installable might contain properties defining the version of the software or the size of the install footprint. Such properties would be considered invariant 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 properties 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 defined 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 used a Deployment Artifact, the variant properties would be defined in the body of a DeploymentArtifact element of a NodeTemplate element or a NodeTypeImplementation 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: To make the definition of variant context properties for Artifact Types specific, we should add a respective element to the ArtifactType element in TOSCA vNext, e.g. ContextPropertiesDefinition. This element would be optional since some Artifact Types do not require it.

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 “ArchiveArtifact” Artifact Type defined further down in this document will be called “ArchiveArtifactProperties”, while the variant properties element will be called “ArchiveArtifactContextProperties”.

4 Identity information on artifacts

Some properties of artifacts 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 specific particular use 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 following pseudo schema defines the structure of identity properties:

01

02 *

03

The IdentityPropertiesy 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 specifies contains a descriptive name of the property and SHOULD should be unique |

| |within the containing IdentityProperties element. |

|value |This attribute specifies contains the value of the property. |

For example, the following identity properties describe the software product name and version of an imaginary software installable:

01

02

03

04

NOTE: Since this applies to all types of artifacts, this element should be made part of the general ArtifactTemplate element in TOSCA vNext. Or should we just use the Tags element, since tags are meant for annotating and finding elements, and this is kind of the same use case.

5 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 might 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.

1 Artifact Type Definition

The following XML snippet shows the definition of the ArchiveArtifact Artifact Type:

2 Artifact Properties

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

01

02

03 ... ?

04

05

07

08

09 +

10 ?

11

12

13 +

14 ?

15

16

17 *

21 ?

22

23 *

24

25

The ArchiveArtifactProperties element provides descriptive information about the actual content of the artifact proper. This information can and SHOULD be used by an implementation to appropriately process the artifact.

The ArchiveArtifactProperties element has the following properties:

• IdentityProperties: This element is optional contains a list of descriptive properties about 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: This attribute specifies 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 element.

• archiveType: This attribute specifies contains the type of the referenced archive, e.g. “tar” or “zip”.

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

If specifiedprovided, this information SHOULD 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.

Each entry is specified by aa separate, nested User element. The User element has the following properties:

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

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

• GroupMap: This OPTIONAL element contains an 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 specifying providing the exactly the ownership of directories and files inside the archive.

If specifiedprovided, this information SHOULD 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 specified by a separate, nested Group element. The Group element has the following properties:

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

• id: This attribute specifies 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 specifiedprovided, this location SHOULD 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”.

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

For each segment of the path specified in the path attribute of the ContentSourceLocation element, a corresponding Segment element SHOULD would be present. For example, for a path value of “/a/b/c” three Segment elements (with name values 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 beare assumed during deployment.

The Segment element has the following properties:

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

• userID: This attribute specifies 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 specifies 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.

• permissions: This attribute specifies 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).

3 Artifact Context Properties

Context properties of an Archive Artifact take effect during the use and deployment of an archive in a specific particular context. In many cases, information provided with the Archive Artifact Template in the form of the ArchiveArtifactProperties element is also used 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 specified provided in the ContentSourceLocation element).

ArchiveArtifactContextProperties 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 specifiedprovided.

The following pseudo schema specifies 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

02

03

04

05

06 +

07 ?

08

09

10 +

11 ?

12

13

14 *

18 ?

19

20 *

21

22

The ArchiveArtifactContextProperties element provides descriptive information for deployment of an artifact. This information can and SHOULD 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 element has the following properties:

• archiveReference: This attribute specifies 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 ArtifactTemplate element referenced by the Deployment- or Implementation Artifact containing the ArchiveArtifactContextProperties element.

• UserMap: This OPTIONAL 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.

If specifiedsupplied, this information would overrides the mappings defined by a corresponding ArchiveInformation element in the Artifact Template referenced by the Deployment- or Implementation Artifact containing the ArchiveArtifactContextProperties element and SHOULD 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 is specified by a separate, nested User element. The User element has the following properties:

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

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

• GroupMap: This OPTIONAL element optionally contains 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 specifying declaring exactly the ownership of directories and files inside the archive.

If specifiedsupplied, this information overrides mappings defined by a corresponding ArchiveInformation element in the Artifact Template referenced by the Deployment- or Implementation Artifact containing the ArchiveArtifactContextProperties element and SHOULD 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 specified by a separated by a, nested Group element. The Group element has the following properties:

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

• id: This attribute specifies contans the numeric id of the group.

• ContentDeploymentLocation: This OPTIONAL 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 referenced by the Deployment- or Implementation Artifact containing the ArchiveArtifactContextProperties element.

Note: If neither ContentSourceLocation nor ContentDeploymentLocation are specified provided for an archive, an implementation MAY might choose to deploy the contents of the archive to a custom location or it MAY might reject the respective TOSCA Definitions document.

The ContentDeploymentLocation element has the following properties:

• path: This attribute specifies contains the absolute filesystem path to which the content of the archive has to be extracted.

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

• If specifiedprovided, this information would SHOULD 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 specifies contains the name of the segment, e.g. “/usr/mypath”.

• userID: This attribute specifies 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 specifies 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.

• permissions: This attribute specifies 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).

4 Artifact definition example

The following example outlines the use of an Archive Artifact as a Deployment Artifact for the database content of an imaginary application. The application “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 the sample application.

The following XML snipped shows the definition of the respective Artifact Template of type ArchiveArtifact for the database content component of an overall TOSCA model:

01

06

07

09

10

11

13

14

15

16

17

18

19

20

24

28

29

30

31

32

33

34

35

36

37

38

39

The Artifact Template “MyDatabaseContentArchive” declares that it is of type ArchiveArtifact. It is assumed that this Artifact Type is defined in namespace “” which is prefixed with “tbase” in the current example. The Artifact Template references a TAR file “MyDatabaseContent.tar” contained in the “files” directory of the CSAR containing the shown TOSCA Definitions document. Inside the ArchiveArtifactProperties element, additional metadata for this TAR file is provided. A user and group (“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.

If it is further specifiedshown, that the content of the TAR file stems from a location “/myapplication/mydatabase” and .b Both segments 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 snippet shows a Node Type Implementation for the “MyDatabaseContent” Node Type that uses the Artifact Template defined above as a Deployment Artifact and uses all the information provided in the ArtifactTemplate as default deployment settings:

01

06

07

09 ...

10

11

14

15

16

17

The Deployment Artifact “DatabaseContent-Archive” references the Artifact Template “MyDatabaseContentArchive” defined earlier. It does not include any additional context properties. Therefore, the archive content will be deployed to the same location as specified 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” wouldill 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 Node Type Implementation for the “MyDatabaseContent” Node Type that uses the Artifact Template defined above as a Deployment Artifact, but overrides some settings for deployment:

01

06

07

09 ...

10

11

14

15

17

18

22

26

27

28

29

30

31

32

33

The Deployment Artifact “DatabaseContent-Archive2” references the Artifact Template “MyDatabaseContentArchive” defined earlier. It includes additional context properties inside the ArchiveArtifactContextProperties element to specify 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 specified 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 created, 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 persisted within the archive (for example by invoking the tar command with options “--same-user”).

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 different 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.

6 Script artifact definitions

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

Script Artifact

The ScriptArtifactProperties element is defined as follows and, assumes that a script always has a script language and a primary script:

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 library files).

By referring to the ScriptArtifact Artifact Type in its type attribute, the following defines an Artifact Template that is a script:

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

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

Google Online Preview   Download