TOSCA Implementer S Recommendation

TOSCA Implementer’s Recommendation:

Script Invocation Conventions

Frank Leymann

Thomas Spatzier

Introduction

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.

Script Artifact Definitions

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

<documentation>Script Artifact</documentation>

</ArtifactType>

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

<xs:element name="ScriptArtifactProperties">

<xs:complexType>

<xs:complexContent>

<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 themain 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:

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

type="ns1:ScriptArtifact">

<ns1:ScriptArtifactProperties

xmlns:ns1="

xmlns="

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

</ns1:ScriptArtifactProperties>

</Properties>

</ArtifactReference>

</ArtifactReferences>

</ArtifactTemplate>

The script is a shell scripts as specified 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 the actual Artifact Template is the configure.sh script itself, as defined by the ArtifactReference element; this element uses anAnt fileset 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.

ParameterPassing Conventions for bash Scripts

Passing Parameters to Scripts Implementing Node Type Operations

Parameters are passed to a script as environment variables. The invoker[z1] of the script has to make the parameter values required by the script available from the property values of the node instance the script implements an operation from. TOSCA Container is responsible for making the parameter values required by the script to be executed available from the property values of the node instance the script implements an operation from. These property values are copiedinto 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[z2] 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 scripts are assumed to be executed on the target environment, i.e. within the virtual machines created during service instantiation. To avoid name confliction among environment variables, XXX mechanism is recommended.

For example, the configure.sh script within the scripts/SugarCRMApplication subdirectory of the SugarCRM CSAR contains the following lines of code[z3]:

...

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 by the script are the elements of the property definition of the SugarCRMApplication node type:

...

</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 following 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="

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">

<ns2:ScriptArtifactProperties ...>

<PrimaryScript>scripts/SugarCRMApplication/configure.sh

</PrimaryScript>

</ns2:ScriptArtifactProperties>

</Properties>

</ArtifactReference>

</ArtifactReferences>

</ArtifactTemplate>

Passing Parameters to Scripts Implementing Relationship Type Operations

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[z4] 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 instance 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 connectToDatabase.shscriptof 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

...

Invocation Conventions for bash Scripts

The script to be invoked (typically the PrimaryScript of an Artifact Template) 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,…) 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 variables by the script itself.

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 PropertiesDefinition 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 arbitrary environments requires additional handling in boththe invoker as well as the script itself. The above recommendations assume that scripts run on the target virtual machine.

Because signatures are 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 recommendations assume a separate definition of a fixed set of context parameters [z5]known to both, the script as well as its invoker.

Input to V.Next

The assumptions above represent (sometimes significant) limitations of TOSCA V1.0. Thus, the assumptions can be turned into requirements on the next version of TOSCA:

TOSCA V.Next should include normative specification for supporting the following functionality:

A definition of Artifact Types for scripts
Reflecting the signature of an operation implemented by a script when exchanging parameters between a script and an invoker of a script
Support properties definitions of any type supported by TOSCA 1.0, and not only sequences of simple types
Support asynchronous invocation of scripts
Support remote invocation of scripts
Support the invocation of scriptsthat do not only run on a target VMs
Support the definition of context parameters

Page 1

[z1]Not clear about the invoker

[z2]Not clear. From user point of view, the deployer will be the invoker. From the process flow point of view, TOSCA container is the invoker.

Also, how will the invoker discover the context parameters? This is the pre-condition to make the context parameters available to the script.

[z3]Who creates these code lines? And when?

The answers are very important to make the document more clear.

[z4]No matter whether a property is needed as an enviroment variable?

[z5]Difficult to define the appropriate set of context parameters.