Blueprint Format v 1.0.0

1 TOSCA Simple Profile definitions in YAML

1.1 TOSCA namespace and alias

The following table defines the namespace alias and (target) namespace values that SHALL be used when referencing the TOSCA Simple Profile version 1.0 specification.

Alias Target Namespace Specification Description
tosca_simple_yaml_1_0_0 The TOSCA Simple Profile v1.0 (YAML) target namespace and namespace alias.

1.2.1 Referenced YAML Types

Many of the types we use in this profile are built-in types from the YAML 1.2 specification (i.e., those identified by the tag:yaml.org,2002 version tag). The following table declares the valid YAML type URIs and aliases that SHALL be used when possible when defining parameters or properties within TOSCA Service Templates using this specification:

Valid aliasesType URI
stringtag:yaml.org,2002:str (default)
integertag:yaml.org,2002:int
floattag:yaml.org,2002:float
booleantag:yaml.org,2002:bool (i.e., a value either ‘true’ or ‘false’)
timestamptag:yaml.org,2002:timestamp
nulltag:yaml.org,2002:null

Note

float, Boolean, timestamp are not supported as Input parameters.

1.2.2 TOSCA base types

This specification defines the following types that may be used when defining properties or parameters.

1.2.2.1 TOSCA version

TOSCA supports the concept of “reuse” of type definitions, as well as template definitions which could be version and change over time. It is important to provide a reliable, normative means to represent a version string which enables the comparison and management of types and templates over time. Therefore, the TOSCA TC intends to provide a normative version type (string) for this purpose in future Working Drafts of this specification.

1.2.2.1.1 Grammar

TOSCA version strings have the following grammar:

<major_version>.<minor_version>.<fix_version>[.<qualifier>[-<build_version] ]

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

major_version: is a required integer value greater than or equal to 0 (zero)
minor_version: is a required integer value greater than or equal to 0 (zero).
fix_version: is a required integer value greater than or equal to 0 (zero).
qualifier: is an optional string that indicates a named, pre-release version of the associated code that has been derived from the version of the code identified by the combination major_version, minor_version and fix_version numbers.
build_version: is an optional integer value greater than or equal to 0 (zero) that can be used to further qualify different build versions of the code that has the same qualifer_string.

1.2.2.1.2 Version Comparison

When comparing TOSCA versions, all component versions (i.e., major, minor and fix) are compared in sequence from left to right.
  • TOSCA versions that include the optional qualifier are considered older than those without a qualifier.
  • TOSCA versions with the same major, minor, and fix versions and have the same qualifier string, but with different build versions can be compared based upon the build version.
  • Qualifier strings are considered domain-specifi3. Therefore, this specification makes no recommendation on how to compare TOSCA versions with the same major, minor and fix versions, but with different qualifiers strings and simply considers them different named branches derived from the same code.

1.2.2.1.3 Examples

Example of a version with

# basic version string
2.0.1
# version string with optional qualifier
3.1.0.beta
# version string with optional qualifier and build version
1.0.0.alpha-10

1.2.2.1.4 Notes

[Maven-Version] The TOSCA version type is compatible with the Apache Maven versioning policy.

1.2.2.2 TOCSA range type

The range type can be used to define numeric ranges with a lower and upper boundary. For example, this allows for specifying a range of ports to be opened in a firewall.

1.2.2.2.1 Grammar

TOSCA range values have the following grammar:

[<lower_bound>, <upper_bound>]
In the above grammar, the pseudo values that appear in angle brackets have the following meaning:
lower_bound: is a required integer value that denotes the lower boundary of the range.
upper_bound: is a required integer value that denotes the upper boundary of the range. This value must be greater than lower_bound.

1.2.2.2.2 Examples

Example of a node template property with a range value:

# numeric range between 1 and 100
a_range_property: [ 1, 100 ]
1.2.2.3 TOSCA list type

The list type allows for specifying multiple values for a parameter of property. For example, if an application allows for being configured to listen on multiple ports, a list of ports could be configured using the list data type.

Note that entries in a list for one property or parameter must be of the same type. The type (for simple entries) or schema (for complex entries) is defined by the entry_schema attribute of the respective property definition, attribute definition, or input- or output parameter definition.

1.2.2.4.1 Grammar

TOSCA lists normal YAML lists with the following grammars:

1.2.2.4.2 Square bracket notation

[ <list_entry_1>, <list_entry_2>, ... ]

1.2.2.4.3 Bulleted list notation

- <list_entry_1>
- ...
- <list_entry_n>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning: <list_entry_*>: represents one entry of the list

1.2.2.4.4 Examples

Example of node template property with a list value:

1.2.2.4.5 Square bracket notation

listen_ports: [ 80, 8080 ]

1.2.2.4.6 Bulleted list notation

listen_ports:
- 80
- 8080
1.2.2.5 TOSCA map type

The map type allows for specifying multiple values for a parameter of property as a map. In contrast to the list type, where each entry can only be addressed by its index in the list, entries in a map are named elements that can be addressed by their keys. Note that entries in a map for one property or parameter must be of the same type. The type (for simple entries) or schema (for complex entries) is defined by the entry_schema attribute of the respective property definition, attribute definition, or input or output parameter definition.

1.2.2.5.1 Grammar

TOSCA maps are normal YAML dictionaries with following grammar:

1.2.2.5.2 Single-line grammar

{ <entry_key_1>: <entry_value_1>, ..., <entry_key_n>: <entry_value_n> }
...
<entry_key_n>: <entry_value_n>

1.2.2.5.3 Multi-line grammar

<entry_key_1>: <entry_value_1>
...
<entry_key_n>: <entry_value_n>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

entry_key_*: is the required key for an entry in the map
entry_value_*: is the value of the respective entry in the map
1.2.2.5.4 Examples

Example of a node template property with a map value:

1.2.2.5.5 Single-line notation

# notation option for shorter maps
user_name_to_id_map: { user1: 1001, user2: 1002 }

1.2.2.5.6 Multi-line notation

# notation for longer maps
user_name_to_id_map:
    user1: 1001
    user2: 1002

In the examples above, two notation options are given: option 1 is using a notation where each map entry is one a separate line; this option is typically useful or more readable if there is a large number of entries, or if the entries are complex. Option 2 is using a notation that is useful for only short maps with simple entries.

1.3 Normative values

1.3.1 Node States

As components (i.e., nodes) of TOSCA applications are deployed, instantiated and orchestrated over their lifecycle using normative lifecycle operations (see section 3.6 for normative lifecycle definitions) it is important define normative values for communicating the states of these components normatively between orchestration and workflow engines and any managers of these applications. The following table provides the list of recognized node states for TOSCA Simple Profile that would be set by the orchestrator to describe a node instance’s state:

Node State ValueTransitionalDescription
initialnoNode is not yet created. Node only exists as a template definition.
creatingyesNode is transitioning from initial state to created state.
creatednoNode software has been installed.
configuringyesNode is transitioning from created state to configured state.
configurednoNode has been configured prior to being started.
startingyesNode is transitioning from configured state to started state.
runningnoNode is started and running (correlates to Started in TOSCA)
stoppingyesNode is transitioning from its current state to a configured state.
deletingyesNode is transitioning from its current state to one where it is deleted and its state is no longer tracked by the instance model.
errornoNode is in an error state.

1.4 TOSCA entity and element definitions (meta-model)

This section defines all modelable entities that comprise the TOSCA Version 1.0 Simple Profile specification along with their key names, grammar and requirements.

1.4.1 Description element

This optional element provides a means include single or multiline descriptions within a TOSCA Simple Profile template as a scalar string value.

1.4.1.1 Keyname

The following keyname is used to provide a description within the TOSCA Simple Profile specification:

description
1.4.1.2 Grammar

The description element is a YAML string.

description: <string>
1.4.1.3 Examples

Simple descriptions are treated as a single literal that includes the entire contents of the line that immediately follows the description key:

description: This is an example of a single line description (no folding).

The YAML “folded” style may also be used for multi-line descriptions which “folds” line breaks as space characters.

description: >
    This is an example of a multi-line description using YAML. It permits for line
    breaks for easier readability...

if needed. However, (multiple) line breaks are folded into a single space character when processed into a single string value.

1.4.1.4 Notes

Use of “folded” style is discouraged for the YAML string type apart from when used with the description keyname.

1.4.2 Constraint clause

A constraint clause defines an operation along with one or more compatible values that can be used to define a constraint on a property or parameter’s allowed values when it is defined in a TOSCA Service Template or one of its entities.

1.4.2.1 Operator keynames

The following is the list of recognized operators (keynames) when defining constraint clauses:

OperatorTypeValue TypeDescription
equalscalaranyConstrains a property or parameter to a value equal to (‘=’) the value declared.
greater_thanscalarcomparableConstrains a property or parameter to a value greater than (‘>’) the value declared.
greater_or_equalscalarcomparableConstrains a property or parameter to a value greater than or equal to (‘>=’) the value declared.
less_thanscalarcomparableConstrains a property or parameter to a value less than (‘<’) the value declared.
less_or_equalscalarcomparableConstrains a property or parameter to a value less than or equal to (‘<=’) the value declared.
in_rangedual scalarcomparableConstrains a property or parameter to a value in range of (inclusive) the two values declared.
note:subclasses or templates of types that declare a property with the in_range constraint MAY only further restrict the range specified by the parent type.
valid_valueslistanyConstrains a property or parameter to a value that is in the list of declared values.
lengthscalarstringConstrains the property or parameter to a value of a given length.
min_lengthscalarstringConstrains the property or parameter to a value to a minimum length.
max_lengthscalarstringConstrains the property or parameter to a value to a maximum length.
patternregexstringConstrains the property or parameter to a value that is allowed by the provided regular expression.
Note: Future drafts of this specification will detail the use of regular expressions and reference an appropriate standardized grammar.

In the Value Type column above, an entry of “comparable” includes integer, float, timestamp, string and version types, while an entry of “any” refers to any type allowed in the TOSCA simple profile in YAML.

1.4.2.2 Grammar

Constraint clauses take one of the following forms:

# Scalar grammar
<operator>: <scalar_value>

# Dual scalar grammar
<operator>: { <scalar_value_1>, <scalar_value_2> }

# List grammar
<operator> [ <value_1>, <value_2>, ..., <value_n> ]

# Regular expression (regex) grammar
pattern: <regular_expression_value>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

operator: represents a required operator from the specified list shown above (see section 1.4.2.1 “Operator keynames”).
scalar_value, scalar_value_*: represents a required scalar (or atomic quantity) that can hold only one value at a time.  This will be a value of a primitive type, such as an integer or string that is allowed by this specification.
value_*: represents a required value of the operator that is not limited to scalars.
reqular_expression_value: represents a regular expression (string) value.
1.4.2.3 Examples

Constraint clauses used on parameter or property definitions:

# equal
equal: 2

# greater_than
greater_than: 1

# greater_or_equal
greater_or_equal: 2

# less_than
less_than: 5

# less_or_equal
less_or_equal: 4

# in_range
in_range: [ 1, 4 ]

# valid_values
valid_values: [1, 2, 4]

# specific length (in characters)
length: 32

# min_length (in characters)
min_length: 8

# max_length (in characters)
max_length: 64
1.4.2.4 Notes

Values provided by the operands (i.e., values and scalar values) SHALL be type-compatible with their associated operations. Future drafts of this specification will detail the use of regular expressions and reference an appropriate standardized grammar.

1.4.3 Constraints element

The Constraints element specifies a sequenced list of constraints on one or more of the Service Template’s properties, parameters or other typed elements of the TOSCA Simple Profile. A constraints element is represented as a YAML block collection that contains a sequenced list of nested constraint clauses.

1.4.3.1 Keyname

The following keyname is used to provide a list of constraints within the TOSCA Simple Profile specification: constraints

1.4.3.2 Grammar

The constraints element is described as a YAML block collection that contains a sequence of constraint clauses:

<some_typed_property_name>:
    constraints:
        - <constraint_clause_1>
        - ...
        - <constraint_clause_n>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

some_typed_property_name: represents the required symbolic name of a typed property definition, as a string, which can be associated to a TOSCA entity.

For example, a property (definition) can be declared as part of a Node Type or Node Template definition or it can be used to define an input or output property (parameter) for a Service Template’s. constraint_clause_*: represents constraint clauses for the associated property or parameter.

1.4.3.3 Examples

Constraint on an integer-typed parameter definition:

# An example input parameter that represents a number of CPUs
# and constrains its value to a specific range.
inputs:
num_cpus:
    type: integer
    constraints:
    - in_range: [ 2, 4 ]

Constraints on a string-typed parameter definition:

# An example input parameter that represents a user ID and constrains its length.
inputs:
  user_id:
    type: string
    constraints:
      - min_length: 8
      - max_length: 16
1.4.3.4 Notes

Constraints of properties or parameters SHOULD be type-compatible with the type defined for that property or parameter. In the TOSCA v1.0 specification constraints are expressed in the XML Schema definitions of Node Type properties referenced in the PropertiesDefinition element of NodeType definitions.

1.4.4 Property definition

A property definition defines a named, typed value and related data that can be associated with an entity defined in this specification. It is used to provide a transparent property or characteristic of that entity which can either be set on or retrieved from it. Properties are used by template authors to provide the “desired state”, as input to TOSCA entities for use when they are instantiated. The value of a property can be retrieved using the get_property function within TOSCA Service Templates.

1.4.4.1 Keynames

The following is the list of recognized keynames recognized for a TOSCA property definition:

KeynameRequiredTypeConstraintsDescription
typeyesstringNoneThe required data type for the property.
1.4.4.3 Grammar

Named property definitions have the following grammar:

<property_name>:
  type: <property_type>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

property_name: represents the required symbolic name of the property as a string. property_type: represents the required data type of the property.

1.4.4.5 Additional Requirements

Implementations of the TOSCA Simple Profile SHALL automatically reflect (i.e., make available) any property defined on an entity as an attribute of the entity with the same name as the property.

1.4.4.6 Notes

This element directly maps to the PropertiesDefinition element defined as part of the schema for most type and entities defined in the TOSCA v1.0 specification.

1.4.11 Interfaces element

The Interfaces element describes a list of one or more interface definitions for a modelable entity (e.g., a Node or Relationship Type) as defined within the TOSCA Simple Profile specification. Each interface definition contains one or more interfaces for operations that can be invoked on the associated entity.

1.4.12 Properties element

Note

Applies only to dcm.nodes.SoftwareComponent

The Properties element describes one or more typed Property definitions that can be associated with modelable TOSCA entities (e.g., Node Types, Node Templates, Relationship Types, Artifact Types, et3.). Properties are used by the author to declare the “desired state” of that entity when initially deployed. The actual state of the entity, at any point in its lifecycle once instantiated, is reflected by Attribute definitions. TOSCA orchestrators automatically create an attribute for every declared property (with the same symbolic name) to allow introspection of both the desired state (property) and actual state (attribute).

1.4.12.1 Keyname

The following keyname is used to declare a list of properties within the TOSCA Simple Profile specification:

properties
1.4.12.2 Grammar

The properties element is described as a YAML block collection that contains a list of property definitions:

<some_typed_entity_name>:
    properties:
        <property_defn_1>
        ...
        <property_defn_n>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

some_typed_entity_name: represents the name of a typed TOSCA entity (e.g., a Node Type, Node Template, Relationship Type, et3.) that has, as part of its definition, a list of properties. property_defn_*: represents one or more property definitions for the associated entity.

1.4.12.3 Example

The following example shows property definitions being associated to a Node Type:

my_app_node_type:
  derived_from: tosc1.nodes.Root
  properties:
    stylesheet:
      type: string
      default: basi3.css
    max_connections:
      type: integer
      required: false

1.4.13 Attributes element

Note

Applies only to dcm.nodes.SoftwareComponent

The Attributes element describes one or more typed Attribute definitions that can be associated with a modelable TOSCA entity (e.g., Node Types, Relationship Types, et3.). Attributes are used by the author to provide access the “actual state” of certain properties of TOSCA entities at any point in their lifecycle once instantiated (i.e., post deployment). TOSCA orchestrators automatically create Attribute definitions for any Property definitions declared on the same TOSCA entity in order to make accessible the actual (i.e., the current state) value from the running instance of the entity.

1.4.13.1 Keyname

The following keyname is used to declare a list of attributes within the TOSCA Simple Profile specification: attributes

1.4.13.2 Grammar

The attributes element is described as a YAML block collection that contains a list of attribute definitions:

<some_typed_entity_name>:
  attributes:
    <attribute_defn_1>
    ...
    <attribute_defn_n>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning: some_typed_entity_name: represents the name of a typed TOSCA entity (e.g., a Node Type, Relationship Type, et3.) that has, as part of its definition, a list of attributes. attribute_defn_*: represents one or more attribute definitions for the associated entity.

1.4.13.3 Example

The following example shows attribute definitions being associated to a Node Type:

my_app_node_type:
  derived_from: tosc1.nodes.Root
  attributes:
    instanceId:
      type: string
    max_connections:
      type: integer

1.4.16 Capability definition

A capability definition defines a named, typed set of data that can be associated with Node Type or Node Template to describe a transparent capability or feature of the software component the node describes. Note: Only supported for Note: Applies only to dcm.nodes.server and SofwareComponent

1.4.16.1 Keynames

The following is the list of recognized keynames recognized for a TOSCA capability definition:

KeynameTypeDescription
descriptiondescriptionThe optional description of the Capability Type.
propertiespropertiesAn optional list of property definitions for the capability definition.
1.4.16.2 Grammar

Named capability definitions have one of the following grammars:

1.4.16.2.1 Short notation

The following grammar may be used when only a list of capability definition names needs to be declared:

<capability_defn_name>: <capability_type>

1.4.16.2.2 Extended notation

The following multi-line grammar may be used when additional information on the capability definition is needed:

<capability_defn_name>:
   type: <capability_type>
   description: <capability_defn_description>
   properties:
     <property_definitions>
   attributes:
     <attribute_definitions>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning: capability_defn_name: represents the name of a capability definition as a string. capability_type: represents the required capability type the capability definition is based upon. capability_defn_description: represents the optional description of the capability definition. property_definitions: represents the optional list of property definitions for the capability definition. attribute_definitions: represents the optional list of attribute definitions for the capability definition.

1.4.16.3 Examples

The following examples show capability definitions in both simple and full forms:

1.4.16.3.1 Simple notation example

# Simple notation, no properties defined or augmented

some_capability: mytypes.mycapabilities.MyCapabilityTypeName

1.4.16.3.2 Full notation example

# Full notationnotation, augmenting properties of the referenced capability type

some_capability:
  type: mytypes.mycapabilities.MyCapabilityTypeName
  properties:
    limit: 100

1.4.16.3 Notes

The Capability Type, in this example MyCapabilityTypeName, would be defined elsewhere and have an integer property named limit. This definition directly maps to the CapabilitiesDefinition of the Node Type entity as defined in the TOSCA v1.0 specification.

1.4.17 Capabilities element

The Capabilities element is used to associate one or more typed Capability definitions with a TOSCA Node Type or Node Template.

1.4.17.1 Keyname

The following keyname is used to declare a list of capabilities within the TOSCA Simple Profile specification: capabilities

1.4.17.2 Grammar

The capabilities element is described by a YAML block collection that contains a list of capability definitions:

capabilities:
<some_typed_entity_name>:
    <capability_definition_1>
    ...
    <capability_definition_n>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning: some_typed_entity_name: represents the name of a typed TOSCA entity (e.g., a Node Type, Node Template) that has, as part of its definition, a list of capabilities. capability_definition_*: represents one or more Capability definitions for the associated entity.

1.4.17.3 Example

The following examples show capability definitions in both simple and full forms being associated to Node Types:

my_node_type_1:
  # Other keys omitted here for sake of brevity
  capabilities:
    app_container: mytypes.mycapabilities.AppContainer
    app_endpoint:
      type: mytypes.mycapabilities.Endpoint
      properties:
        timeout: 300

Note

This element directly maps to the Capabilities element defined as part of the schema for the Node Template entity as defined in the TOSCA v1.0 specification.

1.4.27 Node Type

A Node Type is a reusable entity that defines the type of one or more Node Templates. As such, a Node Type defines the structure of observable properties via a Properties Definition, the Requirements and Capabilities of the node as well as its supported interfaces. The following is the list of recognized keynames recognized for a TOSCA Node Type definition:

KeynameDefinition/TypeDescription
derived_fromstringAn optional parent Node Type name this new Node Type derives from.
descriptiondescriptionAn optional description for the Node Type.
propertiespropertiesAn optional list of property definitions for the Node Type.
attributesattributesAn optional list of attribute definitions for the Node Type.
requirementsrequirementsAn optional sequenced list of requirement definitions for the Node Type.
capabilitiescapabilitiesAn optional list of capability definitions for the Node Type.
interfacesinterfacesAn optional list of named interfaces for the Node Type.
1.4.27.1 Grammar
<node_type_name>:
  derived_from: <parent_node_type_name>
  description: <node_type_description>
  properties:
    <property_definitions>
  attributes:
    <attribute_definitions>
  requirements:
    <requirement_definitions>
  capabilities:
    <capability_definitions>
  interfaces: <interface_definitions>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning: node_type_name: represents the required symbolic name of the Node Type being declared. parent_node_type_name: represents the name (string) of the Node Type this Node Type definition derives from (i.e., its “parent” type). node_type_description: represents the optional description string for the corresponding node_type_name. property_definitions: represents the optional list of property definitions for the Node Type. attribute_definitions: represents the optional list of attribute definitions for the Node Type. requirement_definitions: represents the optional sequenced list of requirement definitions for the Node Type. capability_definitions: represents the optional list of capability definitions for the Node Type. interface_definitions: represents the optional list of one or more named interface definitions supported by the Node Type.

1.4.27.2 Best Practices

It is recommended that all Node Types SHOULD derive directly (as a parent) or indirectly (as an ancestor) of the TOSCA “Root” Node Type (i.e., tosc1.nodes.Root) to promote compatibility and portability. However, it is permitted to author Node Types that do not do so.

1.4.27.3 Example

my_company.my_types.my_app_node_type:
  derived_from: tosc1.nodes.SoftwareComponent
  description: My company’s custom applicaton
  properties:
    my_app_password:
      type: string
      description: application password
      constraints:
        - min_length: 6
        - max_length: 10
    my_app_port:
      type: integer
      description: application port number
  requirements:
    - host: tosc1.nodes.Compute
  interfaces: [ Standard ]
1.4.28 Node Template definition

A Node Template specifies the occurrence of a manageable software component as part of an application’s topology model which is defined in a TOSCA Service Template. A Node template is an instance of a specified Node Type and can provide customized properties, constraints or operations which override the defaults provided by its Node Type and its implementations. The following is the list of recognized keynames recognized for a TOSCA Node Template definition:

KeynameDefinition/TypeDescription
typestringThe required name of the Node Type the Node Template is based upon.
descriptiondescriptionAn optional description for the Node Template.
propertiespropertiesAn optional list of property definitions for the Node Template.
attributesattributesAn optional list of attribute definitions for the Node Template.
requirementsrequirementsAn optional sequenced list of requirement definitions for the Node Template.
capabilitiescapabilitiesAn optional list of capability definitions for the Node Template.
interfacesinterfacesAn optional list of named interfaces for the Node Template.

1.4.28.1 Grammar

<node_template_name>:
  type: <node_type_name>
  description: <node_template_description>
  properties:
    <property_definitions>
  attributes:
    <attribute_definitions>
  requirements:
    <requirement_definitions>
  capabilities:
    <capability_definitions>
  interfaces:
    <interface_definitions>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning: node_template_name: represents the required symbolic name of the Node Template being declared. node_type_name: represents the name of the Node Type the Node Template is based upon. node_template_description: represents the optional description string for Node Template. property_definitions: represents the optional list of property definitions for the Node Template that augment those provided by its declared Node Type. requirement_definitions: represents the optional sequenced list of requirement definitions for the Node Template that augment those provided by its declared Node Type. capability_definitions: represents the optional list of capability definitions for the Node Template that augment those provided by its declared Node Type. interface_definitions: represents the optional list of interface definitions for the Node Template that augment those provided by its declared Node Type.

1.4.28.2 Example

node_templates:
  mysql:
    type: tosc1.nodes.DBMS.MySQL
    properties:
      dbms_password: { get_input: my_mysql_rootpw }
      dbms_port: { get_input: my_mysql_port }
    requirements:
      - host: db_server
    interfaces:
      Standard:
        configure: scripts/my_own_configure.sh

1.5 Service Template

A TOSCA Definitions YAML document contains element definitions of building blocks for cloud application, or complete models of cloud applications. This section describes the top-level structural elements (i.e., YAML keys), which are allowed to appear in a TOSCA Definitions YAML document.

1.5.1 Keynames

A TOSCA Definitions file contains the following element keynames:

KeynameRequiredDescription
tosca_definitions_versionyesDefines the version of the TOSCA Simple Profile specification the template (grammar) complies with.
template_namenoDeclares the name of the template.
template_authornoDeclares the author(s) of the template.
descriptionyesDeclares a description for this Service Template and its contents.
importsyesDeclares import statements external TOSCA Definitions documents (files).
topology_templatenoDefines the topology template of an application or service, consisting of node templates that represent the application’s or service’s components, as well as relationship templates representing relations between the components.
node_typesnoThis section contains a set of node type definitions for use in service templates. Such type definitions may be used within the node_templates section of the same file, or a TOSCA Definitions file may also just contain node type definitions for use in other files.
relationship_typesnoThis section contains a set of relationship type definitions for use in service templates. Such type definitions may be used within the same file, or a TOSCA Definitions file may also just contain relationship type definitions for use in other files.
capability_typesnoThis section contains an optional list of capability type definitions for use in service templates. Such type definitions may be used within the same file, or a TOSCA Definitions file may also just contain capability type definitions for use in other files.

1.5.2 Grammar

The overall structure of a TOSCA Service Template and its top-level key collations using the TOSCA Simple Profile is shown below: tosca_definitions_version: # Required TOSCA Definitions version string tosca_default_namespace: # Optional. default namespace (schema, types version) template_name: # Optional name of this service template template_author: # Optional author of this service template template_version: # Optional version of this service template

description: A short description of the definitions inside the file.

imports:
# list of import statements for importing other definitions files
topology_template:
# topology template definition of the cloud application or service
node_types:
# list of node type definitions
capability_types:
# list of capability type definitions
relationship_types:
# list of relationship type definitions

1.5.3 Top-level key definitions

1.5.3.1 tosca_definitions_version

This required element provides a means to include a reference to the TOSCA Simple Profile specification within the TOSCA Definitions YAML file. It is an indicator for the version of the TOSCA grammar that should be used to parse the remainder of the document.

1.5.3.1.1 Keyword

tosca_definitions_version

1.5.3.1.2 Grammar

Single-line form:

tosca_definitions_version: <tosca_simple_profile_version>

1.5.3.1.3 Examples:

TOSCA Simple Profile version 1.0 specification using the defined namespace alias (see Section 1.1): tosca_definitions_version: tosca_simple_yaml_1_0_0 TOSCA Simple Profile version 1.0 specification using the fully defined (target) namespace (see Section 1.1): tosca_definitions_version: http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/TOSCA-Simple-Profile-YAML-v1.0.html

1.5.3.2 template_name

This optional element declares the optional name of service template as a single-line string value.

1.5.3.2.1 Keyword

template_name

1.5.3.2.2 Grammar

template_name: <name string>

1.5.3.2.3 Example

template_name: My service template

1.5.3.2.4 Notes

Some service templates are designed to be referenced and reused by other service templates. Therefore, in these cases, the template_name value SHOULD be designed to be used as a unique identifier through the use of namespacing techniques.

1.5.3.3 template_author

This optional element declares the optional author(s) of the service template as a single-line string value.

1.5.3.3.1 Keyword

template_author

1.5.3.3.2 Grammar

template_author: <author string>

1.5.3.3.3 Example

template_author: My service template

1.5.3.4 template_version

This element declares the optional version of the service template as a single-line string value.

1.5.3.4.1 Keyword

template_version

1.5.3.4.2 Grammar

template_version: <version>

1.5.3.4.3 Example

template_version: 2.0.17

1.5.3.4.4 Notes:

Some service templates are designed to be referenced and reused by other service templates and have a lifecycle of their own. Therefore, in these cases, a template_version value SHOULD be included and used in conjunction with a unique template_name value to enable lifecycle management of the service template and its contents.

1.5.3.5 description

This optional element provides a means to include single or multiline descriptions within a TOSCA Simple Profile template as a scalar string value.

1.5.3.5.1 Keyword

description

1.5.3.6 imports

This optional element provides a way to import a block sequence of one or more TOSCA Definitions documents. TOSCA Definitions documents can contain reusable TOSCA type definitions (e.g., Node Types, Relationship Types, Artifact Types, et3.) defined by other authors. This mechanism provides an effective way for companies and organizations to define normative types and/or describe their software applications for reuse in other TOSCA Service Templates.

1.5.3.6.1 Keyword

imports

1.5.3.6.2 Grammar

imports:
    - <tosca_definitions_file_1>
    - ...
    - <tosca_definitions_file_n>

1.5.3.6.3 Example

# An example import of definitions files from a location relative to the
# file location of the service template declaring the import.

imports:
  - my_typesdefs_1.yaml
  - ...
  - my_typesdefs_n.yaml
1.5.3.10 relationship_types
This element lists the Relationship Types that provide the reusable type definitions that can be used to describe dependent relationships between Node Templates or Node Types.
1.5.3.10.1 Keyword
relationship_types
1.5.3.10.2 Grammar
relationship_types:
  <relationship_type_defn_1>
  ...
  <relationship type_defn_n>
1.5.3.10.3 Example
relationship_types:
  mycompany.mytypes.myCustomClientServerType:
    derived_from: tosc1.relationships.HostedOn
    properties:
      # more details ...
  mycompany.mytypes.myCustomConnectionType:
    derived_from: tosc1.relationships.ConnectsTo
    properties:
      # more details ...

1.5.3.11 capability_types

This element lists the Capability Types that provide the reusable type definitions that can be used to describe features Node Templates or Node Types can declare they support.

1.5.3.11.1 Keyword

capability_types

1.5.3.11.2 Grammar

capability_types:
  <capability_type_defn_1>
  ...
  <capability type_defn_n>

1.5.3.11.3 Example

capability_types:
  mycompany.mytypes.myCustomEndpoint:
    derived_from: tosc1.capabilities.Endpoint
    properties:
      # more details ...

  mycompany.mytypes.myCustomFeature:
    derived_from: tosc1.capabilites.Feature
    properties:
      # more details ...

1.6 topology_template

This section defines the topology template of a cloud application. The main ingredients of the topology template are node templates representing components of the application and relationship templates representing links between the components. These elements are defined in the nested node_templates section and the nested relationship_templates sections, respectively. Furthermore, a topology template allows for defining input parameters, output parameters as well as grouping of elements.

1.6.1 Grammar

The overall grammar of the topology_template section is shown below.–Detailed grammar definitions of the each sub-sections are provided in subsequent subsections.

topology_template:
  description:
    # a description of the topology template

  inputs:
    # definition of input parameters for the topology template

  node_templates:
    # definition of the node templates of the topology

  relationship_templates:
    # definition of the relationship templates of the topology

  outputs:
    # definition of output parameters for the topology template
1.6.1.1 inputs

The inputs section provides a means to define parameters, their allowed values via constraints and default values within a TOSCA Simple Profile template. Input parameters defined in the inputs section of a topology template can be mapped to properties of node templates or relationship templates within the same topology template and can thus be used for parameterizing the instantiation of the topology template.

This section defines topology template-level input parameter section. Inputs here would ideally be mapped to BoundaryDefinitions in TOSCA v1.0. Treat input parameters as fixed global variables (not settable within template) If not in input take default (nodes use default)

1.6.1.1.1 Grammar

The grammar of the inputs section is as follows:

inputs:
  <property_definition_1>
  ...
  <property_definition_n>

1.6.1.1.2 Examples

This section provides a set of examples for the single elements of a topology template. Simple inputs example without any constraints:

inputs:
  fooName:
    type: string
    description: Simple string typed property definition with no constraints.
    default: bar
Example of inputs with constraints:
inputs:
  SiteName:
    type: string
    description: string typed property definition with constraints
    default: My Site
    constraints:
      - min_length: 9
1.6.1.2 node_templates

The node_templates section lists the Node Templates that describe the (software) components that are used to compose cloud applications.

1.6.1.2.1 grammar

The grammar of the node_templates section is a follows:

node_templates:
  <node_template_defn_1>
  ...
  <node_template_defn_n>

1.6.1.2.2 Example

Example of node_templates section:

node_templates:
  my_webapp_node_template:
    type: WebApplication

  my_database_node_template:
    type: Database
1.6.1.3 relationship_templates

The relationship_templates section lists the Relationship Templates that describe the relations between components that are used to compose cloud applications.

Note that in the TOSCA Simple Profile, the explicit definition of relationship templates as it was required in TOSCA v1.0 is optional, since relationships between nodes get implicitly defined by referencing other node templates in the requirements sections of node templates.

1.6.1.3.1 Grammar

The grammar of the relationship_templates section is as follows:

relationship_templates:
  <relationship_template_defn_1>
  ...
  <relationship_template_defn_n>

1.6.1.3.2 Example

Example of relationship_templates section:

relationship_templates:
1.6.1.4 Outputs

The outputs section provides a means to define the output parameters that are available from a TOSCA Simple Profile service template. It allows for exposing attributes of node templates or relationship templates within the containing topology_template to users of a service.

1.6.1.4.1 Grammar

The grammar of the outputs section is as follows: .. code-block:: text

outputs:
<property_definitions>

1.6.1.4.2 Example

Example of ouputs section:

outputs:
  server_ip:
    description: The IP address of the provisioned server.
    value: { get_attribute: [ my_server, ip_address ] }

1.6.1.5 Groups The groups section allows for grouping one or more node templates within a TOSCA Service Template and for assigning special attributes like policies to the group.

1.6.1.5.1 Grammar

The grammar of the groups section is as follows:

groups:
  <group_name_A>:
    <node_template_defn_A_1>
    ...
    <node_template_defn_A_n>

  <group_name_B>
    <node_template_defn_B_1>
    ...
    <node_template_defn_B_n>

1.6.1.5.2 Example

The following example shows the definition of three Compute nodes in the node_templates section of a topology_template as well as the grouping of two of the Compute nodes in a group server_group_1.

node_templates:
  server1:
    type: tosc1.nodes.Compute
    # more details ...

  server2:
    type: tosc1.nodes.Compute
    # more details ...

  server3:
    type: tosc1.nodes.Compute
    # more details ...

groups:
  server_group_1:
    members: [ server1, server2 ]
    policies:
      - anti_collocation_policy:
          # specific policy declarations omitted, as this is not yet specified

1.6.2 Notes

The parameters (properties) that are listed as part of the inputs block can be mapped to PropertyMappings provided as part of BoundaryDefinitions as described by the TOSCA v1.0 specification. The node templates listed as part of the node_templates block can be mapped to the list of NodeTemplate definitions provided as part of TopologyTemplate of a ServiceTemplate as described by the TOSCA v1.0 specification. The relationship templates listed as part of the relationship_templates block can be mapped to the list of RelationshipTemplate definitions provided as part of TopologyTemplate of a ServiceTemplate as described by the TOSCA v1.0 specification. The output parameters that are listed as part of the outputs section of a topology template can be mapped to PropertyMappings provided as part of BoundaryDefinitions as described by the TOSCA v1.0 specification. Note, however, that TOSCA v1.0 does not define a direction (input vs. output) for those mappings, i.e. TOSCA v1.0 PropertyMappings are underspecified in that respect and TOSCA Simple Profile’s inputs and outputs provide a more concrete definition of input and output parameters.

2. Functions.

This sections contains description of functions supported by DCM

2.1 Reserved Function Keywords

The following keywords MAY be used in some TOSCA function in place of a TOSCA Node or Relationship Template name. They will be interpreted by a TOSCA orchestrator at the time the function would be evaluated at runtime as described in the table below. Note that some keywords are only valid in the context of a certain TOSCA entity as also denoted in the table.

KeynameValid ContextsDescription
SELFNode Template or Relationship TemplateA TOSCA orchestrator will interpret this keyword as the Node or Relationship Template instance that contains the function at the time the function is evaluated.

2.3 Property functions

These functions are used within a service template to obtain property values from property definitions declared elsewhere in the same service template. These property definitions can appear either directly in the service template itself (e.g., in the inputs section) or on entities (e.g., node or relationship templates) that have been modeled within the template.

Note that the get_input and get_property functions may only retrieve the static values of property definitions of a TOSCA application as defined in the TOSCA Service Template. The get_attribute function should be used to retrieve values for attribute definitions (or property definitions reflected as attribute definitions) from the runtime instance model of the TOSCA application (as realized by the TOSCA orchestrator).

2.3.1 get_input

The get_input function is used to retrieve the values of properties declared within the inputs section of a TOSCA Service Template.

2.3.1.1 Grammar
get_input: <input_property_name>
2.3.1.2 Parameters
ParameterRequiredTypeDescription
<input_property_name>yesstringThe name of the property as defined in the inputs section of the service template.
2.3.1.3 Examples
inputs:
  cpus:
    type: integer

node_templates:
  my_server:
    type: tosca.nodes.Compute
    properties:
      num_cpus: { get_input: cpus }

2.3.2 get_property

The get_property function is used to retrieve property values between modelable entities defined in the same service template.
2.3.2.1 Grammar
get_property: <modelable_entity_name>, [<req_or_cap_name>], <property_name> [, <nested_property_name_1>, ..., <nested_property_name_*> ]
2.3.2.2 Parameters
ParameterRequiredTypeDescription
<modelable entity name> | SELF | SOURCE | TARGET | HOSTyesstringThe required name of a modelable entity (e.g., Node Template or Relationship Template name) as declared in the service template that contains the named property definition the function will return the value from.
<req_or_cap_name>nostringThe optional name of the requirement or capability name within the modelable entity (i.e., the which contains the named property definition the function will return the value from.
Note: If the property definition is located in the modelable entity directly, then this parameter MAY be omitted.
<property_name>yesstringThe name of the property definition the function will return the value from.
<nested_property_name_1> | nested_property_index_1,, ..., <nested_property_name_m> | nested_property_index_n,nostring | integerSome TOSCA properties are complex (i.e., composed as nested structures). These parameters are used to dereference into the names of these nested structures when needed.
Some properties represent list types. In these cases, an index may be provided to reference a specific entry in the list (as named in the previous parameter) to return.
2.3.2.3 Examples

The following example shows how to use the get_property function with an actual Node Template name:

node_templates:

  mysql_database:
    type: tosca.nodes.Database
    properties:
      db_name: sql_database1

  wordpress:
    type: tosca.nodes.WebApplication.WordPress
    ...
    interfaces:
      Standard:
        configure:
          inputs:
            wp_db_name: { get_property: [ mysql_database, db_name ] }

2.4 Attribute functions

These functions (attribute functions) are used within an instance model to obtain attribute values from instances of nodes and relationships that have been created from an application model described in a service template. The instances of nodes or relationships can be referenced by their name as assigned in the service template or relative to the context where they are being invoked.

2.4.1 get_attribute

The get_attribute function is used to retrieve the values of named attributes declared by the referenced node or relationship template name.

2.4.1.1 Grammar

get_attribute: <modelable_entity_name>, [<req_or_cap_name>], <attribute_name> [, <nested_attribute_name_1>, ..., <nested_attribute_name_x> ]

2.4.1.2 Parameters
ParameterRequiredTypeDescription
<modelable entity name> | SELF | SOURCE | TARGET | HOSTyesstringThe required name of a modelable entity (e.g., Node Template or Relationship Template name) as declared in the service template that contains the named attribute definition the function will return the value from.
<req_or_cap_name>nostringThe optional name of the requirement or capability name within the modelable entity (i.e., the which contains the named property definition the function will return the value from.
Note: If the attribute definition is located in the modelable entity directly, then this parameter MAY be omitted.
<attribute_name>yesstringThe name of the property definition the function will return the value from.
<nested_attribute_name_1> | nested_attribute_index_1,, ..., <nested_attribute_name_m> | nested_attribute_index_n,nostring | integerSome TOSCA attribute are complex (i.e., composed as nested structures). These parameters are used to dereference into the names of these nested structures when needed.
Some attributes represent list types. In these cases, an index may be provided to reference a specific entry in the list (as named in the previous parameter) to return.
2.4.1.3 Examples:

The attribute functions are used in the same way as the equivalent Property functions described above. Please see their examples and replace “get_property” with “get_attribute” function name.

2.4.2 Notes

These functions are used to obtain attributes from instances of node or relationship templates by the names they were given within the service template that described the application model (pattern).

2.5 Operation functions

These functions are used within an instance model to obtain values from interface operations. These can be used in order to set an attribute of a node instance at runtime or to pass values from one operation to another.

2.5.1 get_operation_output

The get_operation_output function is used to retrieve the values of life-cycle script from an interface operation only, Return value must be in JSON format to be correctly parsed. Note: This only applies to SoftwareComponents derived nodes and with Attribute.

2.5.1.1 Grammar

get_operation_output: <modelable_entity_name>, <interface_name>, <operation_name>, <output_variable_name>

2.5.1.2 Parameters
ParameterRequiredTypeDescription
<modelable entity name> | SELF | SOURCE | TARGET yesstringThe required name of a modelable entity (e.g., Node Template or Relationship Template name) as declared in the service template that implements the named interface and operation.
<interface_name>yesstringThe required name of the interface which defines the operation.
<operation_name>yesstringThe required name of the operation whose value we would like to retrieve.
<output_variable_name>yesstringThe required name of the variable that is exposed / exported by the operation.
2.5.1.3 Notes

If operation failed, then ignore its outputs. Orchestrators should allow orchestrators to continue running when possible past deployment in the lifecycle. For example, if an update fails, the application should be allowed to continue running and some other method would be used to alert administrators of the failure.

2.8 DCM Functions

2.8.1 func_join

The function func_join is used to join/concatenate values together in the template with defined delimiter

2.8.1.1 Grammar
func_join: <join delimiter> [ array of parameters to join ]
2.8.1.2 Parameters
ParameterRequiredTypeDescription
<Join delimiter>yesstringDelimiter string that will separate each item in the array of values
[ array of parameters to join ]yesstringArray of values that will be joined/concatenated in to single string
2.8.1.3 Example

Example:

type: baseVM
    properties:
      name:  { func_join: ["-", [{ get_input: name }, "web"]]}

Create required web server name by adding “web” to the name of application stack with “-” delimiter.

2.8.2 get_random_str

The function get_random_str is used to generate random string of characters.

2.8.2.1 Grammar

get_random_str: [<string length>, <include special characters>]

2.8.2.2 Parameters
ParameterRequiredTypeDescription
<string length>yesstringLength of the string to generate
<include special characters>nobooltrue - generate string with special characters. At least one special character will be used
false (deafult) generate string without special characters.
Note: Special characters are defined as: "!#$$&()*+,-./:;<=>?@[\\]^_`{|}~”
2.8.2.3 Example

Example:

type: baseVM
    properties:
      password:  { get_random_str: [10, true]}

3. TOSCA normative type definitions

The declarative approach is heavily dependent of the definition of basic types that a declarative container must understand. The definition of these types must be very clear such that the operational semantics can be precisely followed by a declarative container to achieve the effects intended by the modeler of a topology in an interoperable manner.

3.1 Assumptions

Assumes alignment with/dependence on XML normative types proposal for TOSCA v1.1 Assumes that the normative types will be versioned and the TOSCA TC will preserve backwards compatibility. Assumes that security and access control will be addressed in future revisions or versions of this specification.

3.2 Data Types

Note

No Data Types are defined in DCM implementation.

3.3 Capabilities Types

3.3.1 tosca.capabilities.Root

This is the default (root) TOSCA Capability Type definition that all other TOSCA Capability Types derive from.

3.3.1.1 Definition

tosca.capabilities.Root:

3.3.2 dcm.capabilities.Container

The Container capability, when included on a Node Type or Template definition, indicates that the node can act as a container for (or a host for) one or more other declared Node Types.

Shorthand NameContainer
Type Qualified Nametosca:Container
Type URItosca.capabilities.Container
3.3.3.2 Definition
tosca.capabilities.Container:
    derived_from: dcm.capabilities.Feature

3.4 Requirement Types

There are no normative Requirement Types currently defined in this working draft. Typically, Requirements are described against a known Capability Type

3.5 Relationship Types

DCM does not implement any Relationship Types at the moment.

3.5.1 tosca.relationships.Root

This is the default (root) TOSCA Relationship Type definition that all other TOSCA Relationship Types derive from.

3.5.1.1 Attributes

NameRequiredTypeConstraintsDescription
tosca_idyesstringNoneA unique identifier of the realized instance of a Relationship Template that derives from any TOSCA normative type.
tosca_nameyesstringNoneThis attribute reflects the name of the Relationship Template as defined in the TOSCA service template. This name is not unique to the realized instance model of corresponding deployed application as each template in the model can result in one or more instances (e.g., scaled) when orchestrated to a provider environment.
3.5.1.2 Definition
tosca.relationships.Root:
  # The TOSCA root relationship type has no property mappings
  interfaces: [ tosca.interfaces.relationship.Configure ]
  valid_targets: [ tosca.capabilities.Root ]
  attributes:
    tosca_id:
      type: string
    tosca_name:
      type: string

3.5.2 tosca.relationships.DependsOn

This type represents a general dependency relationship between two nodes. Shorthand Name DependsOn Type Qualified Name tosca:DependsOn Type URI tosca.relationships.DependsOn

3.5.2.1 Definition
tosca.relationships.DependsOn:
  derived_from: tosca.relationships.Root
valid_targets: [ tosca.capabilities.Feature ]

3.5.3 tosca.relationships.HostedOn

This type represents a hosting relationship between two nodes. Shorthand Name HostedOn Type Qualified Name tosca:HostedOn Type URI tosca.relationships.HostedOn

3.5.3.1 Definition
tosca.relationships.HostedOn:
  derived_from: tosca.relationships.DependsOn
  valid_targets: [ tosca.capabilities.Container ]

3.5.4 tosca.relationships.ConnectsTo

This type represents a hosting relationship between two nodes.

Shorthand NameConnectsTo
Type Qualified NameConnectsTo
Type URItosca.relationships.ConnectsTo
3.5.3.1 Definition
tosca.relationships.ConnectsTo:
    derived_from: tosca.relationships.ConnectsTo
    valid_targets: [ tosca.capabilities.Endpoint ]

3.6 Interface Types

Interfaces are reusable entities that define a set of operations that that can be included as part of a Node type or Relationship Type definition. Each named operations may have code or scripts associated with them that orchestrators can execute for when transitioning an application to a given state.

3.6.1 Requirements

Designers of Node or Relationship types are not required to actually provide/associate code or scripts with every operation for a given interface it supports. In these cases, orchestrators SHALL consider that a “No Operation” or “no-op”. Template designers MAY provide or override code or scripts provided by a type for a specified interface defined for the type (even if the type itself does not provide a script for that operation).

3.6.2 tosca.interfaces.node.lifecycle.Standard

This lifecycle interface defines the essential, normative operations that TOSCA nodes may support.

Shorthand NameStandard
Type Qualified Nametosca: Standard
Type URItosca.interfaces.node.lifecycle.Standard
3.6.2.1 Definition
tosca.interfaces.node.lifecycle.Standard:
  create:
    description: Standard lifecycle create operation.
  configure:
    description: Standard lifecycle configure operation (pre-start).
  start:
    description: Standard lifecycle start operation.
  stop:
    description: Standard lifecycle stop operation.
  delete:
    description: Standard lifecycle delete operation.
3.6.2.2 Operation sequencing and node state

The following diagrams show how TOSCA orchestrators sequence the operations of the Standard lifecycle in normal node startup and shutdown procedures.

../_images/image002.png

The following key should be used to interpret the diagrams:

3.6.2.2.1 Normal node startup sequence diagram

The following diagram shows how the TOSCA orchestrator would invoke operations on the Standard lifecycle to shut down a node.

../_images/image003.png

3.6.2.2.2 Normal node shutdown sequence diagram

../_images/image004.png

The following diagram shows how the TOSCA orchestrator would invoke operations on the Standard lifecycle to shut down a node.

3.7 Node Types

3.7.1 tosca.nodes.Root

The TOSCA Root Node Type is the default type that all other TOSCA base Node Types derive from. This allows for all TOSCA nodes to have a consistent set of features for modeling and management (e.g., consistent definitions for requirements, capabilities and lifecycle interfaces).

3.7.1.1 Properties

The TOSCA Root Node type has no specified properties.

3.7.2 tosca.nodes.SoftwareComponent

The TOSCA SoftwareComponent node represents a generic software component that can be managed and run by a TOSCA Compute Node Type.

Shorthand NameSoftwareComponent
Type Qualified Nametosca:SoftwareComponent
Type URItosca.nodes.SoftwareComponent
3.7.3.1 Properties
NameRequiredTypeConstraintsDescription
component_versionnoversionNoneThe software component’s version.
3.7.3.2 Attributes
NameRequiredTypeConstraintsDescription
ip_addressnostringstatus: deprecatedThe first public IP address assigned to the host Compute node.
Default: get_attribute ( SELF, host, ip_address)
3.7.3.3 Definition
tosca.nodes.SoftwareComponent:
  derived_from: tosca.nodes.Root
  properties:
    # domain-specific software component version
    component_version:
      type: version
      required: false
  attributes:
    # Deprecated
    ip_address:
      type: string
      status: deprecated
      default: { get_attribute: [ SELF, host, ip_address ] }

  requirements:
    - host:
        node: tosca.nodes.Compute
        relationship: tosca.relationships.HostedOn

..note:: Nodes that can directly be managed and run by a TOSCA Compute Node Type SHOULD extend from this type.

4. DCM “group” extension to TOSCA

Grouping resources simplifies defining auto-scaling, auto-healing and other policies for resources in a stack.

Resource group or group – a subset of resources in a stack that share policies. Policy – details of actions that can be taken on a resource or set of resources either requested by a user or automatically triggered by some condition Measurement – some test or property providing information about the state of a resource Criterion – a logical true/false test that can be applied to the result of a measurement

4.1 Definitions

groups:
    resource_group_1:
        ...
    resource_group_2:
        ....

4.2 members

4.3 properties

NameRequiredTypeConstraintsDescription
instancesnointNoneInitial number of a instances (part of defined group) that will be created at launch
minInstancesnointNoneMinimum number of instances that the group policy can be reduced to.
maxInstancesnointNoneMaximum number of instances that the group policy can be increased to.
coolDownnointNoneCooldown period in seconds between policy actions can be applied or executed.

4.4 actions

Defines actions that will be taken by orchestration engine when policy conditions are violated or triggered.

NameRequiredTypeConstraintsDescription
ScaleUpGroupnodcm.policy.action.ScaleUpGroupNoneAction that instructs orchestration engine to scale up group
ScaleDownGroupnodcm.policy.action.ScaleDownGroupNoneAction that instructs orchestration engine to scale down group
RestartResourcenodcm.policy.action.RestartResourceNoneAction that instructs orchestration engine to heal by restarting resources group

4.5 measurements

Defines measurements (ie monitors) that will be taken and then consumed by policy engine.

NameRequiredTypeConstraintsDescription
CpuIdlenodcm.policy.measurement.CpuIdleNoneMeasures CPU utilization metric: CPU Idle
ResourceStatusnodcm.policy.measurement.ResourceStatusNoneTODO

4.6 criteria

NameRequiredTypeConstraintsDescription
SeriesLessThannodcm.policy.criteria.SeriesLessThanNoneTODO
SeriesMoreThannodcm.policy.criteria.SeriesMoreThanNoneTODO
Falsenodcm.policy.criteria.FalseNoneTODO

4.7 policies

4.7.1 dcm.policy.types.BasicPolicy

TODO

4.8 Example

groups:
    resource_group_1:
      members: [vm]
      properties:
        instances: 2
        minInstances: 1
        maxInstances: 10
        # after one manual or automatic action is performed against a stack,
        # wait this long (seconds) before performing autoscale or autoheal
        coolDown: 1800

      # defines details of various actions that could be taken,
      # the policy just refers to them by name
      # note that some actions (ie- scaling) apply to the whole resource group
      # while other actions (ie- repair) apply just to one resource
      actions:
        scale_up:
          type: dcm.policy.action.ScaleUpGroup
        scale_down:
          type: dcm.policy.action.ScaleDownGroup
        repair:
          type: dcm.policy.action.RestartResource

      # define all measurements to be performed against resources
      # policy will refer to them by name
      # plus special provider-status type is used internally to report resource health
      measurements:
        # VM agent will report last 15 samples of cpu %idle time measured in 30-second intervals
        cpu_idle_time:
          type: dcm.policy.measurement.CpuIdle

        # even if not used explicitly by a policy, include this to enable UX health status
        # status reported by cloud must be active, and for VMs, agent heartbeat must succeed
        # otherwise resource will be marked as DEGRADED
        cloud_reported_status:
          type: dcm.policy.measurement.ResourceStatus

      criteria:
        twice_below_5:
          type: dcm.policy.criteria.SeriesLessThan
        twice_above_95:
          type: dcm.policy.criteria.SeriesMoreThan
        check_fails:
          type: dcm.policy.criteria.False

      policies:
        # when last 2 periods of idle time reported are both <5%, perform scale_up action
        # when last 2 periods of idle time reported are both >95%, perform scale_down action
        #
        scale_up_on_cpu:
          type: dcm.policy.types.BasicPolicy
          measurement: cpu_idle_time
          criterion: twice_below_5
          actions: [scale_up]
        scale_down_on_cpu:
          type: dcm.policy.types.BasicPolicy
          measurement: cpu_idle_time
          criterion: twice_above_95
          actions: [scale_down]

        # when cloud status of resource is marked not healthy, terminate and restart it
        repair_on_status:
          type: dcm.policy.types.BasicPolicy
          measurement: cloud_reported_status
          criterion: check_fails
          actions: [repair]