Example 1 - TOSCA Simple "Hello
World" 13
Example 2 - Template with input and
output parameter sections. 15
Example 3 - Simple (MySQL) software
installation on a TOSCA Compute node. 16
Example 4 - Node Template overriding
its Node Type's "configure" interface. 18
Example 5 - Template for deploying
database content on-top of MySQL DBMS middleware. 19
Example 6 - Basic two-tier application
(web application and database server tiers) 21
Example 7 - Providing a custom
relationship script to establish a connection. 23
Example 8 - A web application Node
Template requiring a custom database connection type. 25
Example 9 - Defining a custom
relationship type. 26
Example 10 - Simple dependency
relationship between two nodes. 26
Example 11 - An abstract
"host" requirement using a node filter 28
Example 12 - An abstract Compute node template
with a node filter 29
Example 13 - An abstract database
requirement using a node filter 30
Example 14 - An abstract database node
template. 31
Example 15 - Referencing an abstract
database node template. 33
Example 16 - Using substitution
mappings to export a database implementation. 35
Example 17 - Declaring a transaction
subsystem as a chain of substitutable node templates. 37
Example 18 - Defining a
TransactionSubsystem node type. 39
Example 19 - Implementation of a
TransactionSubsytem node type using substitution mappings. 40
Example 20 - Grouping Node Templates
for possible policy application. 46
Example 21 - Grouping nodes for anti-colocation
policy application. 47
Example 22 - Using YAML anchors in
TOSCA templates. 48
Example 23 - Properties reflected as
attributes. 53
Example 24 – TOSCA SD-WAN Service
Template. 55
Example 25 – TOSCA SD-WAN Service
Template. 56
Example 26 – TOSCA SD-WAN Service
Template. 57
Figure 1: Using template substitution
to implement a database tier 33
Figure 2: Substitution mappings. 35
Figure 3: Chaining of subsystems in a
service template. 37
Figure 4: Defining subsystem details in
a service template. 40
Figure‑5: Typical 3-Tier Network. 269
Figure‑6: Generic Service
Template. 278
Figure‑7: Service template with
network template A. 278
Figure‑8: Service template with
network template B. 279
This specification is provided under the RF
on Limited Terms Mode of the OASIS IPR Policy,
the mode chosen when the Technical Committee was established. For information
on whether any patents have been disclosed that may be essential to
implementing this specification, and any offers of patent licensing terms,
please refer to the Intellectual Property Rights section of the TC’s web page (https://www.oasis-open.org/committees/tosca/ipr.php).
The TOSCA Simple Profile in YAML specifies a rendering of
TOSCA which aims to provide a more accessible syntax as well as a more concise
and incremental expressiveness of the TOSCA DSL in order to minimize the
learning curve and speed the adoption of the use of TOSCA to portably describe
cloud applications.
This proposal describes a YAML rendering for TOSCA. YAML is
a human friendly data serialization standard (http://yaml.org/)
with a syntax much easier to read and edit than XML. As there are a number of
DSLs encoded in YAML, a YAML encoding of the TOSCA DSL makes TOSCA more
accessible by these communities.
This proposal prescribes an isomorphic rendering in YAML of
a subset of the TOSCA v1.0 XML specification ensuring that TOSCA semantics are
preserved and can be transformed from XML to YAML or from YAML to XML.
Additionally, in order to streamline the expression of TOSCA semantics, the
YAML rendering is sought to be more concise and compact through the use of the
YAML syntax.
The TOSCA metamodel uses the
concept of service templates that describe cloud workloads as a topology
template, which is a graph of node templates modeling the components a workload
is made up of and of relationship templates modeling the relations between
those components. TOSCA further provides a type system of node types to
describe the possible building blocks for constructing a service template, as
well as relationship types to describe possible kinds of relations. Both node
and relationship types may define lifecycle operations to implement the
behavior an orchestration engine can invoke when instantiating a service
template. For example, a node type for some software product might provide a
‘create’ operation to handle the creation of an instance of a component at
runtime, or a ‘start’ or ‘stop’ operation to handle a start or stop event
triggered by an orchestration engine. Those lifecycle operations are backed by
implementation artifacts such as scripts or Chef recipes that implement the
actual behavior.
An orchestration engine
processing a TOSCA service template uses the mentioned lifecycle operations to
instantiate single components at runtime, and it uses the relationship between
components to derive the order of component instantiation. For example, during
the instantiation of a two-tier application that includes a web application
that depends on a database, an orchestration engine would first invoke the
‘create’ operation on the database component to install and configure the
database, and it would then invoke the ‘create’ operation of the web
application to install and configure the application (which includes
configuration of the database connection).
The TOSCA simple profile
assumes a number of base types (node types and relationship types) to be
supported by each compliant environment such as a ‘Compute’ node type, a
‘Network’ node type or a generic ‘Database’ node type. Furthermore, it is
envisioned that a large number of additional types for use in service templates
will be defined by a community over time. Therefore, template authors in many
cases will not have to define types themselves but can simply start writing
service templates that use existing types. In addition, the simple profile will
provide means for easily customizing and extending existing types, for example
by providing a customized ‘create’ script for some software.
Different kinds of processors
and artifacts qualify as implementations of the TOSCA simple profile. Those
that this specification is explicitly mentioning or referring to fall into the
following categories:
·
TOSCA YAML service template (or “service template”): A YAML
document artifact containing a (TOSCA) topology template (see sections 3.9
“Service template definition”) that represents a Cloud application. (see
sections 3.8 “Topology template definition”)
·
TOSCA processor (or “processor”): An engine or tool that is
capable of parsing and interpreting a TOSCA service template for a particular
purpose. For example, the purpose could be validation, translation or visual
rendering.
·
TOSCA orchestrator (also called orchestration engine): A TOSCA
processor that interprets a TOSCA service template or a TOSCA CSAR in order to
instantiate, deploy, and manage the described application in a Cloud.
·
TOSCA generator: A tool that generates a TOSCA service template.
An example of generator is a modeling tool capable of generating or editing a
TOSCA service template (often such a tool would also be a TOSCA processor).
·
TOSCA archive (or TOSCA Cloud Service Archive, or “CSAR”): a
package artifact that contains a TOSCA service template and other artifacts
usable by a TOSCA orchestrator to deploy an application.
The above list is not
exclusive. The above definitions should be understood as referring to and
implementing the TOSCA simple profile as described in this document
(abbreviated here as “TOSCA” for simplicity).
The TOSCA language introduces a YAML grammar for describing
service templates by means of Topology Templates and towards enablement of
interaction with a TOSCA instance model perhaps by external APIs or plans. The
primary focus currently is on design time aspects, i.e. the description of
services to ensure their exchange between Cloud providers, TOSCA Orchestrators
and tooling.
The language provides an extension mechanism that can be
used to extend the definitions with additional vendor-specific or
domain-specific information.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”,
“SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in
this document are to be interpreted as described in [RFC2119].
·
Sections that are titled “Example” throughout this document are
considered non-normative.
·
A feature marked as deprecated
in a particular version will be removed in the subsequent version of the
specification.
|
Reference Tag
|
Description
|
|
[RFC2119]
|
S. Bradner, Key words for use in RFCs
to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt,
IETF RFC 2119, March 1997.
|
|
[TOSCA-1.0]
|
Topology and Orchestration Topology and
Orchestration Specification for Cloud Applications (TOSCA) Version 1.0, an
OASIS Standard, 25 November 2013, http://docs.oasis-open.org/tosca/TOSCA/v1.0/os/TOSCA-v1.0-os.pdf
|
|
[YAML-1.2]
|
YAML, Version 1.2, 3rd Edition, Patched
at 2009-10-01, Oren Ben-Kiki, Clark Evans, Ingy döt Net http://www.yaml.org/spec/1.2/spec.html
|
|
[YAML-TS-1.1]
|
Timestamp Language-Independent Type for
YAML Version 1.1, Working Draft 2005-01-18, http://yaml.org/type/timestamp.html
|
|
Reference Tag
|
Description
|
|
[Apache]
|
Apache Server, https://httpd.apache.org/
|
|
[Chef]
|
Chef, https://chef.io
|
|
[NodeJS]
|
Node.js, https://nodejs.org/
|
|
[Puppet]
|
Puppet, http://puppetlabs.com/
|
|
[WordPress]
|
WordPress, https://wordpress.org/
|
|
[Maven-Version]
|
https://cwiki.apache.org/confluence/display/MAVEN/Version+number+policy
|
|
[JSON-Spec]
|
|
|
[JSON-Schema]
|
|
|
[XMLSpec]
|
XML Specification, W3C Recommendation,
February 1998,
http://www.w3.org/TR/1998/REC-xml-19980210
|
|
[XML Schema Part 1]
|
XML Schema Part 1: Structures, W3C
Recommendation, October 2004,
http://www.w3.org/TR/xmlschema-1/
|
|
[XML Schema Part 2]
|
XML Schema Part 2: Datatypes, W3C
Recommendation, October 2004,
http://www.w3.org/TR/xmlschema-2/
|
|
[IANA register for
Hash Function Textual Names]
|
https://www.iana.org/assignments/hash-function-text-names/hash-function-text-names.xhtml
|
|
[Jinja2]
|
Jinja2, jinja.pocoo.org/
|
|
[Twig]
|
Twig, https://twig.symfony.com
|
The following terms are used throughout this
specification and have the following definitions when used in context of this
document.
|
Term
|
Definition
|
|
Instance Model
|
A deployed service is a running instance of a Service
Template. More precisely, the instance is derived by instantiating the
Topology Template of its Service Template, most often by running a declarative
workflow that is automatically generated based on the node templates and
relationship templates defined in the Topology Template.
|
|
Node Template
|
A Node Template specifies the occurrence of a
component node as part of a Topology Template. Each Node Template refers to a
Node Type that defines the semantics of the node (e.g., properties,
attributes, requirements, capabilities, interfaces). Node Types are defined
separately for reuse purposes.
|
|
Relationship Template
|
A Relationship Template specifies the occurrence of
a relationship between nodes in a Topology Template. Each Relationship
Template refers to a Relationship Type that defines the semantics
relationship (e.g., properties, attributes, interfaces, etc.). Relationship
Types are defined separately for reuse purposes.
|
|
Service
Template
|
A Service Template is typically
used to specify the “topology” (or structure) and “orchestration” (or
invocation of management behavior) of IT services so that they can be
provisioned and managed in accordance with constraints and policies.
Specifically, TOSCA Service Templates
optionally allow definitions of a TOSCA Topology
Template, TOSCA types (e.g., Node, Relationship, Capability, Artifact,
etc.), groupings, policies and constraints along with any input or output
declarations.
|
|
Topology
Model
|
The term Topology Model is often used
synonymously with the term Topology
Template with the use of “model” being prevalent when considering a
Service Template’s topology definition as an abstract representation
of an application or service to facilitate understanding of its functional
components and by eliminating unnecessary details.
|
|
Topology
Template
|
A Topology Template defines the
structure of a service in the context of a Service Template. A Topology
Template consists of a set of Node Template and Relationship Template
definitions that together define the topology model of a service as a (not
necessarily connected) directed graph.The term Topology Template is often
used synonymously with the term Topology Model.
The distinction is that a topology template can be used to instantiate and
orchestrate the model as a reusable pattern and includes all
details necessary to accomplish it.
|
|
Abstract Node Template
|
An abstract node template is a node
template that doesn’t define any implementations for the TOSCA lifecycle
management operations. Service designers explicitly mark node templates as
abstract using the substitute directive. TOSCA
orchestrators provide implementations for abstract node templates by finding
substituting templates for those node templates.
|
|
No-Op Node Template
|
A No-Op node template is a node template
that does not specify implementations for any of its operations, but is not
marked as abstract. No-op templates only act as placeholders for information
to be used by other node templates and do not need to be orchestrated.
|
This non-normative section contains several sections
that show how to model applications with TOSCA Simple Profile using YAML by
example starting with a “Hello World” template up through examples that show
complex composition modeling.
2.1 A “hello world” template for TOSCA Simple
Profile in YAML
As mentioned before, the TOSCA
simple profile assumes the existence of a small set of pre-defined, normative
set of node types (e.g., a ‘Compute’ node) along with other types, which will
be introduced through the course of this document, for creating TOSCA Service
Templates. It is envisioned that many additional node types for building
service templates will be created by communities. Some may be published as
profiles that build upon the TOSCA Simple Profile specification. Using the
normative TOSCA Compute node type, a very basic “Hello World” TOSCA template
for deploying just a single server would look as follows:
Example 1
- TOSCA Simple "Hello World"
|
tosca_definitions_version: tosca_simple_yaml_1_3tosca_simple_yaml_1_3
description:
Template for deploying a single server with predefined properties.
topology_template:
node_templates:
db_server:
type: tosca.nodes.Compute
capabilities:
# Host container properties
host:
properties:
num_cpus: 1
disk_size: 10 GB
mem_size: 4096 MB
# Guest Operating System properties
os:
properties:
# host Operating System image properties
architecture: x86_64
type: linux
distribution: rhel
version: 6.5
|
The template above contains a very simple topology
template” with only a single ‘Compute’ node template named “db_server that declares some basic values for
properties within two of the several capabilities that are built into the
Compute node type definition. All TOSCA Orchestrators are expected to know how
to instantiate a Compute node since it is normative and expected to represent a
well-known function that is portable across TOSCA implementations. This
expectation is true for all normative TOSCA Node and Relationship types that
are defined in the Simple Profile specification. This means, with TOSCA’s
approach, that the application developer does not need to provide any
deployment or implementation artifacts that contain code or logic to
orchestrate these common software components. TOSCA orchestrators simply
select or allocate the correct node (resource) type that fulfills the
application topologies requirements using the properties declared in the node
and its capabilities.
In the above example, the “host”
capability contains properties that allow application developers to optionally
supply the number of CPUs, memory size and disk size they believe they need
when the Compute node is instantiated in order to run their applications.
Similarly, the “os” capability is used
to provide values to indicate what host operating system the Compute node
should have when it is instantiated.
The logical diagram of the “hello world” Compute node would
look as follows:
As you can see, the Compute
node also has attributes and other built-in capabilities, such as Bindable and Endpoint, each with additional properties
that will be discussed in other examples later in this document. Although the
Compute node has no direct properties apart from those in its capabilities,
other TOSCA node type definitions may have properties that are part of the node
type itself in addition to having Capabilities. TOSCA orchestration engines
are expected to validate all property values provided in a node template
against the property definitions in their respective node type definitions
referenced in the service template. The tosca_definitions_version
keyname in the TOSCA service template identifies the versioned set of
normative TOSCA type definitions to use for validating those types defined in
the TOSCA Simple Profile including the Compute node type. Specifically, the
value tosca_simple_yaml_1_3 indicates
Simple Profile v1.3.0 definitions would be used for validation. Other type
definitions may be imported from other service templates using the import keyword discussed later.
Typically, one would want to
allow users to customize deployments by providing input parameters instead of
using hardcoded values inside a template. In addition, output values are provided
to pass information that perhaps describes the state of the deployed template
to the user who deployed it (such as the private IP address of the deployed
server). A refined service template with corresponding inputs and outputs
sections is shown below.
Example 2 - Template with
input and output parameter sections
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template for deploying a single server with predefined properties.
topology_template:
inputs:
db_server_num_cpus:
type: integer
description: Number of CPUs for the server.
constraints:
- valid_values: [ 1, 2, 4, 8 ]
node_templates:
db_server:
type: tosca.nodes.Compute
capabilities:
# Host container properties
host:
properties:
# Compute properties
num_cpus: { get_input: db_server_num_cpus }
mem_size: 2048 MB
disk_size: 10 GB
mem_size: 4096 MB
#
Guest Operating System properties
os:
# omitted for brevity
outputs:
server_ip:
description: The private IP address of the provisioned server.
value: { get_attribute: [ db_server, private_address ] }
|
The inputs and
outputs sections are contained in the topology_template element of the TOSCA
template, meaning that they are scoped to node templates within the topology
template. Input parameters defined in the inputs section can be assigned to
properties of node template within the containing topology template; output
parameters can be obtained from attributes of node templates within the
containing topology template.
Note that the inputs
section of a TOSCA template allows for defining optional constraints on each
input parameter to restrict possible user input. Further note that TOSCA
provides for a set of intrinsic functions like get_input, get_property
or get_attribute to reference elements
within the template or to retrieve runtime values.
2.2 TOSCA template for a simple software
installation
Software installations can be modeled in TOSCA as node
templates that get related to the node template for a server on which the
software would be installed. With a number of existing software node types
(e.g. either created by the TOSCA work group or a community) template authors
can just use those node types for writing service templates as shown below.
Example 3 - Simple (MySQL) software installation on a
TOSCA Compute node
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template for deploying a single server with MySQL software on top.
topology_template:
inputs:
mysql_rootpw:
type: string
mysql_port:
type: integer
# rest omitted here for brevity
node_templates:
db_server:
type: tosca.nodes.Compute
#
rest omitted here for brevity
mysql:
type: tosca.nodes.DBMS.MySQL
properties:
root_password: { get_input: mysql_rootpw }
port: { get_input: mysql_port }
requirements:
- host: db_server
outputs:
#
omitted here for brevity
|
The example above makes use of a node type tosca.nodes.DBMS.MySQL for the mysql node template to install MySQL on a
server. This node type allows for setting a property root_password to adapt the password of the
MySQL root user at deployment. The set of properties and their schema has been
defined in the node type definition. By means of the get_input function, a value provided by the user at
deployment time is used as the value for the root_password
property. The same is true for the port
property.
The mysql node template is related to the db_server node template (of type tosca.nodes.Compute) via the requirements section to indicate where
MySQL is to be installed. In the TOSCA metamodel, nodes get related to each
other when one node has a requirement against some capability provided by
another node. What kinds of requirements exist is defined by the respective
node type. In case of MySQL, which is software that needs to be installed or
hosted on a compute resource, the underlying node type named tosca.nodes.SoftwareComponent has a
predefined requirement called host,
which needs to be fulfilled by pointing to a node template of type tosca.nodes.Compute.
The
logical relationship between the mysql
node and its host db_server node would
appear as follows:
Within the list of requirements, each list entry is a map that
contains a single key/value pair where the symbolic name of a requirement
definition is the key and the identifier of the fulfilling node is the value.
The value is essentially the symbolic name of the other node template;
specifically, or the example above, the host
requirement is fulfilled by referencing the db_server
node template. The underlying TOSCA DBMS
node type already has a complete requirement definition for the host requirement of type Compute and assures that a HostedOn TOSCA relationship will
automatically be created and will only allow a valid target host node is of
type Compute. This approach allows the
template author to simply provide the name of a valid Compute node (i.e., db_server) as the value for the mysql node’s host requirement and not worry about defining
anything more complex if they do not want to.
Node types in TOSCA have
associated implementations that provide the automation (e.g. in the form of
scripts such as Bash, Chef or Python) for the normative lifecycle operations of
a node. For example, the node type implementation for a MySQL database would
associate scripts to TOSCA node operations like configure, start,
or stop to manage the state of MySQL at
runtime.
Many node types may already
come with a set of operational scripts that contain basic commands that can
manage the state of that specific node. If it is desired, template authors can
provide a custom script for one or more of the operations defined by a node
type in their node template which will override the default implementation in
the type. The following example shows a mysql
node template where the template author provides their own configure script:
Example 4 - Node Template overriding its Node Type's
"configure" interface
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template for deploying a single server with MySQL software on top.
topology_template:
inputs:
#
omitted here for brevity
node_templates:
db_server:
type: tosca.nodes.Compute
#
rest omitted here for brevity
mysql:
type: tosca.nodes.DBMS.MySQL
properties:
root_password: { get_input: mysql_rootpw }
port: { get_input: mysql_port }
requirements:
- host: db_server
interfaces:
Standard:
configure: scripts/my_own_configure.sh
outputs:
# omitted
here for brevity
|
In the example above, the my_own_configure.sh script is provided for
the configure operation of the MySQL
node type’s Standard lifecycle
interface. The path given in the example above (i.e., ‘scripts/’) is
interpreted relative to the template file, but it would also be possible to
provide an absolute URI to the location of the script.
In other words, operations
defined by node types can be thought of as “hooks” into which automation can be
injected. Typically, node type implementations provide the automation for those
“hooks”. However, within a template, custom automation can be injected to run
in a hook in the context of the one, specific node template (i.e. without
changing the node type).
In the Example 4, shown above,
the deployment of the MySQL middleware only, i.e. without actual database
content was shown. The following example shows how such a template can be
extended to also contain the definition of custom database content on-top of
the MySQL DBMS software.
Example 5 - Template for deploying database content
on-top of MySQL DBMS middleware
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template for deploying a single server with predefined properties.
topology_template:
inputs:
wordpress_db_name:
type: string
wordpress_db_user:
type: string
wordpress_db_password:
type: string
#
rest omitted here for brevity
node_templates:
db_server:
type: tosca.nodes.Compute
#
rest omitted here for brevity
mysql:
type: tosca.nodes.DBMS.MySQL
#
rest omitted here for brevity
wordpress_db:
type: tosca.nodes.Database.MySQL
properties:
name: { get_input: wordpress_db_name }
user: { get_input: wordpress_db_user }
password: { get_input: wordpress_db_password }
artifacts:
db_content:
file: files/wordpress_db_content.txt
type: tosca.artifacts.File
requirements:
- host: mysql
interfaces:
Standard:
create:
implementation: db_create.sh
inputs:
# Copy DB file artifact to server’s staging area
db_data: { get_artifact: [ SELF, db_content ] }
outputs:
#
omitted here for brevity
|
In the example above, the wordpress_db node template of type tosca.nodes.Database.MySQL represents an
actual MySQL database instance managed by a MySQL DBMS installation. The requirements section of the wordpress_db node template expresses that the
database it represents is to be hosted on a MySQL DBMS node template named mysql which is also declared in this
template.
In the artifacts section of the wordpress_db the node template, there is an
artifact definition named db_content
which represents a text file wordpress_db_content.txt
which in turn will be used to add content to the SQL database as part of the create operation.
As you can see above, a script is associated with the create
operation with the name db_create.sh.
The TOSCA Orchestrator sees that this is not a named artifact declared in the
node’s artifact section, but instead a filename for a normative TOSCA
implementation artifact script type (i.e., tosca.artifacts.Implementation.Bash).
Since this is an implementation type for TOSCA, the orchestrator will execute
the script automatically to create the node on db_server, but first it will prepare the
local environment with the declared inputs for the operation. In this case, the
orchestrator would see that the db_data
input is using the get_artifact
function to retrieve the file (wordpress_db_content.txt)
which is associated with the db_content
artifact name prior to executing the db_create.sh
script.
The logical diagram for this example would appear as
follows:
Note that while it would be
possible to define one node type and corresponding node templates that
represent both the DBMS middleware and actual database content as one entity,
TOSCA normative node types distinguish between middleware (container) and
application (containee) node types. This allows on one hand to have better
re-use of generic middleware node types without binding them to content running
on top of them, and on the other hand this allows for better substitutability
of, for example, middleware components like a DBMS during the deployment of
TOSCA models.
The definition of multi-tier
applications in TOSCA is quite similar to the example shown in section 2.2, with the only difference that multiple software node stacks (i.e., node templates
for middleware and application layer components), typically hosted on different
servers, are defined and related to each other. The example below defines a web
application stack hosted on the web_server
“compute” resource, and a database software stack similar to the one shown
earlier in section 6 hosted on the db_server
compute resource.
Example 6 - Basic two-tier application (web
application and database server tiers)
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template for deploying a two-tier application servers on 2 servers.
topology_template:
inputs:
#
Admin user name and password to use with the WordPress application
wp_admin_username:
type: string
wp_admin_password:
type:
string
mysql_root_password:
type: string
context_root:
type: string
#
rest omitted here for brevity
node_templates:
db_server:
type: tosca.nodes.Compute
#
rest omitted here for brevity
mysql:
type: tosca.nodes.DBMS.MySQL
#
rest omitted here for brevity
wordpress_db:
type: tosca.nodes.Database.MySQL
#
rest omitted here for brevity
web_server:
type: tosca.nodes.Compute
# rest omitted here for brevity
apache:
type: tosca.nodes.WebServer.Apache
requirements:
- host: web_server
# rest omitted here for brevity
wordpress:
type: tosca.nodes.WebApplication.WordPress
properties:
context_root: { get_input: context_root }
admin_user: { get_input: wp_admin_username }
admin_password: { get_input: wp_admin_password }
db_host: { get_attribute: [
db_server, private_address ] }
requirements:
- host: apache
- database_endpoint: wordpress_db
interfaces:
Standard:
inputs:
db_host: { get_attribute: [ db_server, private_address ] }
db_port: { get_property: [ mysql, port ] }
db_name: { get_property: [ wordpress_db, name ] }
db_user: { get_property: [ wordpress_db, user ] }
db_password: { get_property: [ wordpress_db, password ] }
outputs:
#
omitted here for brevity
|
The web application stack
consists of the wordpress [WordPress],
the apache [Apache] and the web_server
node templates. The wordpress node template represents a custom web
application of type tosca.nodes.WebApplication.WordPress which is hosted
on an Apache web server represented by the apache node template. This
hosting relationship is expressed via the host entry in the requirements
section of the wordpress node template. The apache node template,
finally, is hosted on the web_server compute node.
The database stack consists of the wordpress_db, the mysql
and the db_server node templates. The wordpress_db node
represents a custom database of type tosca.nodes.Database.MySQL which is
hosted on a MySQL DBMS represented by the mysql node template. This
node, in turn, is hosted on the db_server compute node.
The wordpress node requires a connection to
the wordpress_db node, since the WordPress application needs a database
to store its data in. This relationship is established through the database_endpoint entry in the requirements
section of the wordpress node template’s declared node type. For
configuring the WordPress web application, information about the database to
connect to is required as input to the configure operation. Therefore,
the input parameters are defined and values for them are retrieved from the
properties and attributes of the wordpress_db node via the get_property
and get_attribute functions. In the
above example, these inputs are defined at the interface-level and would be
available to all operations of the Standard
interface (i.e., the tosca.interfaces.node.lifecycle.Standard
interface) within the wordpress node
template and not just the configure
operation.
In previous examples, the
template author did not have to think about explicit relationship types to be
used to link a requirement of a node to another node of a model, nor did the
template author have to think about special logic to establish those links. For
example, the host requirement
in previous examples just pointed to another node template and based on
metadata in the corresponding node type definition the relationship type to be
established is implicitly given.
In some cases, it might be
necessary to provide special processing logic to be executed when establishing
relationships between nodes at runtime. For example, when connecting the
WordPress application from previous examples to the MySQL database, it might be
desired to apply custom configuration logic in addition to that already
implemented in the application node type. In such a case, it is possible for
the template author to provide a custom script as implementation for an
operation to be executed at runtime as shown in the following example.
Example 7 - Providing a custom relationship script to
establish a connection
|
tosca_definitions_version:
tosca_simple_yaml_1_3
description: Template for deploying a two-tier
application on two servers.
topology_template:
inputs:
# omitted here for brevity
node_templates:
db_server:
type: tosca.nodes.Compute
# rest omitted here for brevity
mysql:
type: tosca.nodes.DBMS.MySQL
# rest omitted here for brevity
wordpress_db:
type: tosca.nodes.Database.MySQL
# rest omitted here for brevity
web_server:
type: tosca.nodes.Compute
# rest omitted here for brevity
apache:
type: tosca.nodes.WebServer.Apache
requirements:
- host: web_server
# rest omitted here for brevity
wordpress:
type: tosca.nodes.WebApplication.WordPress
properties:
# omitted here for brevity
requirements:
- host: apache
- database_endpoint:
node: wordpress_db
relationship: wp_db_connection
# rest omitted here for brevity
wordpress_db:
type: tosca.nodes.Database.MySQL
properties:
# omitted here for the brevity
requirements:
- host: mysql
relationship_templates:
wp_db_connection:
type: ConnectsTo
interfaces:
Configure:
pre_configure_source: scripts/wp_db_configure.sh
outputs:
# omitted here for brevity
|
The node type definition for the wordpress node template is WordPress which declares the complete database_endpoint
requirement definition. This database_endpoint
declaration indicates it must be fulfilled by any node template that provides
an Endpoint.Database Capability Type
using a ConnectsTo relationship. The wordpress_db
node template’s underlying MySQL type
definition indeed provides the Endpoint.Database
Capability type. In this example however, no explicit relationship
template is declared; therefore, TOSCA orchestrators would automatically create
a ConnectsTo relationship to establish the link between the wordpress node and the wordpress_db node at runtime.
The ConnectsTo
relationship (see 5.7.4) also provides a default Configure interface with operations that
optionally get executed when the orchestrator establishes the relationship. In
the above example, the author has provided the custom script wp_db_configure.sh to be executed for the
operation called pre_configure_source. The script file is
assumed to be located relative to the referencing service template such as a
relative directory within the TOSCA Cloud Service Archive (CSAR) packaging
format. This approach allows for conveniently hooking in custom behavior
without having to define a completely new derived relationship type.
In the previous section it was
shown how custom behavior can be injected by specifying scripts inline in the
requirements section of node templates. When the same custom behavior is
required in many templates, it does make sense to define a new relationship
type that encapsulates the custom behavior in a re-usable way instead of
repeating the same reference to a script (or even references to multiple
scripts) in many places.
Such a custom relationship type
can then be used in templates as shown in the following example.
Example 8 - A web application Node Template requiring
a custom database connection type
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template for deploying a two-tier application on two servers.
topology_template:
inputs:
#
omitted here for brevity
node_templates:
wordpress:
type: tosca.nodes.WebApplication.WordPress
properties:
# omitted here for brevity
requirements:
- host: apache
- database_endpoint:
node: wordpress_db
relationship: my.types.WordpressDbConnection
wordpress_db:
type: tosca.nodes.Database.MySQL
properties:
# omitted here for the brevity
requirements:
- host: mysql
#
other resources not shown here ...
|
In the example above, a special relationship type my.types.WordpressDbConnection is
specified for establishing the link between the wordpress node and the wordpress_db
node through the use of the relationship
keyword in the database
reference. It is assumed, that this special relationship type provides some
extra behavior (e.g., an operation with a script) in addition to what a generic
“connects to” relationship would provide. The definition of this custom
relationship type is shown in the following section.
The following YAML snippet shows the definition of
the custom relationship type used in the previous section. This type derives
from the base “ConnectsTo” and overrides one operation defined by that base
relationship type. For the pre_configure_source
operation defined in the Configure
interface of the ConnectsTo relationship type, a script implementation is
provided. It is again assumed that the custom configure script is located at a
location relative to the referencing service template, perhaps provided in some
application packaging format (e.g., the TOSCA Cloud Service Archive (CSAR)
format).
Example 9 - Defining a custom relationship type
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Definition of custom WordpressDbConnection relationship type
relationship_types:
my.types.WordpressDbConnection:
derived_from: tosca.relationships.ConnectsTo
interfaces:
Configure:
pre_configure_source: scripts/wp_db_configure.sh
|
In some cases, it can be
necessary to define a generic dependency between two nodes in a template to
influence orchestration behavior, i.e. to first have one node processed before
another dependent node gets processed. This can be done by using the generic dependency requirement which is defined by
the TOSCA Root Node Type and thus gets
inherited by all other node types in TOSCA (see section 5.9.1).
Example 10 - Simple dependency relationship between
two nodes
|
tosca_definitions_version:
tosca_simple_yaml_1_3
description:
Template with a generic dependency between two nodes.
topology_template:
inputs:
#
omitted here for brevity
node_templates:
my_app:
type: my.types.MyApplication
properties:
#
omitted here for brevity
requirements:
- dependency: some_service
some_service:
type: some.nodetype.SomeService
properties:
# omitted here for brevity
|
As in previous examples, the relation that one node
depends on another node is expressed in the requirements
section using the built-in requirement named dependency
that exists for all node types in TOSCA. Even if the creator of the MyApplication node type did not define a
specific requirement for SomeService (similar
to the database requirement in the
example in section 2.6), the template author who knows that there is a timing
dependency and can use the generic dependency
requirement to express that constraint using the very same syntax as used for
all other references.
In TOSCA templates, nodes are either:
·
Concrete: meaning that they have a deployment and/or one
or more implementation artifacts that are declared on the “create” operation of
the node’s Standard lifecycle interface, or they are
·
Abstract: where the template describes only the node type
along with its required capabilities and properties that must be satisfied.
TOSCA Orchestrators, by default, when finding an abstract
node in TOSCA Service Template during deployment will attempt to “select” a
concrete implementation for the abstract node type that best matches and
fulfills the requirements and property constraints the template author provided
for that abstract node. The concrete implementation of the node could be
provided by another TOSCA Service Template (perhaps located in a catalog or
repository known to the TOSCA Orchestrator) or by an existing resource or
service available within the target Cloud Provider’s platform that the TOSCA
Orchestrator already has knowledge of.
TOSCA supports two methods for template authors to express
requirements for an abstract node within a TOSCA service template.
1. Using
a target node_filter: where a node template can describe a requirement
(relationship) for another node without including it in the topology. Instead,
the node provides a node_filter to describe the
target node type along with its capabilities and property constrains
2. Using
an abstract node template: that describes the abstract node’s type
along with its property constraints and any requirements and capabilities it
also exports. This first method you have already seen in examples from
previous chapters where the Compute node is abstract and selectable by the
TOSCA Orchestrator using the supplied Container and OperatingSystem capabilities property
constraints.
These approaches allow architects and developers to create
TOSCA service templates that are composable and can be reused by allowing
flexible matching of one template’s requirements to another’s capabilities.
Examples of both these approaches are shown below.
The following section describe how a user can define a
requirement for an orchestrator to select an implementation and replace a node.
For more details on how an orchestrator may perform matching and select a node
from it’s catalog(s) you may look at section 14 of the specification.
Using TOSCA, it is possible to
define only the software components of an application in a template and just
express constrained requirements against the hosting infrastructure. At
deployment time, the provider can then do a late binding and dynamically
allocate or assign the required hosting infrastructure and place software
components on top.
This example shows how a single software component (i.e.,
the mysql node template) can define its host
requirements that the TOSCA Orchestrator and provider will use to select or
allocate an appropriate host Compute
node by using matching criteria provided on a node_filter.
Example
11 - An abstract "host" requirement using a node filter
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template with requirements against hosting infrastructure.
topology_template:
inputs:
#
omitted here for brevity
node_templates:
mysql:
type: tosca.nodes.DBMS.MySQL
properties:
# omitted here for brevity
requirements:
- host:
node_filter:
capabilities:
# Constraints for selecting “host” (Container Capability)
-
host:
properties:
- num_cpus: { in_range: [ 1, 4 ] }
- mem_size: { greater_or_equal: 2 GB }
# Constraints for selecting “os” (OperatingSystem Capability)
-
os:
properties:
- architecture: { equal: x86_64 }
- type: linux
- distribution: ubuntu
|
In the example above, the mysql component contains a host requirement for a node of type Compute which it inherits from its
parent DBMS node type definition; however, there is no declaration or reference
to any node template of type Compute.
Instead, the mysql node template
augments the abstract “host”
requirement with a node_filter which
contains additional selection criteria (in the form of property constraints
that the provider must use when selecting or allocating a host Compute node.
Some of the constraints shown above narrow down the
boundaries of allowed values for certain properties such as mem_size or num_cpus
for the “host” capability by means of
qualifier functions such as greater_or_equal.
Other constraints, express specific values such as for the architecture or distribution properties of the “os” capability which will require the
provider to find a precise match.
Note that when no qualifier
function is provided for a property (filter), such as for the distribution property, it is interpreted to
mean the equal operator as shown on the
architecture property.
2.9.2
Using an abstract node template to define infrastructure requirements for software
This previous approach works well if no other
component (i.e., another node template) other than mysql node template wants to reference the
same Compute node the orchestrator
would instantiate. However, perhaps another component wants to also be deployed
on the same host, yet still allow the flexible matching achieved using a
node-filter. The alternative to the above approach is to create an abstract
node template that represents the Compute
node in the topology as follows:
Example
12 - An abstract Compute node template with a node filter
|
tosca_definitions_version:
tosca_simple_yaml_1_3
description: Template with requirements against hosting
infrastructure.
topology_template:
inputs:
# omitted here for brevity
node_templates:
mysql:
type: tosca.nodes.DBMS.MySQL
properties:
# omitted here for brevity
requirements:
- host: mysql_compute
# Abstract node template (placeholder) to be selected by
provider
mysql_compute:
type: Compute
directives: [ select ]
node_filter:
capabilities:
- host:
properties:
num_cpus: { equal: 2 }
mem_size: { greater_or_equal: 2 GB }
- os:
properties:
architecture: { equal: x86_64 }
type: linux
distribution: ubuntu
|
In this node template, the msql_compute
node template is marked as abstract using the select
directive. As you can see the resulting mysql_compute
node template looks very much like the “hello world” template as shown in Chapter 2.1 but this one also allows the TOSCA
orchestrator more flexibility when “selecting” a host Compute node by providing flexible constraints
for properties like mem_size.
As we proceed, you will see that TOSCA provides many
normative node types like Compute for
commonly found services (e.g., BlockStorage,
WebServer, Network, etc.). When these TOSCA normative
node types are used in your application’s topology they are always assumed to
be “implementable” by TOSCA Orchestrators which work with target infrastructure
providers to find or allocate the best match for them based upon your
application’s requirements and constraints.
In the same way requirements
can be defined on the hosting infrastructure (as shown above) for an
application, it is possible to express requirements against application or
middleware components such as a database that is not defined in the same
template. The provider may then allocate a database by any means, (e.g. using a
database-as-a-service solution).
Example
13 - An abstract database requirement using a node filter
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template with a TOSCA Orchestrator selectable database requirement using a
node_filter.
topology_template:
inputs:
#
omitted here for brevity
node_templates:
my_app:
type: my.types.MyApplication
properties:
admin_user: { get_input: admin_username }
admin_password: { get_input: admin_password }
db_endpoint_url: { get_property: [SELF, database_endpoint,
url_path ] }
requirements:
- database_endpoint:
node: my.types.nodes.MyDatabase
node_filter:
properties:
- db_version: { greater_or_equal: 5.5 }
|
In the example above, the application my_app requires a database node of type MyDatabase which has a db_version property value of greater_or_equal to the value 5.5.
This example also shows how the get_property intrinsic function can be used
to retrieve the url_path property from
the database node that will be selected by the provider and connected to my_app at runtime due to fulfillment of the database_endpoint requirement. To locate the
property, the get_property’s first argument is set to the keyword SELF which indicates the property is being
referenced from something in the node itself. The second parameter is the name
of the requirement named database_endpoint
which contains the property we are looking for. The last argument is
the name of the property itself (i.e., url_path)
which contains the value we want to retrieve and assign to db_endpoint_url.
The alternative representation,
which includes a node template in the topology for database that is still
selectable by the TOSCA orchestrator for the above example, is as follows:
Example
14 - An abstract database node template
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template with a TOSCA Orchestrator selectable database using node template.
topology_template:
inputs:
#
omitted here for brevity
node_templates:
my_app:
type: my.types.MyApplication
properties:
admin_user: { get_input: admin_username }
admin_password: { get_input: admin_password }
db_endpoint_url: { get_property: [SELF, database_endpoint, url_path ] }
requirements:
- database_endpoint: my_abstract_database
my_abstract_database:
type: my.types.nodes.MyDatabase
properties:
- db_version: { greater_or_equal: 5.5 }
|
From an application perspective, it is often not necessary
or desired to dive into platform details, but the platform/runtime for an
application is abstracted. In such cases, the template for an application can
use generic representations of platform components. The details for such
platform components, such as the underlying hosting infrastructure and its
configuration, can then be defined in separate template files that can be used
for substituting the more abstract representations in the application level
template file. Service designers use the substitute
directive to declare node templates as abstract. At deployment time, TOSCA
orchestrators are expected to substitute
abstract node templates in a service template before service orchestration can
be performed.
When a topology template is instantiated by a TOSCA
Orchestrator, the orchestrator has to first look for abstract node templates in
the topology template. Abstract node templates are node templates that include
the substitute directive. These
abstract node templates must then be realized using substituting service templates that
are compatible with the node types specified for each abstract node template.
Such realizations can either be node types that include the appropriate
implementation artifacts and deployment artifacts that can be used by the
orchestrator to bring to life the real-world resource modeled by a node template.
Alternatively, separate topology templates may be annotated as being suitable
for realizing a node template in the top-level topology template.
In the latter case, a TOSCA Orchestrator will use additional
substitution mapping information provided as part of the substituting topology
templates to derive how the substituted part gets “wired” into the overall
deployment, for example, how capabilities of a node template in the top-level
topology template get bound to capabilities of node templates in the substituting
topology template.
Thus, in cases where no “normal” node type implementation is
available, or the node type corresponds to a whole subsystem that cannot be
implemented as a single node, additional topology templates can be used for
filling in more abstract placeholders in top level application templates.
The following sample defines a
web application web_app connected to a
database db. In this example, the
complete hosting stack for the application is defined within the same topology
template: the web application is hosted on a web server web_server, which in turn is installed
(hosted) on a compute node server.
The hosting stack for the
database db, in contrast, is not
defined within the same file but only the database is represented as a node
template of type tosca.nodes.Database.
The underlying hosting stack for the database is defined in a separate template
file, which is shown later in this section. Within the current template, only a
number of properties (user, password, name)
are assigned to the database using hardcoded values in this simple example.
Figure 1:
Using template substitution to implement a database tier
When a node template is to be substituted by another service
template, this has to be indicated to an orchestrator by marking he node
template as abstract using the substitute
directive. Orchestrators can only instantiate abstract node templates by
substituting them with a service template that consists entirely of concrete
nodes. Note that abstract node template substitution may need to happen
recursively before a service template is obtained that consists only of
concrete nodes.
Note that in contrast to the use case described in section 2.9.2 (where a database was abstractly referred to in the requirements section of a node and the
database itself was not represented as a node template), the approach shown
here allows for some additional modeling capabilities in cases where this is
required.
For example, if multiple components need to use the same database (or any other
sub-system of the overall service), this can be expressed by means of normal
relations between node templates, whereas such modeling would not be possible
in requirements sections of disjoint
node templates.
Example
15 - Referencing an abstract database node template
|
tosca_definitions_version:
tosca_simple_yaml_1_3
topology_template:
description: Template of an application connecting to a
database.
node_templates:
web_app:
type: tosca.nodes.WebApplication.MyWebApp
requirements:
- host: web_server
- database_endpoint: db
web_server:
type: tosca.nodes.WebServer
requirements:
- host: server
server:
type: tosca.nodes.Compute
# details omitted for brevity
db:
# This node is abstract as specified by the
substitute directive
# and must be substituted with a topology provided
by another template
# that exports a Database type’s capabilities.
type: tosca.nodes.Database
directives:
- substitute
properties:
user: my_db_user
password: secret
name: my_db_name
|
The following sample defines a template for a
database including its complete hosting stack, i.e. the template includes a database node template, a template for the
database management system (dbms)
hosting the database, as well as a computer node server on which the DBMS is installed.
This service template can be used standalone for deploying
just a database and its hosting stack. In the context of the current use case,
though, this template can also substitute the database node template in the
previous snippet and thus fill in the details of how to deploy the database.
In order to enable such a substitution, an additional metadata
section substitution_mappings is added
to the topology template to tell a TOSCA Orchestrator how exactly the topology
template will fit into the context where it gets used. For example,
requirements or capabilities of the node that gets substituted by the topology
template have to be mapped to requirements or capabilities of internal node
templates for allow for a proper wiring of the resulting overall graph of node
templates.
In short, the substitution_mappings
section provides the following information:
1. It defines
what node templates, i.e. node templates of which type, can be substituted by
the topology template.
2. It defines
how capabilities of the substituted node (or the capabilities defined by the
node type of the substituted node template, respectively) are bound to
capabilities of node templates defined in the topology template.
3. It defines
how requirements of the substituted node (or the requirements defined by the
node type of the substituted node template, respectively) are bound to
requirements of node templates defined in the topology template.
Figure 2: Substitution mappings
The substitution_mappings
section in the sample below denotes that this topology template can be used for
substituting node templates of type tosca.nodes.Database.
It further denotes that the database_endpoint
capability of the substituted node gets fulfilled by the database_endpoint capability of the database node contained in the topology
template.
Example
16 - Using substitution mappings to export a database implementation
|
tosca_definitions_version:
tosca_simple_yaml_1_3
topology_template:
description: Template of a database including its
hosting stack.
inputs:
db_user:
type: string
db_password:
type: string
# other inputs omitted for brevity
substitution_mappings:
node_type: tosca.nodes.Database
capabilities:
database_endpoint: [ database, database_endpoint ]
node_templates:
database:
type: tosca.nodes.Database
properties:
user: { get_input: db_user }
# other properties omitted for brevity
requirements:
- host: dbms
dbms:
type: tosca.nodes.DBMS
# details omitted for brevity
server:
type: tosca.nodes.Compute
# details omitted for brevity
|
Note that the substitution_mappings
section does not define any mappings for requirements of the Database node
type, since all requirements are fulfilled by other nodes templates in the
current topology template. In cases where a requirement of a substituted node
is bound in the top-level service template as well as in the substituting topology
template, a TOSCA Orchestrator should raise a validation error.
Further note that no mappings for properties or attributes
of the substituted node are defined. Instead, the inputs and outputs defined by
the topology template are mapped to the appropriate properties and attributes
or the substituted node. If there are more inputs than the substituted node has
properties, default values must be defined for those inputs, since no values
can be assigned through properties in a substitution case.
A common use case when providing an end-to-end service is to
define a chain of several subsystems that together implement the overall
service. Those subsystems are typically defined as separate service templates
to (1) keep the complexity of the end-to-end service template at a manageable
level and to (2) allow for the re-use of the respective subsystem templates in
many different contexts. The type of subsystems may be specific to the targeted
workload, application domain, or custom use case. For example, a company or a
certain industry might define a subsystem type for company- or industry
specific data processing and then use that subsystem type for various end-user
services. In addition, there might be generic subsystem types like a database
subsystem that are applicable to a wide range of use cases.
Figure 3 shows the chaining of three subsystem types
– a message queuing subsystem, a transaction processing subsystem, and a
databank subsystem – that support, for example, an online booking application.
On the front end, this chain provides a capability of receiving messages for
handling in the message queuing subsystem. The message queuing subsystem in
turn requires a number of receivers, which in the current example are two
transaction processing subsystems. The two instances of the transaction
processing subsystem might be deployed on two different hosting infrastructures
or datacenters for high-availability reasons. The transaction processing
subsystems finally require a database subsystem for accessing and storing
application specific data. The database subsystem in the backend does not
require any further component and is therefore the end of the chain in this
example.
Figure 3:
Chaining of subsystems in a service template
All of the node templates in the service template shown above
are abstract and considered substitutable where each can be treated as their
own subsystem; therefore, when instantiating the overall service, the
orchestrator would realize each substitutable node template using other TOSCA
service templates. These service templates would include more nodes and
relationships that include the details for each subsystem. A simplified version
of a TOSCA service template for the overall service is given in the following
listing.
Example
17 - Declaring a transaction subsystem as a chain of substitutable node
templates
|
tosca_definitions_version: tosca_simple_yaml_1_3
topology_template:
description: Template of online transaction processing
service.
node_templates:
mq:
type: example.QueuingSubsystem
directives:
- substitute
properties:
# properties omitted for brevity
capabilities:
message_queue_endpoint:
# details omitted for brevity
requirements:
- receiver: trans1
- receiver: trans2
trans1:
type: example.TransactionSubsystem
directives:
- substitute
properties:
mq_service_ip: { get_attribute: [ mq, service_ip
] }
receiver_port: 8080
capabilities:
message_receiver:
# details omitted for brevity
requirements:
- database_endpoint: dbsys
trans2:
type: example.TransactionSubsystem
directives:
- substitute
properties:
mq_service_ip: { get_attribute: [ mq, service_ip
] }
receiver_port: 8080
capabilities:
message_receiver:
# details omitted for brevity
requirements:
- database_endpoint: dbsys
dbsys:
type: example.DatabaseSubsystem
directives:
- substitute
properties:
# properties omitted for brevity
capabilities:
database_endpoint:
# details omitted for brevity
|
As can be seen in the example above, the subsystems are
chained to each other by binding requirements of one subsystem node template to
other subsystem node templates that provide the respective capabilities. For
example, the receiver requirement of
the message queuing subsystem node template mq
is bound to transaction processing subsystem node templates trans1 and trans2.
Subsystems can be parameterized by providing properties.
In the listing above, for example, the IP address of the message queuing server
is provided as property mq_service_ip
to the transaction processing subsystems and the desired port for receiving
messages is specified by means of the receiver_port
property.
If attributes of the instantiated subsystems need to
be obtained, this would be possible by using the get_attribute intrinsic function on the
respective subsystem node templates.
The types of subsystems that are required for a
certain end-to-end service are defined as TOSCA node types as shown in the following
example. Node templates of those node types can then be used in the end-to-end
service template to define subsystems to be instantiated and chained for
establishing the end-to-end service.
The realization of the defined node type will be
given in the form of a whole separate service template as outlined in the
following section.
Example
18 - Defining a TransactionSubsystem node type
|
tosca_definitions_version: tosca_simple_yaml_1_3
node_types:
example.TransactionSubsystem:
properties:
mq_service_ip:
type: string
receiver_port:
type: integer
attributes:
receiver_ip:
type: string
type: integer
message_receiver: tosca.capabilities.Endpoint
requirements:
- database_endpoint:
tosca.capabilities.Endpoint.Database
|
Configuration parameters that would be allowed for
customizing the instantiation of any subsystem are defined as properties of the
node type. In the current example, those are the properties mq_service_ip and receiver_port that had been used in the
end-to-end service template in section 2.11.1.
Observable attributes of the
resulting subsystem instances are defined as attributes of the node type. In
the current case, those are the IP address of the message receiver as well as
the actually allocated port of the message receiver endpoint.
The details of a subsystem, i.e. the software components and
their hosting infrastructure, are defined as node templates and relationships
in a service template. By means of substitution mappings that have been
introduced in section 2.10.2, the service template is annotated to indicate to
an orchestrator that it can be used as realization of a node template of a certain
type, as well as how characteristics of the node type are mapped to internal
elements of the service template.
Figure 4: Defining subsystem details in a service
template
Figure 1 illustrates how a transaction processing subsystem
as outlined in the previous section could be defined in a service template. In
this example, it simply consists of a custom application app of type SomeApp
that is hosted on a web server websrv,
which in turn is running on a compute node.
The application named app provides a capability to receive
messages, which is bound to the message_receiver
capability of the substitutable node type. It further requires access to a
database, so the application’s database_endpoint
requirement is mapped to the database_endpoint
requirement of the TransactionSubsystem
node type.
Properties of the TransactionSubsystem node type are used to customize
the instantiation of a subsystem. Those properties can be mapped to any node
template for which the author of the subsystem service template wants to expose
configurability. In the current example, the application app and the web server
middleware websrv get configured
through properties of the TransactionSubsystem
node type. All properties of that node type are defined as inputs of the service template. The input
parameters in turn get mapped to node templates by means of get_input function calls in the respective
sections of the service template.
Similarly, attributes of the whole subsystem can be
obtained from attributes of particular node templates. In the current example,
attributes of the web server and the hosting compute node will be exposed as
subsystem attributes. All exposed attributes that are defined as attributes of
the substitutable TransactionSubsystem
node type are defined as outputs of the subsystem service template.
An outline of the subsystem service
template is shown in the listing below. Note that this service template could
be used for stand-alone deployment of a transaction processing system as well,
i.e. it is not restricted just for use in substitution scenarios. Only the
presence of the substitution_mappings
metadata section in the topology_template
enables the service template for substitution use cases.
Example
19 - Implementation of a TransactionSubsytem node type using substitution
mappings
|
tosca_definitions_version:
tosca_simple_yaml_1_3
topology_template:
description: Template of a database including its
hosting stack.
inputs:
mq_service_ip:
type: string
description: IP address of the message queuing
server to receive messages from
receiver_port:
type: string
description: Port to be used for receiving messages
# other inputs omitted for brevity
substitution_mappings:
node_type: example.TransactionSubsystem
capabilities:
message_receiver: [ app, message_receiver ]
requirements:
database_endpoint: [ app, database ]
node_templates:
app:
type: example.SomeApp
properties:
# properties omitted for brevity
capabilities:
message_receiver:
properties:
service_ip: { get_input: mq_service_ip }
# other properties omitted for brevity
requirements:
- database:
# details omitted for brevity
- host: websrv
websrv:
type: tosca.nodes.WebServer
properties:
# properties omitted for brevity
capabilities:
data_endpoint:
properties:
port_name: { get_input: receiver_port }
# other properties omitted for brevity
requirements:
- host: server
server:
type: tosca.nodes.Compute
# details omitted for brevity
outputs:
receiver_ip:
description: private IP address of
the message receiver application
value: { get_attribute: [ server,
private_address ] }
receiver_port:
description: Port of the message
receiver endpoint
value: { get_attribute: [ app,
app_endpoint, port ] }
|
2.12 Using node template substitution to provide
product choice
Some service templates might include abstract node templates
that model specific functionality without fully specifying the exact product or
technology that provides that functionality. The objective of such service
templates is to allow the end-user of the service to decide at service deployment time
which specific product component to use.
2.12.1 Defining a service template with vendor-independent component
For example, let’s assume an abstract security service that
includes a firewall component where the choice of firewall product is left to
the end-user at service deployment time. The following template shows an
example of such a service: it includes an abstract firewall node template that
has a vendor
property that represents the firewall vendor. The value of this property is
obtained from a topology input variable that allows end-users to specify the
desired firewall vendor at deployment time.
Defining a security service with a vendor-independent
firewall component
tosca_definitions_version:
tosca_simple_yaml_1_3
description: Service template for an abstract security
service
topology_template:
inputs:
vendorInput:
type: string
rulesInput:
type: list
entry_schema: FirewallRules
node_templates:
firewall:
type: abstract.Firewall
directives:
- substitute
properties:
vendor: { get_input: vendorInput }
rules: { get_input: rulesInput }
|
The abstract firewall node type is defined in the
following code snippet. The abstract firewall node type defines a rules property to hold the configured firewall rules. In
addition, it also defines a property for capturing the name of the vendor of
the firewall.
Node type defining an abstract firewall component
tosca_definitions_version: tosca_simple_yaml_1_3
description: Template defining an abstract firewall
component
node_types:
abstract.Firewall:
derived_from: tosca.nodes.Root
properties:
vendor:
type: string
rules:
type: list
entry_schema: FirewallRules
|
2.12.2 Defining vendor-specific component options
In the above example, the firewall node template is abstract,
which means that it needs to be substituted with a substituting firewall
template. Let’s assume we have two firewall vendors—ACME Firewalls and Simple
Firewalls—who each provide implementations for the abstract firewall component.
Their respective implementations are defined in vendor-specific service
templates. ACME Firewall’s service template might look as follows:
Service template for an ACME firewall
tosca_definitions_version:
tosca_simple_yaml_1_3
description: Service template for an ACME firewall
topology_template:
inputs:
rulesInput:
type: list
entry_schema: FirewallRules
substitution_mappings:
node_type: abstract.Firewall
properties:
rules: [ rulesInput ]
node_templates:
acme:
type: ACMEFirewall
properties:
rules: { get_input: rulesInput }
acmeConfig: # any ACME-specific properties go
here.
|
In this example the node type ACMEFirewall is an
ACME-specific node type that models the internals of the ACME firewall product.
The ACMEFirewall node type definition is omitted here for brevity since it is
not relevant for the example.
Similarly, Simple Firewall’s service template looks
as follows:
Service template for a Simple Firewall
tosca_definitions_version: tosca_simple_yaml_1_3
description: Service template for a Simple Corp. firewall
topology_template:
inputs:
rulesInput:
type: list
entry_schema: FirewallRules
substitution_mappings:
node_type: abstract.Firewall
properties:
rules: [ rulesInput ]
node_templates:
acme:
type: SimpleFirewall
properties:
rules: { get_input: rulesInput }
|
As the substitution mappings section in the service templates
show, either firewall service template can be used to implement the abstract
firewall component defined above.
2.12.3 Substitution matching using substitution filters
Since both the ACME Firewall and the Simple Firewall can
substitute for abstract node templates of type abstract.Firewall,
either firewall is a valid candidate to substitute the abstract firewall node
template. When multiple matching templates are available, the orchestrator must
provide mechanisms to allow the end-user to drive the decision about which
matching template must be selected.
TOSCA uses a substitution_filter
in the substitution mappings section of a service template to further constrain
the abstract nodes for which a service template can be a valid substitution.
Using substitution filters, a service template is a valid candidate to
substitute an abstract node template if the following two conditions are met:
1. The type advertised in the substitution_mappings
section of the service template matches the type of the abstract node template.
2. The
property values of the abstract node template satisfy the constraints defined
in the substitution_filtter of the
substituting service template.
In the security service example used in this
section, the value of the vendor property
of the abstract firewall node template is provide by the end-user using a
topology input parameter. Substituting templates use a substitution_filter to
match the appropriate vendor-specific service templates with the abstract
firewall node template based on the value of the vendor
property.
The following code snippet shows an updated version of the
ACME Firewall service template. This version includes a substitution_filter
that specifies that this service template only matches abstract firewall nodes
with a vendor property equal to ‘ACME’.
Service template for an ACME firewall with a substitution
filter
tosca_definitions_version: tosca_simple_yaml_1_3
description: Service template for an ACME firewall
topology_template:
inputs:
rulesInput:
type: list
entry_schema: FirewallRules
substitution_mappings:
node_type: abstract.Firewall
substitution_filter:
properties:
-
vendor: { equal: ACME }
properties:
rules: [ rulesInput ]
node_templates:
acme:
type: ACMEFirewall
properties:
rules: { get_input: rulesInput }
acmeConfig: # any ACME-specific properties go
here.
|
Similarly, an updated service template for Simple
Corp’s firewall looks as follows:
Service template for a Simple firewall with a substitution
filter
tosca_definitions_version: tosca_simple_yaml_1_3
description: Service template for a Simple Corp. firewall
topology_template:
inputs:
rulesInput:
type: list
entry_schema: FirewallRules
substitution_mappings:
node_type: abstract.Firewall
substitution_filter:
properties:
-
vendor: { equal: Simple }
properties:
rules: [ rulesInput ]
node_templates:
acme:
type: SimpleFirewall
properties:
rules: { get_input: rulesInput }
|
As specified in this example, only abstract firewall node
templates that have the vendor property set to
‘Simple’ can be substituted by this service template.
In designing applications composed of several interdependent
software components (or nodes) it is often desirable to manage these components
as a named group. This can provide an effective way of associating policies
(e.g., scaling, placement, security or other) that orchestration tools can
apply to all the components of group during deployment or during other
lifecycle stages.
In many realistic scenarios it is desirable to
include scaling capabilities into an application to be able to react on load
variations at runtime. The example below shows the definition of a scaling web
server stack, where a variable number of servers with apache installed on them
can exist, depending on the load on the servers.
Example
20 - Grouping Node Templates for possible policy application
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template for a scaling web server.
topology_template:
inputs:
#
omitted here for brevity
node_templates:
apache:
type:
tosca.nodes.WebServer.Apache
properties:
# Details omitted for brevity
requirements:
- host: server
server:
type: tosca.nodes.Compute
# details omitted for brevity
groups:
webserver_group:
type: tosca.groups.Root
members: [ apache, server ]
|
The example first of all uses the concept of
grouping to express which components (node templates) need to be scaled as a
unit – i.e. the compute nodes and the software on-top of each compute node.
This is done by defining the webserver_group
in the groups section of the template
and by adding both the apache node
template and the server node
template as a member to the group.
Furthermore, a scaling policy
is defined for the group to express that the group as a whole (i.e. pairs of server node and the apache component installed on top)
should scale up or down under certain conditions.
In cases where no explicit
binding between software components and their hosting compute resources is
defined in a template, but only requirements are defined as has been shown in
section 2.9, a provider could decide to place software components on the same
host if their hosting requirements match, or to place them onto different
hosts.
It is often desired, though, to
influence placement at deployment time to make sure components get collocation
or anti-collocated. This can be expressed via grouping and policies as shown in
the example below.
Example
21 - Grouping nodes for anti-colocation policy application
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template hosting requirements and placement policy.
topology_template:
inputs:
#
omitted here for brevity
node_templates:
wordpress_server:
type: tosca.nodes.WebServer
properties:
# omitted here for brevity
requirements:
- host:
# Find a Compute node that fulfills these additional filter reqs.
node_filter:
capabilities:
- host:
properties:
- mem_size: { greater_or_equal: 512 MB }
- disk_size: { greater_or_equal: 2 GB }
- os:
properties:
- architecture: x86_64
- type: linux
mysql:
type: tosca.nodes.DBMS.MySQL
properties:
# omitted here for brevity
requirements:
- host:
node: tosca.nodes.Compute
node_filter:
capabilities:
- host:
properties:
-
disk_size: { greater_or_equal: 1 GB }
- os:
properties:
- architecture: x86_64
- type: linux
groups:
my_co_location_group:
type: tosca.groups.Root
members: [ wordpress_server, mysql ]
policies:
-
my_anti_collocation_policy:
type: my.policies.anticolocateion
targets: [ my_co_location_group ]
# For this example, specific policy definitions are considered
#
domain specific and are not included here
|
In the example above, both software components wordpress_server and mysql have similar hosting
requirements. Therefore, a provider could decide to put both on the same server
as long as both their respective requirements can be fulfilled. By defining a
group of the two components and attaching an anti-collocation policy to the group
it can be made sure, though, that both components are put onto different hosts
at deployment time.
The YAML 1.2 specification allows for defining of aliases, which allow
for authoring a block of YAML (or node) once and indicating it is an “anchor”
and then referencing it elsewhere in the same document as an “alias”.
Effectively, YAML parsers treat this as a “macro” and copy the anchor block’s
code to wherever it is referenced. Use of this feature is especially helpful
when authoring TOSCA Service Templates where similar definitions and property
settings may be repeated multiple times when describing a multi-tier
application.
For example, an application that has a web server and
database (i.e., a two-tier application) may be described using two Compute nodes (one to host the web server and
another to host the database). The author may want both Compute nodes to be
instantiated with similar properties such as operating system, distribution,
version, etc.
To accomplish this, the author would describe the
reusable properties using a named anchor in the “dsl_definitions” section of the TOSCA Service
Template and reference the anchor name as an alias in any Compute node templates where these properties
may need to be reused. For example:
Example 22
- Using YAML anchors in TOSCA templates
|
tosca_definitions_version:
tosca_simple_yaml_1_3
description:
>
TOSCA
simple profile that just defines a YAML macro for commonly reused Compute
properties.
dsl_definitions:
my_compute_node_props:
&my_compute_node_props
disk_size: 10 GB
num_cpus: 1
mem_size: 2 GB
topology_template:
node_templates:
my_server:
type:
Compute
capabilities:
host:
properties: *my_compute_node_props
my_database:
type:
Compute
capabilities:
host:
properties: *my_compute_node_props
|
It is possible for type and template authors to declare
input variables within an inputs block
on interfaces to nodes or relationships in order to pass along information
needed by their operations (scripts). These declarations can be scoped such as
to make these variable values available to all operations on a node or
relationships interfaces or to individual operations. TOSCA orchestrators will
make these values available using the appropriate mechanisms depending on the
type of implementation artifact used for each operation. For example, when
using script artifacts, input values are passed as environment variables within
the execution environments in which the scripts associated with lifecycle
operations are run.
2.15.1 Example: declaring
input variables for all operations on a single interface
|
node_templates:
wordpress:
type: tosca.nodes.WebApplication.WordPress
requirements:
...
-
database_endpoint: mysql_database
interfaces:
Standard:
inputs:
wp_db_port: { get_property: [ SELF, database_endpoint, port ] }
|
|
node_templates:
wordpress:
type: tosca.nodes.WebApplication.WordPress
requirements:
...
-
database_endpoint: mysql_database
interfaces:
Standard:
create: wordpress_install.sh
configure:
implementation: wordpress_configure.sh
inputs:
wp_db_port: { get_property: [ SELF, database_endpoint, port ] }
|
In the case where an input variable name is defined
at more than one scope within the same interfaces section of a node or template
definition, the lowest (or innermost) scoped declaration would override those
declared at higher (or more outer) levels of the definition.
Service template designers have the ability to define
operation outputs that specify named output values that are expected to be
returned by interface operations as well as the attributes on nodes or
relationships into which these output values must be stored.
2.16.1 Example: setting output values to a node attribute
The service template below shows an example service template
that is used to create a compute node. The config operation of the Standard
lifecycle returns both the private and the public IP addresses of the config
node. The attribute mappings grammar is used to reflect these addresses
into the appropriate Compute node attributes:
|
tosca_definitions_version:
tosca_simple_yaml_1_3
description:
Template for creating compute node
topology_template:
node_templates:
node:
type: tosca.nodes.Compute
interfaces:
Standard:
configure:
outputs:
ip1: [ SELF, private_address ]
ip2: [ SELF, public_address ]
|
2.16.2 Example: setting output values to a capability attribute
Some operation outputs may need to be reflected into
attributes of capabilities of nodes, rather than in attributes of the nodes
themselves. The following example shows how an IP address returned by a config
operation is stored in the ip_address attribute of
the endpoint capability of a Compute
node:
tosca_definitions_version: tosca_simple_yaml_1_2_0
description: Template for creating compute node
topology_template:
node_templates:
compute:
type: tosca.nodes.Compute
interfaces:
Standard:
config:
outputs:
ip1: [
SELF, endpoint, ip_address ]
|
As shown in the previous section, TOSCA allows service
template designers to reflect the results of executing interface operations
into node or relationship artifacts using output mappings. However, there are
many situations where components modeled by a node can change independently as
a result of external events (e.g. load changes, failures, mode changes, etc.) rather
than as a result of executing lifecycle management operations. To support those
situations, TOSCA includes support for notifications that allow service
template designers to specify how to asynchronously receive external events and
how those events should result in node or relationship attribute changes.
Just like operations, notifications are specified as
part of interface definitions. The major difference between notifications and
operations is that the former are called from the outside world to on the
orchestrator, and not the other way around. As a result, notifications do not
have inputs defined (since they are called asynchronously from the outside). Information
carried in notifications is pushed to the orchestrator via notification outputs
(similar to operation outputs).
The following example shows how a health monitoring
interface is used to allow the orchestrator to monitor the health of a database
node by listening for heartbeats as well as by waiting for asynchronous failure
alerts:
|
tosca_definitions_version:
tosca_simple_yaml_1_3
description:
Template showing a health monitoring interface
topology_template:
node_templates:
db_1:
type: org.ego.nodes.Database
interfaces:
HealthMonitor:
notifications:
heartbeat:
outputs:
tick: [ SELF, still_alive ]
failure_report:
outputs:
level: [SELF, failure_level]
time: [SELF, failure_time]
environment: [SELF, failure_context]
|
A TOSCA service template contains a topology template,
which models the components of an application, their relationships and
dependencies (a.k.a., a topology model) that get interpreted and instantiated
by TOSCA Orchestrators. The actual node and relationship instances that are
created represent a set of resources distinct from the template itself, called
a topology instance (model). The direction of this specification is to
provide access to the instances of these resources for management and
operational control by external administrators. This model can also be
accessed by an orchestration engine during deployment – i.e. during the actual
process of instantiating the template in an incremental fashion, That is, the
orchestrator can choose the order of resources to instantiate (i.e.,
establishing a partial set of node and relationship instances) and have the
ability, as they are being created, to access them in order to facilitate
instantiating the remaining resources of the complete topology template.
Most entity types in TOSCA (e.g., Node, Relationship,
Capability Types, etc.) have property
definitions, which allow template authors to set the values for as inputs
when these entities are instantiated by an orchestrator. These property values
are considered to reflect the desired state of the entity by the author. Once
instantiated, the actual values for these properties on the realized
(instantiated) entity are obtainable via attributes on the entity with the same
name as the corresponding property.
In other words, TOSCA orchestrators will
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.
Use of this feature is shown in the example below where a
source node named my_client, of type ClientNode, requires a connection to another
node named my_server of type ServerNode. As you can see, the ServerNode type defines a property named notification_port which defines a dedicated
port number which instances of my_client
may use to post asynchronous notifications to it during runtime. In this case,
the TOSCA Simple Profile assures that the notification_port
property is implicitly reflected as an attribute in the my_server node (also with the name notification_port) when its node template is
instantiated.
Example 23
- Properties reflected as attributes
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
>
TOSCA
simple profile that shows how the (notification_port) property is reflected
as an attribute and can be referenced elsewhere.
node_types:
ServerNode:
derived_from: SoftwareComponent
properties:
notification_port:
type: integer
capabilities:
# omitted here for brevity
ClientNode:
derived_from: SoftwareComponent
properties:
#
omitted here for brevity
requirements:
- server:
capability: Endpoint
node: ServerNode
relationship: ConnectsTo
topology_template:
node_templates:
my_server:
type: ServerNode
properties:
notification_port: 8000
my_client:
type: ClientNode
requirements:
- server:
node: my_server
relationship: my_connection
relationship_templates:
my_connection:
type: ConnectsTo
interfaces:
Configure:
inputs:
targ_notify_port: { get_attribute: [ TARGET, notification_port ] }
# other operation definitions omitted here for
brevity
|
Specifically, the above example shows that the ClientNode type needs the notification_port value anytime a node of ServerType is connected to it using the ConnectsTo relationship in order to make it
available to its Configure operations
(scripts). It does this by using the get_attribute
function to retrieve the notification_port
attribute from the TARGET node of the ConnectsTo relationship (which is a node of
type ServerNode) and assigning it to an
environment variable named targ_notify_port.
It should be noted that the actual port value of the notification_port attribute may or may not be
the value 8000 as requested on the
property; therefore, any node that is dependent on knowing its actual “runtime”
value would use the get_attribute
function instead of the get_property
function.
TOSCA service templates specify a set of nodes that
need to be instantiated at service deployment time. Some service templates may
include multiple nodes that perform the same role. For example, a template that
models an SD-WAN service might contain multiple VPN Site nodes, one for each
location that accesses the SD-WAN. Rather than having to create a separate
service template for each possible number of VPN sites, it would be preferable
to have a single service template that allows the number of VPN sites to be
specified as an input to the template at deployment time. This section
introduces experimental TOSCA language extensions in support of
this functionality.It is expected that these extensions will be formally
standardized in a future version of this specifications.
The discussion in this section uses an example
SD-WAN deployment to three sites as shown in the following figure:
Example SD-WAN
Service Deployment
The following code snippet shows a TOSCA service template
from which this service could have been deployed:
Example
24 – TOSCA SD-WAN Service Template
|
tosca_definitions_version: tosca_simple_yaml_1_3
description:
Template for deploying SD-WAN with three sites.
topology_template:
inputs:
location1:
type: Location
location2:
type: Location
location3:
type: Location
node_templates:
sdwan:
type: VPN
site1:
type: VPNSite
properties:
location: { get_input: location1 }
requirements:
- vpn: sdwan
site2:
type: VPNSite
properties:
location: { get_input: location2 }
requirements:
- vpn: sdwan
site3:
type: VPNSite
properties:
location: { get_input: location3 }
requirements:
- vpn: sdwan
|
Unfortunately, this template can only be used to deploy an
SD-WAN with three sites. To deploy a different number of sites, additional
service templates would have t be created, one for each number of possible
SD-WAN sites. This leads to template proliferation, which is undesirable. The next
section explores alternatives.
2.20.1 Specifying Number of Occurrences
To avoid the need for multiple service templates, TOSCA must
provide a mechanism that allows all VPN Site nodes to be created from the same
Site node template in the topology, and allow the number of sites to be
specified at deployment time. Specifically, this functionality must:
- Allow
service template designers to specify that multiple node instances can be
created from a single node template
- Allow
service template designers to constrain how many node instances can be created
from a single node template
- Allow
users to specify at deployment time the exact number of instances that need to
be created from the single node template.
To provide this functionality, the TOSCA node template
definition grammar is extended with an occurrences
keyword that specifies the minimum and maximum number of instances that can be
created from this node template. If occurrences is not specified, only one
single instance can be created. In addition, an instance_count
keyword is used to specify the requested number of runtime instances of this
node template. It is expected that the value of the instance_count is provided
as an input to the topology template. These extensions enable the creation of a
simplified SD-WAN service template that contains only one single VPN Site node
as shown in the following code snippet:
Example
25 – TOSCA SD-WAN Service Template
|
tosca_definitions_version: tosca_simple_yaml_1_3
description: Template for deploying SD-WAN with a
variable number of sites.
topology_template:
inputs:
numberOfSites:
type: integer
node_templates:
sdwan:
type: VPN
site:
type: VPNSite
occurrences: [1, UNBOUNDED]
instance_count: { get_input: numberOfSites }
requirements:
- vpn: sdwan
|
2.20.2 Specifying Inputs
The service template in the previous section
conveniently ignores the location property of the Site node. As shown earlier,
the location property is expected to be provided as an input value. If Site
node templates can be instantiated multiple times, then it follows that
multiple input values are required to initialize the location property for each
of the Site node instances.
To allow specific input values to be matched with specific node template
instances, a new reserved keyword called INDEX is introduced. A TOSCA
orchestrator will interpret this keyword as the runtime index in the list of
node instances created from a single node template.
The
following service template shows how the INDEX keyword is used to retrieve
specific values from a list of input values in a service template:
Example
26 – TOSCA SD-WAN Service Template
|
tosca_definitions_version: tosca_simple_yaml_1_3
description: Template for deploying SD-WAN with a
variable number of sites.
topology_template:
inputs:
numberOfSites:
type: integer
locations:
type: list
entry_schema: Location
node_templates:
sdwan:
type: VPN
site:
type: VPNSite
occurrences: [1, UNBOUNDED]
instance_count: { get_input: numberOfSites }
properties:
location: { get_input: [ locations, INDEX ] }
requirements:
- vpn: sdwan
|
3
TOSCA Simple Profile definitions in YAML
Except for the examples, this section is normative
and describes all of the YAML grammar, definitions and block structure for all
keys and mappings that are defined for the TOSCA Version 1.3 Simple Profile
specification that are needed to describe a TOSCA Service Template (in YAML).
The following TOSCA Namespace URI alias and TOSCA
Namespace Alias are reserved values which SHALL be used when identifying the
TOSCA Simple Profile version 1.3 specification.
|
Namespace Alias
|
Namespace URI
|
Specification Description
|
|
tosca_simple_yaml_1_3
|
http://docs.oasis-open.org/tosca/ns/simple/yaml/1.3
|
The TOSCA Simple Profile v1.3 (YAML) target namespace and
namespace alias.
|
The following TOSCA Namespace prefix is a reserved
value and SHALL be used to reference the default TOSCA Namespace URI as
declared in TOSCA Service Templates.
|
Namespace Prefix
|
Specification Description
|
|
tosca
|
The reserved TOSCA Simple Profile Specification prefix
that can be associated with the default TOSCA Namespace URI
|
In the TOSCA Simple Profile, TOSCA Service Templates
MUST always have, as the first line of YAML, the keyword “tosca_definitions_version” with an associated
TOSCA Namespace Alias value. This single line accomplishes the following:
1. Establishes
the TOSCA Simple Profile Specification version whose grammar MUST be used to
parse and interpret the contents for the remainder of the TOSCA Service
Template.
2. Establishes
the default TOSCA Namespace URI and Namespace Prefix for all types found in the
document that are not explicitly namespaced.
3. Automatically
imports (without the use of an explicit import statement) the normative type
definitions (e.g., Node, Relationship, Capability, Artifact, etc.) that are
associated with the TOSCA Simple Profile Specification the TOSCA Namespace
Alias value identifies.
4. Associates
the TOSCA Namespace URI and Namespace Prefix to the automatically imported
TOSCA type definitions.
TOSCA Simple Profiles allows template authors to declare
their own types and templates and assign them simple names with no apparent
namespaces. Since TOSCA Service Templates can import other service templates
to introduce new types and topologies of templates that can be used to provide
concrete implementations (or substitute) for abstract nodes. Rules are needed
so that TOSCA Orchestrators know how to avoid collisions and apply their own
namespaces when import and nesting occur.
3.1.3.1 Additional Requirements
·
The URI value “http://docs.oasis-open.org/tosca”,
as well as all (path) extensions to it, SHALL be reserved for TOSCA approved
specifications and work. That means Service Templates that do not originate
from a TOSCA approved work product MUST NOT use it, in any form, when declaring
a (default) Namespace.
·
Since TOSCA Service Templates can import (or substitute in) other
Service Templates, TOSCA Orchestrators and tooling will encounter the “tosca_definitions_version” statement for each
imported template. In these cases, the following additional requirements
apply:
o
Imported type definitions with the same Namespace URI, local name
and version SHALL be equivalent.
o
If different values of the “tosca_definitions_version”
are encountered, their corresponding type definitions MUST be uniquely
identifiable using their corresponding Namespace URI using a different Namespace
prefix.
·
Duplicate local names (i.e., within the same Service Template
SHALL be considered an error. These include, but are not limited to duplicate
names found for the following definitions:
o
Repositories (repositories)
o
Data Types (data_types)
o
Node Types (node_types)
o
Relationship Types (relationship_types)
o
Capability Types (capability_types)
o
Artifact Types (artifact_types)
o
Interface Types (interface_types)
·
Duplicate Template names within a Service Template’s Topology
Template SHALL be considered an error. These include, but are not limited to
duplicate names found for the following template types:
o
Node Templates (node_templates)
o
Relationship Templates (relationship_templates)
o
Inputs (inputs)
o
Outputs (outputs)
·
Duplicate names for the following keynames within Types or
Templates SHALL be considered an error. These include, but are not limited to
duplicate names found for the following keynames:
o
Properties (properties)
o
Attributes (attributes)
o
Artifacts (artifacts)
o
Requirements (requirements)
o
Capabilities (capabilities)
o
Interfaces (interfaces)
o
Policies (policies)
o
Groups (groups)
3.2
Using Namespaces
As of TOSCA version 1.2, Service template authors may
declare a namespace within a Service Template that would be used as the default
namespace for any types (e.g., Node Type, Relationship Type, Data Type, etc.)
defined within the same Service template.
Specifically, a Service Template’s namespace declaration’s
URI would be used to form a unique, fully qualified Type name when combined
with the locally defined, unqualified name of any Type in the same Service
Template. The resulatant, fully qualified Type name would be used by TOSCA
Orchestrators, Processors and tooling when that Service Template was imported
into another Service Template to avoid Type name collision.
If a default namespace for the Service Template is declared,
then it should be declared immediately after the “tosca_definitions_version” declaration, to
ensure that the namespace is clearly visible.
3.2.1 Example – Importing a Service Template and Namespaces
For example, let say we have two Service Templates,
A and B, both of which define Types and a Namespace. Service Template B
contains a Node Type definition for “MyNode” and
declares its (default) Namespace to be “http://companyB.com/service/namespace/”:
Service Template B
|
tosca_definitions_version:
tosca_simple_yaml_1_2
description:
Service Template B
namespace:
http://companyB.com/service/namespace/
node_types:
MyNode:
derived_from: SoftwareComponent
properties:
# omitted here for brevity
capabilities:
# omitted here for brevity
|
Service Template A has its own, completely different, Node
Type definition also named “MyNode“.
Service Template A
|
tosca_definitions_version:
tosca_simple_yaml_1_2
description:
Service Template A
namespace:
http://companyA.com/product/ns/
imports:
-
file: csar/templates/ServiceTemplateB.yaml
namespace_prefix:
templateB
node_types:
MyNode:
derived_from: Root
properties:
# omitted here for brevity
capabilities:
# omitted here for brevity
|
As you can see, Service Template A also “imports“
Service Template B (i.e., “ServiceTemplateB.yaml“) bringing in its Type
defintions to the global namespace using the Namespace URI declared in Service
Template B to fully qualify all of its imported types.
In addition, the import includes a “namespace_prefix“ value
(i.e., “templateB“ ), that can be used to qualify and disambiguate any
Type reference from from Service Template B within Service Template A. This
prefix is effectively the local alias for the corresponding Namespace URI
declared within Service Template B (i.e., “http://companyB.com/service/namespace/“).
To illustrate conceptually what a TOSCA Orchestrator, for
example, would track for their global namespace upon processing Service
Template A (and by import Service Template B) would be a list of global
Namespace URIs and their associated Namespace prefixes, as well as a list of
fully qualified Type names that comprises the overall global namespace.
3.2.1.1 Conceptual Global Namespace URI and Namespace Prefix tracking
|
Entry#
|
Namespace URI
|
Namespace Prefix
|
Added by Key (Source
file)
|
|
1
|
http://open.org/tosca/ns/simple/yaml/1.3/
|
tosca
|
· tosca_definitions_version:
- from
Service Template A
|
|
2
|
http://companyA.com/product/ns/
|
<None>
|
· namespace:
- from
Service Template A
|
|
3
|
http://companyB.com/service/namespace/
|
templateB
|
· namespace:
- from
Service Template B
· namespace_prefix:
- from Service
Template A, during import
|
In the above table,
·
Entry 1: is an entry for the default TOSCA namespace,
which is required to exist for it to be a valid Service template. It is
established by the “tosca_definitions_version”
key’s value. By default, it also gets assigned the “tosca” Namespace prefix.
·
Entry 2: is the entry for the local default namespace for
Service Template A as declared by the “namespace”
key.
o
Note that no Namespace prefix is needed; any locally defined
types that are not qualified (i.e., not a full URI or using a Namespace Prefix)
will default to this namespace if not found first in the TOSCA namespace.
·
Entry 3: is the entry for default Namespace URI for any
type imported from Service Template B. The author of Service Template A has
assigned the local Namespace Prefix “templateB” that can be used to qualify
reference to any Type from Service Template B.
As per TOSCA specification, any Type, that is not qualified
with the ‘tosca’ prefix or full URI name, should be first resolved by its
unqualified name within the TOSCA namespace. If it not found there, then it
may be resolved within the local Service Template’s default namespace.
3.2.1.2 Conceptual Global Namespace and Type tracking
|
Entry#
|
Namespace URI
|
Unqualified Full
Name
|
Unqualified Short
Name
|
Type
Classification
|
|
1
|
http://open.org/tosca/ns/simple/yaml/1.3/
|
tosca.nodes.Compute
|
Compute
|
node
|
|
2
|
http://open.org/tosca/ns/simple/yaml/1.3/
|
tosca.nodes.SoftwareComponent
|
SoftwareComponent
|
|
|
3
|
http://open.org/tosca/ns/simple/yaml/1.3/
|
tosca.relationships.ConnectsTo
|
ConnectsTo
|
relationship
|
|
...
|
...
|
|
|
|
|
100
|
http://companyA.com/product/ns/
|
N/A
|
MyNode
|
node
|
|
...
|
...
|
|
|
|
|
200
|
http://companyB.com/service/namespace/
|
N/A
|
MyNode
|
node
|
|
...
|
...
|
|
|
|
In the above table,
·
Entry 1: is an example of one of the TOSCA standard Node
Types (i.e., “Compute”) that is brought into the global namespace via the
“tosca_definitions_version” key.
o
It also has two forms, full and short that are unique to TOSCA
types for historical reasons. Reference to a TOSCA type by either its
unqualified short or full names is viewed as equivalent as a reference to the
same fully qualified Type name (i.e., its full URI).
o
In this example, use of either “tosca.nodes.Compute”
or “Compute” (i.e., an unqualified full and
short name Type) in a Service Template would be treated as its fully qualified
URI equivalent of:
§
“http://docs.oasis-open.org/tosca/ns/simple/yaml/1.3/tosca.nodes.Compute”.
·
Entry 2: is an example of a standard TOSCA Relationship
Type
·
Entry 100: contains the unique Type identifer for the Node
Type “MyNode” from Service Template A.
·
Entry 200: contains the unique Type identifer for the Node
Type “MyNode” from Service Template B.
As you can see,
although both templates defined a NodeType with an unqualified name of
“MyNode”, the TOSCA Orchestrator, processor or tool tracks them by their unique
fully qualified Type Name (URI).
The
classification column is included as an example on how to logically
differentiate a “Compute” Node Type and “Compute” capability type if the table
would be used to “search” for a match based upon context in a Service
Template.
For example, if the
short name “Compute” were used in a template on a Requirements clause, then the
matching type would not be the Compute Node Type, but instead the Compute
Capability Type based upon the Requirement clause being the context for Type
reference.
This clause describes the primitive types that are used for
declaring normative properties, parameters and grammar elements throughout this
specification.
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) [YAML-1.2].
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:
3.3.1.1 Notes
·
The “string” type is the default type when not specified on a
parameter or property declaration.
·
While YAML supports further type aliases, such as “str” for
“string”, the TOSCA Simple Profile specification promotes the fully expressed
alias name for clarity.
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.
|
Shorthand Name
|
version
|
|
Type Qualified Name
|
tosca:version
|
3.3.2.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 an
optional 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.
3.3.2.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-specific. 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.
3.3.2.3 Examples
Examples of valid TOSCA version strings:
|
# basic version strings
6.1
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
|
3.3.2.4 Notes
·
[Maven-Version] The TOSCA
version type is compatible with the Apache Maven versioning policy.
3.3.2.5 Additional Requirements
·
A version value of zero (i.e., ‘0’, ‘0.0’, or ‘0.0.0’) SHALL
indicate there no version provided.
·
A version value of zero used with any qualifiers SHALL NOT be
valid.
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.
|
Shorthand Name
|
range
|
|
Type Qualified Name
|
tosca:range
|
3.3.3.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 or equal to lower_bound.
3.3.3.2 Keywords
The following Keywords may be used in the TOSCA
range type:
|
Keyword
|
Applicable Types
|
Description
|
|
UNBOUNDED
|
scalar
|
Used to represent an unbounded
upper bounds (positive) value in a set for a scalar type.
|
3.3.3.3 Examples
Example of a node template property with a range
value:
|
# numeric range between 1 and 100
a_range_property:
[ 1, 100 ]
# a
property that has allows any number 0 or greater
num_connections:
[ 0, UNBOUNDED ]
|
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 definitions,
or input or output parameter definitions.
|
Shorthand Name
|
list
|
|
Type Qualified Name
|
tosca:list
|
3.3.4.1 Grammar
TOSCA lists are essentially normal YAML lists with
the following grammars:
3.3.4.1.1 Square bracket notation
|
[
<list_entry_1>, <list_entry_2>, ... ]
|
3.3.4.1.2 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.
3.3.4.2 Declaration Examples
3.3.4.2.1 List declaration using a simple type
The following example shows a list declaration with
an entry schema based upon a simple integer type (which has additional
constraints):
|
<some_entity>:
...
properties:
listen_ports:
type: list
entry_schema:
description: listen port entry (simple integer type)
type: integer
constraints:
- max_length: 128
|
3.3.4.2.2 List declaration using a complex type
The following example shows a list declaration with
an entry schema based upon a complex type:
|
<some_entity>:
...
properties:
products:
type: list
entry_schema:
description: Product information entry (complex type) defined elsewhere
type:
ProductInfo
|
3.3.4.3 Definition Examples
These examples show two notation options for defining lists:
·
A single-line option which is useful for only short lists with
simple entries.
·
A multi-line option where each list entry is on 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.
3.3.4.3.1 Square bracket notation
|
listen_ports: [ 80, 8080 ]
|
3.3.4.3.2 Bulleted list notation
|
listen_ports:
- 80
- 8080
|
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.
In addition, the keys that identify entries in a map must be of the same type
as well. The type of these keys is defined by the key_schema attribute of the
respective property_definition, attribute_definition, or input or output
parameter_definition. If the key_schema is not specified, keys are assumed to
be of type string.
|
Shorthand Name
|
map
|
|
Type Qualified Name
|
tosca:map
|
3.3.5.1 Grammar
TOSCA maps are normal YAML dictionaries with
following grammar:
3.3.5.1.1 Single-line grammar
|
{ <entry_key_1>:
<entry_value_1>, ..., <entry_key_n>: <entry_value_n> }
|
3.3.5.1.2 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
3.3.5.2 Declaration Examples
3.3.5.2.1 Map declaration using a simple type
The following example shows a map with an entry
schema definition based upon an existing string type (which has additional
constraints):
|
<some_entity>:
...
properties:
emails:
type: map
entry_schema:
description: basic email address
type: string
constraints:
- max_length: 128
|
3.3.5.2.2 Map declaration using a complex type
The following example shows a map with an entry
schema definition for contact information:
|
<some_entity>:
...
properties:
contacts:
type: map
entry_schema:
description: simple contact information
type: ContactInfo
|
3.3.5.3 Definition Examples
These examples show two notation options for
defining maps:
·
A single-line option which is useful for only short maps with
simple entries.
·
A multi-line option where each map entry is on 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.
3.3.5.3.1 Single-line notation
|
# notation option for shorter maps
user_name_to_id_map:
{ user1: 1001, user2: 1002 }
|
3.3.5.3.2 Multi-line notation
|
# notation for longer maps
user_name_to_id_map:
user1:
1001
user2:
1002
|
The scalar-unit type can be used to define scalar values
along with a unit from the list of recognized units provided below.
3.3.6.1 Grammar
TOSCA scalar-unit typed values have the following
grammar:
In the above grammar, the pseudo values that appear
in angle brackets have the following meaning:
·
scalar: is a required
scalar value.
·
unit: is a required unit
value. The unit value MUST be type-compatible with the scalar.
3.3.6.2 Additional requirements
·
Whitespace: any number of spaces (including zero or
none) SHALL be allowed between the scalar
value and the unit value.
·
It SHALL be considered an error if either the scalar or
unit portion is missing on a property or attribute declaration derived from any
scalar-unit type.
·
When performing constraint clause evaluation on values of the
scalar-unit type, both the scalar value portion and unit value portion SHALL
be compared together (i.e., both are treated as a single value). For example,
if we have a property called storage_size.
which is of type scalar-unit, a valid range constraint would appear as follows:
o storage_size: in_range [ 4 GB, 20 GB ]
where storage_size’s range would be evaluated using
both the numeric and unit values (combined together), in this case ‘4 GB’ and
’20 GB’.
3.3.6.3 Concrete Types
|
Shorthand Names
|
scalar-unit.size, scalar-unit.time, scalar-unit.frequency,
scalar-unit.bitrate
|
|
Type Qualified Names
|
tosca:scalar-unit.size, tosca:scalar-unit.time
|
The scalar-unit type grammar is abstract and has four
recognized concrete types in TOSCA:
·
scalar-unit.size – used to define properties that have
scalar values measured in size units.
·
scalar-unit.time – used to define properties that have
scalar values measured in size units.
·
scalar-unit.frequency – used to define properties that
have scalar values measured in units per second.
·
scalar-unit.bitrate – used to define properties that have
scalar values measured in bits or bytes per second
These types and their allowed unit values are
defined below.
3.3.6.4.1 Recognized Units
|
Unit
|
Usage
|
Description
|
|
B
|
size
|
byte
|
|
kB
|
size
|
kilobyte (1000
bytes)
|
|
KiB
|
size
|
kibibytes (1024
bytes)
|
|
MB
|
size
|
megabyte (1000000
bytes)
|
|
MiB
|
size
|
mebibyte
(1048576 bytes)
|
|
GB
|
size
|
gigabyte
(1000000000 bytes)
|
|
GiB
|
size
|
gibibytes
(1073741824 bytes)
|
|
TB
|
size
|
terabyte
(1000000000000 bytes)
|
|
TiB
|
size
|
tebibyte
(1099511627776 bytes)
|
3.3.6.4.2 Examples
|
# Storage size in Gigabytes
properties:
storage_size: 10 GB
|
3.3.6.4.3 Notes
·
The unit values recognized by TOSCA Simple Profile for size-type
units are based upon a subset of those defined by GNU at http://www.gnu.org/software/parted/manual/html_node/unit.html,
which is a non-normative reference to this specification.
·
TOSCA treats these unit values as case-insensitive (e.g., a value
of ‘kB’, ‘KB’ or ‘kb’ would be equivalent), but it is considered best practice
to use the case of these units as prescribed by GNU.
·
Some Cloud providers may not support byte-level granularity for
storage size allocations. In those cases, these values could be treated as
desired sizes and actual allocations would be based upon individual provider
capabilities.
3.3.6.5
scalar-unit.time
3.3.6.5.1 Recognized Units
|
Unit
|
Usage
|
Description
|
|
d
|
time
|
days
|
|
h
|
time
|
hours
|
|
m
|
time
|
minutes
|
|
s
|
time
|
seconds
|
|
ms
|
time
|
milliseconds
|
|
us
|
time
|
microseconds
|
|
ns
|
time
|
nanoseconds
|
3.3.6.5.2 Examples
|
# Response time in milliseconds
properties:
respone_time: 10 ms
|
·
The unit values recognized by TOSCA Simple Profile for time-type
units are based upon a subset of those defined by International System of Units
whose recognized abbreviations are defined within the following reference:
o http://www.ewh.ieee.org/soc/ias/pub-dept/abbreviation.pdf
o
This document is a non-normative reference to this specification
and intended for publications or grammars enabled for Latin characters which
are not accessible in typical programming languages
3.3.6.6.1 Recognized Units
|
Unit
|
Usage
|
Description
|
|
Hz
|
frequency
|
Hertz, or Hz. equals one cycle
per second.
|
|
kHz
|
frequency
|
Kilohertz, or kHz, equals to
1,000 Hertz
|
|
MHz
|
frequency
|
Megahertz, or MHz, equals to
1,000,000 Hertz or 1,000 kHz
|
|
GHz
|
frequency
|
Gigahertz, or GHz, equals to
1,000,000,000 Hertz, or 1,000,000 kHz, or 1,000 MHz.
|
3.3.6.6.2 Examples
|
# Processor raw clock rate
properties:
clock_rate: 2.4 GHz
|
3.3.6.6.3 Notes
·
The value for Hertz (Hz) is the International Standard
Unit (ISU) as described by the Bureau International des Poids et Mesures (BIPM)
in the “SI Brochure: The International System of Units (SI)
[8th edition, 2006; updated in 2014]”, http://www.bipm.org/en/publications/si-brochure/
3.3.6.7 scalar-unit.bitrate
3.3.6.7.1 Recognized Units
|
Unit
|
Usage
|
Description
|
|
bps
|
bitrate
|
bit per second
|
|
Kbps
|
bitrate
|
kilobit (1000 bits) per second
|
|
Kibps
|
bitrate
|
kibibits (1024 bits) per second
|
|
Mbps
|
bitrate
|
megabit (1000000 bits) per
second
|
|
Mibps
|
bitrate
|
mebibit (1048576 bits) per
second
|
|
Gbps
|
bitrate
|
gigabit (1000000000 bits) per
second
|
|
Gibps
|
bitrate
|
gibibits (1073741824 bits) per
second
|
|
Tbps
|
bitrate
|
terabit (1000000000000 bits) per
second
|
|
Tibps
|
bitrate
|
tebibits (1099511627776 bits)
per second
|
|
Bps
|
bitrate
|
byte per second
|
|
KBps
|
bitrate
|
kilobyte (1000 bytes) per second
|
|
KiBps
|
bitrate
|
kibibytes (1024 bytes) per
second
|
|
MBps
|
bitrate
|
megabyte (1000000 bytes) per
second
|
|
MiBps
|
bitrate
|
mebibyte (1048576 bytes) per
second
|
|
GBps
|
bitrate
|
gigabyte (1000000000 bytes) per
second
|
|
GiBps
|
bitrate
|
gibibytes (1073741824 bytes) per
second
|
|
TBps
|
bitrate
|
terabytes (1000000000000 bits)
per second
|
|
TiBps
|
bitrate
|
tebibytes (1099511627776 bits)
per second
|
3.3.6.7.2 Examples
|
#### Somewhere in a node template definition
requirements:
-
link:
node_filter:
capabilities:
-
myLinkable
properties:
bitrate:
- greater_or_equal: 10 Kbps # 10 * 1000 bits per second at least
|
3.3.6.7.3 Notes
·
Unlike with the scalar-unit.size type, TOSCA treats scalar-unit.bitrate
values as case-sensitive (e.g., a value of ‘KBs’ means kilobyte per second,
whereas ‘Kb’ means kilobit per second).
·
For comparison purposes, 1 byte is the same as 8 bits.
As components (i.e., nodes) of TOSCA applications are
deployed, instantiated and orchestrated over their lifecycle using normative
lifecycle operations (see section 5.8 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
|
|
Value
|
Transitional
|
Description
|
|
initial
|
no
|
Node is not yet
created. Node only exists as a template definition.
|
|
creating
|
yes
|
Node is
transitioning from initial state to created state.
|
|
created
|
no
|
Node software
has been installed.
|
|
configuring
|
yes
|
Node is
transitioning from created state to configured state.
|
|
configured
|
no
|
Node has been configured
prior to being started.
|
|
starting
|
yes
|
Node is
transitioning from configured state to started state.
|
|
started
|
no
|
Node is started.
|
|
stopping
|
yes
|
Node is
transitioning from its current state to a configured state.
|
|
deleting
|
yes
|
Node is transitioning
from its current state to one where it is deleted and its state is no longer
tracked by the instance model.
|
|
error
|
no
|
Node is in an
error state.
|
Similar to the Node States described in the previous
section, Relationships have state relative to their (normative) lifecycle
operations.
The following table provides the list of recognized
relationship states for TOSCA Simple Profile that would be set by the
orchestrator to describe a node instance’s state:
|
Node State
|
|
Value
|
Transitional
|
Description
|
|
initial
|
no
|
Relationship is
not yet created. Relationship only exists as a template definition.
|
3.4.2.1 Notes
·
Additional states may be defined in future versions of the TOSCA
Simple Profile in YAML specification.
The following directive values are defined for this
version of the TOSCA Simple Profile:
|
Directive
|
Description
|
|
substitute
|
Marks a node
template as abstract and instructs the TOSCA Orchestrator to substitute this
node template with an appropriate substituting template.
|
|
substitutable
|
This deprecated
directive is synonymous to the substitute directive.
|
|
select
|
Marks a node
template as abstract and instructs the TOSCA Orchestrator to select a node of
this type from its inventory (based on constraints specified in the optional
node_filter in the node template)
|
|
selectable
|
This deprecated
directive is synonymous to the select directive.
|
The following are recognized values that may be used
as aliases to reference types of networks within an application model without
knowing their actual name (or identifier) which may be assigned by the
underlying Cloud platform at runtime.
|
Alias value
|
Description
|
|
PRIVATE
|
An alias used to
reference the first private network within a property or attribute of a Node
or Capability which would be assigned to them by the underlying platform at
runtime.
A private
network contains IP addresses and ports typically used to listen for incoming
traffic to an application or service from the Intranet and not accessible to
the public internet.
|
|
PUBLIC
|
An alias used to
reference the first public network within a property or attribute of a Node
or Capability which would be assigned to them by the underlying platform at
runtime.
A public network
contains IP addresses and ports typically used to listen for incoming traffic
to an application or service from the Internet.
|
3.4.4.1 Usage
These aliases would be used in the tosca.capabilities.Endpoint Capability type
(and types derived from it) within the network_name
field for template authors to use to indicate the type of network the Endpoint
is supposed to be assigned an IP address from.
This section defines all modelable entities that comprise
the TOSCA Version 1.0 Simple Profile specification along with their keynames,
grammar and requirements.
The TOSCA metamodel includes complex types (e.g., Node
Types, Relationship Types, Capability Types, Data Types, etc.) each of which
include their own list of reserved keynames that are sometimes marked as required.
These types may be used to derive other types. These derived types (e.g.,
child types) do not have to provide required keynames as long as they have been
specified in the type they have been derived from (i.e., their parent type).
This optional element provides a means include single or
multiline descriptions within a TOSCA Simple Profile template as a scalar
string value.
3.6.1.1 Keyname
The following keyname is used to provide a
description within the TOSCA Simple Profile specification:
3.6.1.2 Grammar
Description definitions have the following grammar:
3.6.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.
|
3.6.1.4 Notes
- Use of “folded” style is discouraged for the YAML string type
apart from when used with the description
keyname.
3.6.2 Metadata
This optional element provides a means to include optional
metadata as a map of strings.
3.6.2.1 Keyname
The following keyname is used to provide metadata
within the TOSCA Simple Profile specification:
3.6.2.2 Grammar
Metadata definitions have the following grammar:
3.6.2.3 Examples
|
metadata:
foo1:
bar1
foo2:
bar2
...
|
3.6.2.4 Notes
- Data provided within metadata, wherever it appears, MAY be
ignored by TOSCA Orchestrators and SHOULD NOT affect runtime behavior.
3.6.3 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.
The following is the list of recognized operators
(keynames) when defining constraint clauses:
|
Operator
|
Type
|
Value Type
|
Description
|
|
equal
|
scalar
|
any
|
Constrains a property or
parameter to a value equal to (‘=’) the value declared.
|
|
greater_than
|
scalar
|
comparable
|
Constrains a property or parameter
to a value greater than (‘>’) the value declared.
|
|
greater_or_equal
|
scalar
|
comparable
|
Constrains a property or
parameter to a value greater than or equal to (‘>=’) the value declared.
|
|
less_than
|
scalar
|
comparable
|
Constrains a property or parameter
to a value less than (‘<’) the value declared.
|
|
less_or_equal
|
scalar
|
comparable
|
Constrains a property or
parameter to a value less than or equal to (‘<=’) the value declared.
|
|
in_range
|
dual scalar
|
comparable, range
|
Constrains 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_values
|
list
|
any
|
Constrains a property or
parameter to a value that is in the list of declared values.
|
|
length
|
scalar
|
string, list, map
|
Constrains the property or
parameter to a value of a given length.
|
|
min_length
|
scalar
|
string, list, map
|
Constrains the property or
parameter to a value to a minimum length.
|
|
max_length
|
scalar
|
string, list, map
|
Constrains the property or
parameter to a value to a maximum length.
|
|
pattern
|
regex
|
string
|
Constrains 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.
|
|
schema
|
string
|
string
|
Constrains the property or parameter
to a value that is allowed by the referenced schema.
|
In the Value Type column above, an entry of
“comparable” includes integer, float, timestamp,
string, version,
and scalar-unit types while an entry of “any”
refers to any type allowed in the TOSCA simple profile in YAML.
3.6.3.2 Schema Constraint purpose
TOSCA recognizes that there are external
data-interchange formats that are widely used within Cloud service APIs and
messaging (e.g., JSON, XML, etc.).
The ‘schema’ Constraint was added so that, when TOSCA types
utilize types from these externally defined data (interchange) formats on Properties
or Parameters, their corresponding Property definitions’ values can be
optionally validated by TOSCA Orchestrators using the schema string provided on
this operator.
3.6.3.3 Additional Requirements
·
If no operator is present for a simple scalar-value on a
constraint clause, it SHALL be interpreted as being equivalent to having
the “equal” operator provided; however,
the “equal” operator may be used for
clarity when expressing a constraint clause.
·
The “length” operator SHALL
be interpreted mean “size” for set types (i.e., list, map, etc.).
- 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.
- The value for the keyname ‘schema’ SHOULD be a string that
contains a valid external schema definition that matches the corresponding
Property definitions type.
- When a valid ‘schema’ value is provided on a Property
definition, a TOSCA Orchestrator MAY choose use the contained schema
definition for validation.
3.6.3.4 Grammar
Constraint clauses have one of the following
grammars:
|
# 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>
# Schema
grammar
schema:
<schema_definition>
|
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 3.6.3.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.
·
schema_definition:
represents a schema definition as a string.
3.6.3.5 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
# schema
schema:
<
{
#
Some schema syntax that matches corresponding property or parameter.
}
|
A property filter definition defines criteria, using
constraint clauses, for selection of a TOSCA entity based upon it property
values.
3.6.4.1 Grammar
Property filter definitions have one of the following
grammars:
3.6.4.1.1 Short notation:
The following single-line grammar may be used when
only a single constraint is needed on a property:
3.6.4.1.2 Extended notation:
The following multi-line grammar may be used when
multiple constraints are needed on a property:
In the above grammars,
the pseudo values that appear in angle brackets have the following meaning:
·
property_name: represents
the name of property that would be used to select a property definition with
the same name (property_name) on a
TOSCA entity (e.g., a Node Type, Node Template, Capability Type, etc.).
·
property_constraint_clause_*:
represents constraint clause(s) that would be used to filter entities based
upon the named property’s value(s).
3.6.4.2 Additional Requirements
·
Property constraint clauses must be type compatible with the
property definitions (of the same name) as defined on the target TOSCA entity
that the clause would be applied against.
A node filter definition defines criteria for selection of a
TOSCA Node Template based upon the template’s property values, capabilities and
capability properties.
3.6.5.1 Keynames
The following is the list of recognized keynames for
a TOSCA node filter definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
properties
|
no
|
list of
property filter definition
|
An
optional list of property filters that would be used to select (filter)
matching TOSCA entities (e.g., Node Template, Node Type, Capability Types,
etc.) based upon their property definitions’ values.
|
|
capabilities
|
no
|
list of
capability names or capability
type names
|
An
optional list of capability names or types that would be used to select
(filter) matching TOSCA entities based upon their existence.
|
3.6.5.2 Additional filtering on named Capability properties
Capabilities used as filters often have their own
sets of properties which also can be used to construct a filter.
|
Keyname
|
Required
|
Type
|
Description
|
|
<capability
name_or_type>
name>:
properties
|
no
|
list of
property filter definitions
|
An
optional list of property filters that would be used to select (filter)
matching TOSCA entities (e.g., Node Template, Node Type, Capability Types,
etc.) based upon their capabilities’ property definitions’ values.
|
3.6.5.3 Grammar
Node filter definitions have following grammar:
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
property_filter_def_*: represents
a property filter definition that would be used to select (filter) matching
TOSCA entities (e.g., Node Template, Node Type, Capability Types, etc.) based
upon their property definitions’ values.
·
capability_name_or_type_*:
represents the type or name of a capability that would be used to select
(filter) matching TOSCA entities based upon their existence.
·
cap_*_property_def_*:
represents a property filter definition that would be used to select (filter)
matching TOSCA entities (e.g., Node Template, Node Type, Capability Types,
etc.) based upon their capabilities’ property definitions’ values.
3.6.5.4 Additional requirements
·
TOSCA orchestrators SHALL search for matching capabilities
listed on a target filter by assuming the capability name is first a symbolic
name and secondly it is a type name (in order to avoid namespace collisions).
3.6.5.5 Example
The following example is a filter that would be used to
select a TOSCA Compute node based upon
the values of its defined capabilities. Specifically, this filter would select
Compute nodes that supported a specific range of CPUs (i.e., num_cpus value between 1 and 4) and memory
size (i.e., mem_size of 2 or greater)
from its declared “host” capability.
|
my_node_template:
#
other details omitted for brevity
requirements:
-
host:
node_filter:
capabilities:
# My “host” Compute node needs these properties:
- host:
properties:
- num_cpus: { in_range: [ 1, 4 ] }
- mem_size: { greater_or_equal: 512 MB }
|
A repository definition defines a named external repository
which contains deployment and implementation artifacts that are referenced
within the TOSCA Service Template.
3.6.6.1 Keynames
The following is the list of recognized keynames for
a TOSCA repository definition:
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
description
|
no
|
description
|
None
|
The optional description for the
repository.
|
|
url
|
yes
|
string
|
None
|
The required URL or network
address used to access the repository.
|
|
credential
|
no
|
Credential
|
None
|
The optional Credential used to
authorize access to the repository.
|
3.6.6.2 Grammar
Repository definitions have one the following
grammars:
3.6.6.2.1 Single-line grammar (no credential):
3.6.6.2.2 Multi-line grammar
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
repository_name:
represents the required symbolic name of the repository as a string.
·
repository_description:
contains an optional description of the repository.
·
repository_address:
represents the required URL of the repository as a string.
·
authorization_credential:
represents the optional credentials (e.g., user ID and password) used to
authorize access to the repository.
3.6.6.3 Example
The following represents a repository definition:
|
repositories:
my_code_repo:
description: My project’s code repository in GitHub
url:
https://github.com/my-project/
|
An artifact definition defines a named, typed file that can
be associated with Node Type or Node Template and used by orchestration engine
to facilitate deployment and implementation of interface operations.
3.6.7.1 Keynames
The following is the list of recognized keynames for
a TOSCA artifact definition when using the extended notation:
|
Keyname
|
Required
|
Type
|
Description
|
|
type
|
yes
|
string
|
The required artifact type for
the artifact definition.
|
|
file
|
yes
|
string
|
The required URI string
(relative or absolute) which can be used to locate the artifact’s file.
|
|
repository
|
no
|
string
|
The optional name of the
repository definition which contains the location of the external repository
that contains the artifact. The artifact is expected to be referenceable by
its file URI within the repository.
|
|
description
|
no
|
description
|
The optional description for the
artifact definition.
|
|
deploy_path
|
no
|
string
|
The file path the associated
file would be deployed into within the target node’s container.
|
|
artifact_version
|
no
|
string
|
The version of this artifact.
One use of this artifact_version is to declare the particular version of this
artifact type, in addition to its mime_type (that is declared in the artifact
type definition). Together with the mime_type it may be used to select a
particular artifact processor for this artifact. For example a python
interpreter that can interpret python version 2.7.0
|
|
checksum
|
no
|
string
|
The checksum used to validate
the integrity of the artifact.
|
|
checksum_algorithm
|
no
|
string
|
Algorithm used to calculate the
artifact checksum (e.g. MD5, SHA [Ref]). Shall be
specified if checksum is specified for an artifact.
|
|
properties
|
no
|
map of
property
assignments
|
The optional map of property
assignments associated with the artifact.
|
3.6.7.2 Grammar
Artifact definitions have one of the following
grammars:
3.6.7.2.1 Short notation
The following single-line grammar may be used when
the artifact’s type and mime type can be inferred from the file URI:
3.6.7.2.2 Extended notation:
The following multi-line grammar may be used when
the artifact’s definition’s type and mime type need to be explicitly declared:
In the above grammars, the
pseudo values that appear in angle brackets have the following meaning:
·
artifact_name: represents
the required symbolic name of the artifact as a string.
·
artifact_description:
represents the optional description for
the artifact.
·
artifact_type_name:
represents the required artifact type
the artifact definition is based upon.
·
artifact_file_URI: represents the required URI string
(relative or absolute) which can be used to locate the artifact’s file.
·
artifact_repository_name: represents the optional name of the repository definition to use to
retrieve the associated artifact (file) from.
·
file_deployement_path:
represents the optional path the artifact_file_URI
would be copied into within the target node’s container.
·
artifact_version:
represents the version of artifact
·
artifact_checksum:
represents the checksum of the Artifact
·
artifact_checksum_algorithm:represents
the algorithm for verifying the checksum. Shall be specified if checksum is
specified
·
properties:
represents an optional map of property assignments associated with the artifact
3.6.7.3 Examples
The following represents an artifact definition:
|
my_file_artifact:
../my_apps_files/operation_artifact.txt
|
The following example represents an artifact definition with
property assignments:
|
artifacts:
sw_image:
description: Image for virtual machine
type: tosca.artifacts.Deployment.Image.VM
file: http://10.10.86.141/images/Juniper_vSRX_15.1x49_D80_preconfigured.qcow2
checksum: ba411cafee2f0f702572369da0b765e2
version: 3.2
checksum_algorithm: MD5
properties:
name: vSRX
container_format: BARE
disk_format: QCOW2
min_disk: 1 GB
size: 649 MB
|
3.6.8 Import definition
An import definition is used within a TOSCA Service Template
to locate and uniquely name another TOSCA Service Template file which has type
and template definitions to be imported (included) and referenced within
another Service Template.
3.6.8.1 Keynames
The following is the list of recognized keynames for
a TOSCA import definition:
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
file
|
yes
|
string
|
None
|
The required symbolic name for
the imported file.
|
|
repository
|
no
|
string
|
None
|
The optional symbolic name of
the repository definition where the imported file can be found as a string.
|
|
namespace_prefix
|
no
|
string
|
None
|
The optional namespace prefix
(alias) that will be used to indicate the namespace_uri when
forming a qualified name (i.e., qname) when referencing type definitions from
the imported file.
|
|
namespace_uri
|
no
|
string
|
Deprecated
|
The optional, deprecated
namespace URI to that will be applied to type definitions found within the
imported file as a string.
|
3.6.8.2 Grammar
Import definitions have one the following grammars:
3.6.8.2.1 Single-line grammar:
|
imports:
-
<URI_1>
-
<URI_2>
|
3.6.8.2.2 Multi-line grammar
|
imports:
-
file: <file_URI>
repository: <repository_name>
namespace_uri: <definition_namespace_uri> # deprecated
namespace_prefix: <definition_namespace_prefix>
|
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
file_uri: contains the
required name (i.e., URI) of the file to be imported as a string.
·
repository_name:
represents the optional symbolic name of the repository definition where the
imported file can be found as a string.
·
namespace_uri: represents
the optional namespace URI to that will be applied to type definitions found
within the imported file as a string.
·
namespace_prefix:
represents the optional namespace prefix (alias) that will be used to indicate
the default namespace as declared in the imported Service Template when forming
a qualified name (i.e., qname) when referencing type definitions from the
imported file as a string.
3.6.8.2.3 Requirements
·
The “file” keyname’s vlue MAY be an approved TOSCA Namespace
alias.
·
The namespace prefix “tosca” Is reserved and SHALL NOT be used to
as a value for “namespace_prefix” on import.
·
The imports key “namespace_uri” is now deprecated. It was
intended to be able to define a default namespace for any types that were
defined within the Service Template being imported; however, with version 1.2,
Service Templates MAY now declare their own default Namespace which SHALL be
used in place of this key’s value.
o
Please note that TOSCA Orchestrators and Processors MAY still use
the”namespace_uri” value if provided, if the imported Service Template has no
declared default Namespace value. Regardless it is up to the TOSCA
Orchestrator or Processor to resolve Namespace collisions caused by imports as
they see fit, for example, they may treat it as an error or dynamically
generate a unique namepspace themselves on import.
3.6.8.2.4 Import URI processing requirements
TOSCA Orchestrators, Processors and tooling SHOULD treat the
<file_URI> of an import as follows:
·
URI: If the <file_URI>
is a known namespace URI (identifier), such as a well-known URI defined by a
TOSCA specification, then it SHOULD cause the corresponding Type defintions to
be imported.
o
This implies that there may or may not be an actual Service
Template, perhaps it is a known set Types identified by the well-known URI.
o
This also implies that internet access is NOT needed to import.
·
Alias – If the <file_URI>
is a reserved TOSCA Namespace alias, then it SHOULD cause the corresponding Type
defintions to be imported, using the associated full, Namespace URI to uniquely
identify the imported types.
·
URL - If the <file_URI>
is a valid URL (i.e., network accessible as a remote resource) and the location
contains a valid TOSCA Service Template, then it SHOULD cause the remote
Service Template to be imported.
·
Relative path - If the <file_URI>
is a relative path URL, perhaps pointing to a Service Template located in the
same CSAR file, then it SHOULD cause the locally accessible Service Template to
be imported.
o
If the “repository” key is
supplied, this could also mean relative to the repository’s URL in a remote
file system;
o
If the importing file located in a CSAR file, it should be
treated as relative to the current document’s location within a CSAR file’s
directory structure.
·
Otherwise, the import SHOULD be considered a failure.
3.6.8.3 Example
The following represents how import definitions
would be used for the imports keyname within a TOSCA Service Template:
|
imports:
-
path1/path2/some_defs.yaml
-
file: path1/path2/file2.yaml
repository: my_service_catalog
namespace_uri: http://mycompany.com/tosca/1.0/platform
namespace_prefix: mycompany
|
3.6.9 Schema
Definition
All entries in a map or list for one property or parameter
must be of the same type. Similarly, all keys for map entries for one property
or parameter must be of the same type as well. A TOSCA schema definition
specifies the type (for simple entries) or schema (for complex entries) for
keys and entries in TOSCA set types such as the TOSCA list or map.
3.6.9.1 Keynames
The following is the list of recognized keynames for
a TOSCA schema definition:
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
type
|
yes
|
string
|
None
|
The required data type for the key
or entry.
|
|
description
|
no
|
description
|
None
|
The optional description for the
schema.
|
|
constraints
|
no
|
list of
constraint
clauses
|
None
|
The optional list of sequenced
constraint clauses for the property.
|
|
key_schema
|
no
|
schema_definition
|
None
|
When the schema itself is of
type map, the optional schema definition that is used to specify the type of
they keys of that map’s entries.
|
|
entry_schema
|
no
|
schema_definition
|
None
|
When the schema itself is of
type map or list, the optional schema definition that is used to specify the
type of the entries in that map or list
|
3.6.9.2 Grammar
Schema definitions have the following grammar:
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
schema_description:
represents the optional description of the schema definition
·
schema_type: represents
the required type name for
entries of the specified schema.
·
schema_constraints:
represents the optional list of one or more constraint
clauses on on entries of the specified schema.
·
key_schema_definition: if
the schema_type is map, represents the optional schema definition for they keys
of that map’s entries.
·
entry_schema_definition: if
the schema_type is map or list, represents the optional schema definition for
the entries in that map or list.
3.6.10 Property definition
A property definition defines a named, typed value and
related data that can be associated with an entity defined in this specification
(e.g., Node Types, Relationship Types, Capability Types, etc.). Properties are
used by template authors to provide input values to TOSCA entities which
indicate their “desired state” when they are instantiated. The value of a property
can be retrieved using the get_property
function within TOSCA Service Templates.
3.6.10.1 Attribute and Property reflection
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).
3.6.10.2 Keynames
The following is the list of recognized keynames for
a TOSCA property definition:
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
type
|
yes
|
string
|
None
|
The required data type for the
property.
|
|
description
|
no
|
description
|
None
|
The optional description for the
property.
|
|
required
|
no
|
boolean
|
default: true
|
An optional key that declares a
property as required (true) or not (false).
|
|
default
|
no
|
<any>
|
None
|
An optional key that may provide
a value to be used as a default if not provided by another means.
|
|
status
|
no
|
string
|
default: supported
|
The optional status of the
property relative to the specification or implementation. See table below for
valid values.
|
|
constraints
|
no
|
list of
constraint
clauses
|
None
|
The optional list of sequenced
constraint clauses for the property.
|
|
key_schema
|
no
|
schema_definition
|
None
|
The optional schema definition
for the keys used to identify entries in properties of type TOSCA map.
|
|
entry_schema
|
no
|
schema_definition
|
None
|
The optional schema definition
for the entries in properties of TOSCA set types such as list or map.
|
|
external-schema
|
no
|
string
|
None
|
The optional key that contains a
schema definition that TOSCA Orchestrators MAY use for validation when the
“type” key’s value indicates an External schema (e.g., “json”)
See section “External schema”
below for further explanation and usage.
|
|
metadata
|
no
|
map
of string
|
N/A
|
Defines a section used to
declare additional metadata information.
|
The following
property status values are supported:
|
Value
|
Description
|
|
supported
|
Indicates the property is
supported. This is the default value for all property definitions.
|
|
unsupported
|
Indicates the property is not
supported.
|
|
experimental
|
Indicates the property is
experimental and has no official standing.
|
|
deprecated
|
Indicates the property has been
deprecated by a new specification version.
|
3.6.10.4 Grammar
Named property definitions have the following
grammar:
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_description: represents
the optional description of the
property.
·
property_type: represents
the required data type of the property.
·
property_required:
represents an optional boolean value (true or
false) indicating whether or not the property is required. If this keyname is
not present on a property definition, then the property SHALL be considered required
(i.e., true) by default.
·
default_value: contains a
type-compatible value that may be used as a default if not provided by another
means.
·
status_value: a string that contains a keyword that indicates the
status of the property relative to the specification or implementation.
·
property_constraints:
represents the optional list of one or more sequenced constraint clauses on the property
definition.
·
key_schema_definition: if
the property_type is map, represents the optional schema definition for they
keys used to identify entries in that map.
·
entry_schema_definition: if
the property_type is map or list, represents the optional schema definition for
the entries in that map or list.
·
metadata_map: represents
the optional map of string.
3.6.10.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.
·
A property SHALL be considered required by default
(i.e., as if the required keyname on
the definition is set to true) unless
the definition’s required keyname is
explicitly set to false.
·
The value provided on a property definition’s default keyname SHALL be type compatible with
the type declared on the definition’s type
keyname.
·
Constraints of a property definition SHALL be
type-compatible with the type defined for that definition.
·
If a ‘schema’ keyname is provided, its value (string) MUST
represent a valid schema definition that matches the recognized external type provided
as the value for the ‘type’ keyname as described
by its correspondig schema specification.
·
TOSCA Orchestrators MAY choose to validate the value of the
‘schema’ keyname in accordance with the corresponding schema specifcation for
any recognized external types.
3.6.10.6 Refining Property Definitions
TOSCA allows derived types to refine properties defined in base
types. A property definition in a derived type is considered a refinement when
a property with the same name is already defined in one of the base types for
that type.
Property definition refinements use parameter definition grammar
rather than property definition
grammar. Specifically, this means the following:
·
The type keyname is
optional. If no type is specified, the property refinement reuses the type of
the property it refines. If a type is specified, the type must be the same as
the type of the refined property or it must derive from the type of the refined
property.
·
Property definition refinements support the value keyname that specifies a fixed type-compatible
value to assign to the property. These value assignments are considered final,
meaning that it is not valid to change the property value later (e.g. using
further refinements)..
Property refinement definitions can refine properties
defined in one of base types by doing one or more of the following:
·
Assigning a new (compatible) type as per the rules outlined
above.
·
Assigning a (final) fixed value
·
Adding a default value
·
Changing a default value
·
Adding constraints.
·
Turning an optional property into a required property.
No other refinements are allowed.
3.6.10.7 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.
- 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.
3.6.10.8 Examples
The following represents an example of a property
definition with constraints:
|
properties:
num_cpus:
type: integer
description: Number of CPUs requested for a software node instance.
default: 1
required: true
constraints:
-
valid_values: [ 1, 2, 4, 8 ]
|
The following shows an example
of a property refinement. Consider the definition of an Endpoint capability
type:
tosca.capabilities.Endpoint:
derived_from: tosca.capabilities.Root
properties:
protocol:
type: string
required: true
default: tcp
port:
type: PortDef
required: false
secure:
type: boolean
required: false
default: false
# Other property definitions omitted for brevity
|
The Endpoint.Admin capability type refines the secure property of the Endpoint capability type from
which it derives by forcing its value to always be true:
tosca.capabilities.Endpoint.Admin:
derived_from: tosca.capabilities.Endpoint
# Change Endpoint secure indicator to true from its
default of false
properties:
secure: true
|
3.6.11 Property assignment
This section defines the grammar for assigning values to
named properties within TOSCA Node and Relationship templates that are defined
in their corresponding named types.
3.6.11.1 Keynames
The TOSCA property assignment has no keynames.
3.6.11.2 Grammar
Property assignments have the following grammar:
3.6.11.2.1 Short notation:
The following single-line grammar may be used when a
simple value assignment is needed:
|
<property_name>:
<property_value> | { <property_value_expression> }
|
In the above grammars, the pseudo values that appear
in angle brackets have the following meaning:
·
property_name: represents
the name of a property that would be used to select a property definition with
the same name within on a TOSCA entity (e.g., Node Template, Relationship
Template, etc.,) which is declared in its declared type (e.g., a Node Type,
Node Template, Capability Type, etc.).
·
property_value, property_value_expression:
represent the type-compatible value to assign to the named property. Property
values may be provided as the result from the evaluation of an expression or a
function.
An attribute definition defines a named, typed value that can
be associated with an entity defined in this specification (e.g., a Node,
Relationship or Capability Type). Specifically, it is used to expose the
“actual state” of some property of a TOSCA entity after it has been deployed
and instantiated (as set by the TOSCA orchestrator). Attribute values can be
retrieved via the get_attribute
function from the instance model and used as values to other entities within
TOSCA Service Templates.
3.6.12.1 Attribute and Property reflection
TOSCA orchestrators automatically create Attribute definitions for any Property definitions declared on the
same TOSCA entity (e.g., nodes, node capabilities and relationships) in order
to make accessible the actual (i.e., the current state) value from the running
instance of the entity.
3.6.12.2 Keynames
The following is the list of recognized keynames for
a TOSCA attribute definition:
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
type
|
yes
|
string
|
None
|
The required data type for the
attribute.
|
|
description
|
no
|
description
|
None
|
The optional description for the
attribute.
|
|
default
|
no
|
<any>
|
None
|
An optional key that may provide
a value to be used as a default if not provided by another means.
This value SHALL be type
compatible with the type declared by the property definition’s type keyname.
|
|
status
|
no
|
string
|
default: supported
|
The optional status of the
attribute relative to the specification or implementation. See supported status values defined under the Property definition section.
|
|
key_schema
|
No
|
schema_definition
|
None
|
The optional schema definition
for the keys used to identify entries in attributes of type TOSCA map.
|
|
entry_schema
|
no
|
schema_definition
|
None
|
The optional schema definition
for the entries in attributes of TOSCA set types such as list or map.
|
3.6.12.3 Grammar
Attribute definitions have the following grammar:
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
attribute_name:
represents the required symbolic name of the attribute as a string.
·
attribute_type:
represents the required data type of the attribute.
·
attribute_description:
represents the optional description of
the attribute.
·
default_value: contains a
type-compatible value that may be used as a default if not provided by another
means.
·
status_value: contains a
value indicating the attribute’s status relative to the specification version
(e.g., supported, deprecated, etc.). Supported status values for this keyname
are defined under Property definition.
·
key_schema_definition: if
the attribute_type is map, represents the optional schema definition for they
keys used to identify entries in that map.
·
entry_schema_definition: if
the attribute_type is map or list, represents the optional schema definition
for the entries in that map or list.
3.6.12.4 Additional Requirements
·
In addition to any explicitly defined attributes on a TOSCA
entity (e.g., Node Type, RelationshipType, etc.), implementations of the TOSCA
Simple Profile MUST 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.
·
Values for the default keyname MUST be derived or
calculated from other attribute or operation output values (that reflect the
actual state of the instance of the corresponding resource) and not hard-coded
or derived from a property settings or inputs (i.e., desired state).
3.6.12.5 Notes
·
Attribute definitions are very similar to Property definitions; however,
properties of entities reflect an input that carries the template author’s
requested or desired value (i.e., desired state) which the orchestrator
(attempts to) use when instantiating the entity whereas attributes reflect the
actual value (i.e., actual state) that provides the actual instantiated value.
o
For example, a property can be used to request the IP address of
a node using a property (setting); however, the actual IP address after the
node is instantiated may by different and made available by an attribute.
3.6.12.6 Example
The following represents a required attribute definition:
|
actual_cpus:
type:
integer
description: Actual number of CPUs allocated to the node instance.
|
This section defines the grammar for assigning values to
named attributes within TOSCA Node and Relationship templates which are defined
in their corresponding named types.
3.6.13.1 Keynames
The TOSCA attribute assignment has no keynames.
3.6.13.2 Grammar
Attribute assignments have the following grammar:
3.6.13.2.1 Short notation:
The following single-line grammar may be used when a
simple value assignment is needed:
|
<attribute_name>: <attribute_value> | {
<attribute_value_expression> }
|
3.6.13.2.2 Extended notation:
The following multi-line grammar may be used when a
value assignment requires keys in addition to a simple value assignment:
|
<attribute_name>:
description: <attribute_description>
value:
<attribute_value> | { <attribute_value_expression> }
|
In the above grammars, the
pseudo values that appear in angle brackets have the following meaning:
·
attribute_name: represents
the name of an attribute that would be used to select an attribute definition
with the same name within on a TOSCA entity (e.g., Node Template, Relationship
Template, etc.) which is declared (or reflected from a Property definition) in
its declared type (e.g., a Node Type, Node Template, Capability Type, etc.).
·
attribute_value, attribute_value_expresssion:
represent the type-compatible value to assign to the named attribute.
Attribute values may be provided as the result from the evaluation of an
expression or a function.
·
attribute_description:
represents the optional description of
the attribute.
3.6.13.3 Additional requirements
·
Attribute values MAY be provided by the underlying
implementation at runtime when requested by the get_attribute function or it MAY
be provided through the evaluation of expressions and/or functions that derive
the values from other TOSCA attributes (also at runtime).
3.6.14 Parameter definition
A parameter definition is essentially a TOSCA property
definition; however, it also allows a value to be assigned to it (as for a
TOSCA property assignment). In addition, in the case of output parameters, it
can optionally inherit the data type of the value assigned to it rather than
have an explicit data type defined for it.
3.6.14.1 Keynames
The TOSCA parameter definition has all the keynames
of a TOSCA Property definition, but in addition includes the following
additional or changed keynames:
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
type
|
no
|
string
|
None
|
The required data type for the
parameter.
Note: This keyname is required for a TOSCA Property
definition, but is not for a TOSCA Parameter definition.
|
|
value
|
no
|
<any>
|
N/A
|
The type-compatible value to
assign to the named parameter. Parameter values may be provided as the
result from the evaluation of an expression or a function.
|
3.6.14.2 Grammar
Named parameter definitions have the following
grammar:
In addition, the following
single-line grammar is supported when only a fixed value needs to be provided:
|
<parameter_name>: <parameter_value> | {
<parameter_value_expression> }
|
This single-line grammar
is equivalent to the following:
|
<parameter_name>:
value : <parameter_value> | {
<parameter_value_expression> }
|
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
parameter_name: represents
the required symbolic name of the parameter as a string.
·
parameter_description:
represents the optional description of
the parameter.
·
parameter_type:
represents the optional data type of the parameter. Note, this keyname is
required for a TOSCA Property definition, but is not for a TOSCA Parameter
definition.
·
parameter_value, parameter_value_expresssion:
represent the type-compatible value to assign to the named parameter.
Parameter values may be provided as the result from the evaluation of an
expression or a function.
·
parameter_required:
represents an optional boolean value (true or
false) indicating whether or not the parameter is required. If this keyname is
not present on a parameter definition, then the property SHALL be considered required
(i.e., true) by default.
·
default_value: contains a
type-compatible value that may be used as a default if not provided by another
means.
·
status_value: a string that contains a keyword that indicates the
status of the parameter relative to the specification or implementation.
·
parameter_constraints:
represents the optional list of one or more sequenced constraint clauses on the parameter
definition.
·
key_schema_definition: if
the parameter_type is map, represents the optional schema definition for they
keys used to identify entries in that map.
·
entry_schema_definition: if
the parameter_type is map or list, represents the optional schema definition
for the entries in that map or list.
3.6.14.3 Additional Requirements
·
A parameter SHALL be considered required by default
(i.e., as if the required keyname on
the definition is set to true) unless
the definition’s required keyname is
explicitly set to false.
·
The value provided on a parameter definition’s default keyname SHALL be type
compatible with the type declared on the definition’s type keyname.
- Constraints of a parameter definition SHALL be
type-compatible with the type defined for that definition.
3.6.14.4 Example
The following represents an example of an input
parameter definition with constraints:
|
inputs:
cpus:
type: integer
description: Number of CPUs for the server.
constraints:
-
valid_values: [ 1, 2, 4, 8 ]
|
The following represents
an example of an (untyped) output parameter definition:
|
outputs:
server_ip:
description:
The private IP address of the provisioned server.
value: { get_attribute: [ my_server, private_address ] }
|
3.6.15 Attribute Mapping definition
An attribute mapping defines a named output value that is
expected to be returned by an operation implementations and a mapping that
specifies the node or relationship attribute into which the returned output
value must be stored.
3.6.15.1 Grammar
Attribute mappings have the following grammar :
|
output_name: [ <SELF | SOURCE | TARGET >, <optional_capability_name>,
<attribute_name>, <nested_attribute_name_or_index_1>, ...,
<nested_attribute_name_or_index_or_key_n> ]
|
The various entities in this grammar are defined as follows:
|
Parameter
|
Required
|
Type
|
Description
|
|
SELF | SOURCE | TARGET
|
yes
|
string
|
For operation outputs in
interfaces on node templates, the only allowed keyname is SELF: output values
must always be stored into attributes that belong to the node template that
has the interface for which the output values are returned.
For operation outputs in
interfaces on relationship templates, allowable keynames are SELF, SOURCE, or
TARGET.
|
|
<optional_capability_name>
|
no
|
string
|
The optional name of the
capability within the specified node template that contains the named
attribute into which the output value must be stored.
|
|
<attribute_name>
|
yes
|
string
|
The name of the attribute into
which the output value must be stored.
|
|
<nested_attribute_name_or_index_or_key_*>
|
no
|
string| integer
|
Some TOSCA attributes 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 or map types.
In these cases, an index or key may be provided to reference a specific entry
in the list or map (as named in the previous parameter) to return.
|
Note that it is possible for multiple operations to define
outputs that map onto the same attribute value. For example, a create
operation could include an output value that sets an attribute to an initial
value, and the subsequence configure operation could then update that
same attribute to a new value.
It is also possible that a node template assigns a value to
an attribute that has an operation output mapped to it (including a value that
is the result of calling an intrinsic function). Orchestrators could use the
assigned value for the attribute as its initial value. After the operation runs
that maps an output value onto that attribute, the orchestrator must then use
the updated value, and the value specified in the node template will no longer
be used.
3.6.16 Operation implementation
definition
An operation implementation definition specifies one or more
artifacts (e.g. scripts) to be used as the implementation for an operation in
an interface.
3.6.16.1 Keynames
The following is the list of recognized keynames for
a TOSCA operation implementation definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
primary
|
no
|
Artifact definition
|
The optional implementation
artifact (i.e., the primary script file within a TOSCA CSAR file).
|
|
dependencies
|
no
|
list of
Artifact definition
|
The optional list of one or more
dependent or secondary implementation artifacts which are referenced by the
primary implementation artifact (e.g., a library the script installs or a
secondary script).
|
|
timeout
|
No
|
integer
|
Timeout value in seconds
|
|
operation_host
|
no
|
string
|
The node on which operations
should be executed (for TOSCA call_operation activities).
If the operation is associated
with an interface on a node type or a relationship template, valid_values are
SELF or HOST – referring to the node itself or to the node that is the target
of the HostedOn relationship for that node.
If the operation is associated
with a relationship type or a relationship template, valid_values are SOURCE
or TARGET – referring to the relationship source or target node.
In both cases, the value can
also be set to ORCHESTRATOR to indicated that the operation must be executed
in the orchestrator environment rather than within the context of the service
being orchestrated.
|
3.6.16.2 Grammar
Operation implementation definitions have the
following grammars:
3.6.16.2.1 Short notation for use with single artifact
The following single-line grammar may be used when
only a primary implementation artifact name is needed:
This notation can be used
when the primary artifact name uniquely identifies the artifact, either because
it refers to a named artifact specified in the artifacts section of a type or
template, or because it represents the name of a script in the CSAR file
that contains the definition.
3.6.16.2.2 Short notation for use with multiple artifact
The following multi-line short-hand grammar may be
used when multiple artifacts are needed, but each of the artifacts can be
uniquely identified by name as before:
|
implementation:
primary: <primary_artifact_name>
dependencies:
- <list_of_dependent_artifact_names>
operation_host :
SELF
timeout : 60
|
3.6.16.2.3 Extended notation for use with single artifact
The following multi-line grammar may be used in Node
or Relationship Type or Template definitions when only a single artifact is
used but additional information about the primary artifact is needed (e.g. to
specify the repository from which to obtain the artifact, or to specify the
artifact type when it cannot be derived from the artifact file extension):
3.6.16.2.4 Extended notation for use with multiple artifacts
The following multi-line grammar may be used in Node
or Relationship Type or Template definitions when there are multiple artifacts
that may be needed for the operation to be implemented and additional information
about each of the artifacts is required:
|
implementation:
primary:
<primary_artifact_definition>
dependencies:
-
<list_of_dependent_artifact
definitions>
operation_host: HOST
timeout: 120
|
In the above
grammars, the pseudo values that appear in angle brackets have the following
meaning:
·
primary_artifact_name:
represents the optional name (string) of an
implementation artifact definition (defined elsewhere), or the direct name of
an implementation artifact’s relative filename (e.g., a service
template-relative, path-inclusive filename or absolute file location using a
URL).
·
primary_artifact_definition:
represents a full inline definition of an implementation artifact.
·
list_of_dependent_artifact_names:
represents the optional ordered list of one or more dependent or secondary
implementation artifact names (as strings) which are referenced by the primary
implementation artifact. TOSCA orchestrators will copy these files to the same
location as the primary artifact on the target node so as to make them
accessible to the primary implementation artifact when it is executed.
·
list_of_dependent_artifact_definitions:
represents the ordered list of one or more inline definitions of dependent or
secondary implementation artifacts. TOSCA orchestrators will copy these artifacts
to the same location as the primary artifact on the target node so as to make
them accessible to the primary implementation artifact when it is executed.
3.6.17 Operation definition
An operation definition defines a named function or
procedure that can be bound to an operation implementation.
3.6.17.1 Keynames
The following is the list of recognized keynames for
a TOSCA operation definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
description
|
no
|
description
|
The optional description string
for the associated named operation.
|
|
implementation
|
no
|
Operation implementation definition
|
The optional definition of the
operation implementation
|
|
inputs
|
no
|
map of
parameter
definitions
|
The optional map of input
properties definitions (i.e., parameter definitions) for operation
definitions that are within TOSCA Node or Relationship Type definitions. This
includes when operation definitions are included as part of a Requirement
definition in a Node Type.
|
|
no
|
map of
property
assignments
|
The optional map of input
property assignments (i.e., parameters assignments) for operation definitions
that are within TOSCA Node or Relationship Template definitions. This
includes when operation definitions are included as part of a Requirement
assignment in a Node Template.
|
|
outputs
|
no
|
map of
attribute mappings
|
The optional map of attribute
mappings that specify named operation output values and their mappings onto
attributes of the node_type or relationship that contains the interface
within which the operation is defined.
|
3.6.17.2 Grammar
Operation definitions have the following grammars:
3.6.17.2.1 Short notation
The following single-line grammar may be used when the
operation’s implementation definition is the only keyname that is needed, and
when the operation implementation definition itself can be specified using a
single line grammar
3.6.17.2.2 Extended notation for use in Type definitions
The following multi-line grammar may be used in Node
or Relationship Type definitions when additional information about the
operation is needed:
3.6.17.2.3 Extended notation for use in Template definitions
The following multi-line grammar may be used in Node
or Relationship Template definitions when additional information about the
operation is needed:
In the above grammars, the
pseudo values that appear in angle brackets have the following meaning:
·
operation_name:
represents the required symbolic name of the operation as a string.
·
operation_description:
represents the optional description
string for the corresponding operation_name.
·
operation_implementation_definition:
represents the optional specification of the operation’s implementation).
·
property_definitions:
represents the optional map of property
definitions which the TOSCA orchestrator would make available (i.e., or
pass) to the corresponding implementation artifact during its execution.
·
property_assignments:
represents the optional map of property assignments for passing parameters to
Node or Relationship Template operations providing values for properties
defined in their respective type definitions.
·
attribute_mappings: represents
the optional map of of attribute_mappings that consists of named output values
returned by operation implementations (i.e. artifacts) and associated mappings
that specify the attribute into which this output value must be stored.
3.6.17.3 Additional requirements
·
The default sub-classing behavior for implementations of
operations SHALL be override. That is, implementation artifacts assigned in
subclasses override any defined in its parent class.
·
Template authors MAY provide property assignments on operation
inputs on templates that do not necessarily have a property definition defined
in its corresponding type.
·
Implementation artifact file names (e.g., script filenames) may
include file directory path names that are relative to the TOSCA service template
file itself when packaged within a TOSCA Cloud Service ARchive (CSAR) file.
3.6.17.4 Examples
3.6.17.4.1 Single-line example
|
interfaces:
Standard:
start: scripts/start_server.sh
|
3.6.17.4.2 Multi-line example with shorthand implementation definitions
|
interfaces:
Configure:
pre_configure_source:
implementation:
primary: scripts/pre_configure_source.sh
dependencies:
- scripts/setup.sh
- binaries/library.rpm
- scripts/register.py
|
3.6.17.4.3 Multi-line example with extended implementation definitions
|
interfaces:
Configure:
pre_configure_source:
implementation:
primary:
file: scripts/pre_configure_source.sh
type: tosca.artifacts.Implementation.Bash
repository: my_service_catalog
dependencies:
- file : scripts/setup.sh
type : tosca.artifacts.Implementation.Bash
Repository : my_service_catalog
|
A notification implementation definition specifies one or
more artifacts to be used by the orchestrator to subscribe to that particular
notification. We use the primary and dependencies keynames as in
the operation implementation definition.
3.6.18.1 Keynames
The following is the list of recognized keynames for
a TOSCA notification implementation definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
primary
|
no
|
Artifact definition
|
The optional implementation
artifact (i.e., the primary script file within a TOSCA CSAR file).
|
|
dependencies
|
no
|
list of
Artifact definition
|
The optional list of one or more
dependent or secondary implementation artifacts which are referenced by the
primary implementation artifact (e.g., a library the script installs or a
secondary script).
|
3.6.18.2 Grammar
Notification implementation definitions have the
following grammars:
3.6.18.2.1 Short notation for use with single artifact
The following single-line grammar may be used when
only a primary implementation artifact name is needed:
This notation can be used
when the primary artifact name uniquely identifies the artifact, either because
it refers to a named artifact specified in the artifacts section of a
type or template, or because it represents the name of a script in the CSAR
file that contains the definition.
3.6.18.2.2 Short notation for use with multiple artifact
The following multi-line short-hand grammar may be
used when multiple artifacts are needed, but each of the artifacts can be
uniquely identified by name as before:
|
implementation:
primary: <primary_artifact_name>
dependencies:
- <list_of_dependent_artifact_names>
|
3.6.19 Notification definition
A notification definition defines a named notification that
can be associated with an interface. The notification is a way for an external
event to be transmitted to the TOSCA orchestrator. Parameter values can be sent
together with a notification and we can map them to node/relationship
attributes imilarly to the way operation outputs are mapped to attributes. The
artifact that the orchestrator is registering with in order to receive the
notification is specified using the “implementation” keyname in a similar way
to operations.
When the notification is received an event is generated
within the orchestrator that can be associated to triggers in policies to call
other internal operations and workflows. The notification name (the unqualified
full name) itself identifies the event type that is generated and can be
textually used when defining the associated triggers.
3.6.19.1 Keynames
The following is the list of recognized keynames for
a TOSCA notification definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
description
|
no
|
description
|
The optional description string
for the associated named notification.
|
|
implementation
|
no
|
notification implementation
definition
|
The optional definition of the
notification implementation.
|
|
outputs
|
no
|
map of attribute mappings
|
The optional map of property mappings
that specify named notification output values and their mappings onto
attributes of the node or relationship that contains the interface within
which the notification is defined.
|
3.6.19.2 Grammar
The following multi-line grammar may be used in Node
or Relationship Template or Type definitions:
|
<notification_name>:
description: <notification_description>
implementation: <notification_implementation_definition>
outputs:
<attribute_mappings>
|
In the above grammar,
the pseudo values that appear in angle brackets have the following meaning:
·
notification_name:
represents the required symbolic name of the notification as a string.
·
notification_description:
represents the optional description string for the corresponding
notification_name.
·
notification_implementation_definition:
representes the optional specification of the notification implementation (i.e.
the external artifact that is may send notifications)
·
attribute_mappings: represents
the optional map of attribute assignments for mapping the outputs values to the
respective attributes of the node or relationship.
3.6.20 Interface definition
An interface definition defines a named interface that can
be associated with a Node or Relationship Type
3.6.20.1 Keynames
The following is the list of recognized keynames for
a TOSCA interface definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
inputs
|
no
|
map of
property definitions
|
The optional map of input
property definitions available to all defined operations for interface
definitions that are within TOSCA Node or Relationship Type definitions. This
includes when interface definitions are included as part of a Requirement
definition in a Node Type.
|
|
no
|
map of
property
assignments
|
The optional map of input
property assignments (i.e., parameters assignments) for interface definitions
that are within TOSCA Node or Relationship Template definitions. This
includes when interface definitions are referenced as part of a Requirement assignment
in a Node Template.
|
|
operations
|
no
|
map of operation definitions
|
The optional map of operations
defined for this interface.
|
|
notifications
|
no
|
map of notification definitions
|
The optional map of
notifications defined for this interface.
|
3.6.20.2 Grammar
Interface definitions have the following grammar:
3.6.20.2.1 Extended notation for use in Type definitions
The following multi-line grammar may be used in Node
or Relationship Type definitions:
3.6.20.2.2 Extended notation for use in Template definitions
The following multi-line grammar may be used in Node
or Relationship Template definitions:
In the above grammars, the
pseudo values that appear in angle brackets have the following meaning:
·
interface_definition_name: represents
the required symbolic name of the interface as a string.
·
interface_type_name: represents the required name of the Interface
Type for the interface definition.
·
property_definitions:
represents the optional map of property
definitions (i.e., parameters) which the TOSCA orchestrator would make
available (i.e., or pass) to all defined operations.
-
This means these properties and their values would be
accessible to the implementation artifacts (e.g., scripts) associated to each
operation during their execution.
·
property_assignments:
represents the optional map of property
assignments for passing parameters to Node or Relationship Template
operations providing values for properties defined in their respective type
definitions.
·
operation_definitions: represents the required name of one or more operation definitions.
·
notification_definitions:
represents the required name of one or more notification definitions.
3.6.20.3 Notes
Starting with Version 1.3 of this specification, interface definition
grammar was changed to support notifications as well as operations. As a result,
operations must now be specified under the newly-introduced operations keyname and the notifications
under the new notifications keyname. For
backward compatibility if neither the operations or notifications are specified
then we assume the symbolic names in the interface definition to mean
operations, but this use is deprecated. Operations and notifications names
should not overlap.
An event filter definition defines criteria for selection of
an attribute, for the purpose of monitoring it, within a TOSCA entity, or one
its capabilities.
3.6.21.1 Keynames
The following is the list of recognized keynames for
a TOSCA event filter definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
node
|
yes
|
string
|
The
required name of the node type or template that contains either the attribute
to be monitored or contains the requirement that references the node that
contains the attribute to be monitored.
|
|
requirement
|
no
|
string
|
The optional
name of the requirement within the filter’s node that can be used to locate a
referenced node that contains an attribute to monitor.
|
|
capability
|
no
|
string
|
The
optional name of a capability within the filter’s node or within the node
referenced by its requirement that contains the attribute to monitor.
|
3.6.21.2 Grammar
Event filter definitions have following grammar:
|
node: <node_type_name> |
<node_template_name>
requirement:
<requirement_name>
capability:
<capability_name>
|
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
node_type_name: represents
the required name of the node type that would be used to select (filter) the
node that contains the attribute to monitor or contains the requirement that
references another node that contains the attribute to monitor.
·
node_template_name: represents
the required name of the node template that would be used to select (filter)
the node that contains the attribute to monitor or contains the requirement
that references another node that contains the attribute to monitor.
·
requirement_name: represents
the optional name of the requirement that would be used to select (filter) a
referenced node that contains the attribute to monitor.
·
capability_name: represents
the optional name of a capability that would be used to select (filter) the
attribute to monitor. If a requirement_name is specified, then the
capability_name refers to a capability of the node that is targeted by the
requirement.
3.6.22 Trigger definition
A trigger definition defines the event, condition and action
that is used to “trigger” a policy it is associated with.
3.6.22.1 Keynames
The following is the list of recognized keynames for
a TOSCA trigger definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
description
|
no
|
description
|
The optional description string
for the named trigger.
|
|
event
|
yes
|
string
|
The required name of the event
that activates the trigger’s action. A deprecated form of this keyname is “event_type”.
|
|
schedule
|
no
|
TimeInterval
|
The optional time interval
during which the trigger is valid (i.e., during which the declared actions
will be processed).
|
|
target_filter
|
no
|
event filter
|
The optional filter used to
locate the attribute to monitor for the trigger’s defined condition. This
filter helps locate the TOSCA entity (i.e., node or relationship) or further
a specific capability of that entity that contains the attribute to monitor.
|
|
condition
|
no
|
condition
clause definition
|
The optional condition which
contains a condition clause definition specifying one or multiple attribute
constraint that can be monitored. Note: this is optional since sometimes the
event occurrence itself is enough to trigger the action.
|
|
action
|
yes
|
list of activity
definition
|
The list of sequential activities
to be performed when the event is triggered
and the condition is met (i.e. evaluates to true).
|
3.6.22.2 Additional keynames for the extended condition notation
|
Keyname
|
Required
|
Type
|
Description
|
|
constraint
|
no
|
condition
clause definition
|
The optional condition which
contains a condition clause definition specifying one or multiple attribute
constraint that can be monitored. Note: this is optional since sometimes the
event occurrence itself is enough to trigger the action.
|
|
period
|
no
|
scalar-unit.time
|
The optional period to use to
evaluate for the condition.
|
|
evaluations
|
no
|
integer
|
The optional number of
evaluations that must be performed over the period to assert the condition
exists.
|
|
method
|
no
|
string
|
The optional statistical method
name to use to perform the evaluation of the condition.
|
3.6.22.3 Grammar
Trigger definitions have the following grammars:
3.6.22.3.1 Short notation
In the above grammars, the pseudo values that appear
in angle brackets have the following meaning:
·
trigger_name: represents
the required symbolic name of the trigger as a string.
·
trigger_description:
represents the optional description
string for the corresponding trigger_name.
·
event_name: represents
the required name of an event associated with an interface notification on the identified
resource (node).
·
time_interval_for_trigger: represents the optional time interval that
the trigger is valid for.
·
event_filter_definition: represents
the optional filter to use to locate the resource (node) or capability
attribute to monitor.
·
condition_clause_definition: represents
one or multiple attribute constraint that can be monitored.and that would be
used to test for a specific condition on the monitored resource.
·
list_of_activity_definition:
represents the list of activities that are performed if the event and
(optionally) condition are met. The activity definitions are the same as the
ones used in a workflow step. One could regard these activities as an anonymous
workflow that is invoked by this trigger and is applied to the target(s) of this
trigger’s policy.
An activity defines an operation to be performed in a TOSCA
workflow step or in an action body of a policy trigger.
Activity definitions can be of the following types:
·
Delegate workflow activity definition
o
Defines the name of the delegate workflow and optional input assignments.
This activity requires the target to be provided by the orchestrator (no-op
node or relationship).
·
Set state activity definition
o
Sets the state of a node.
·
Call operation activity definition
o
Calls an operation defined on a TOSCA interface of a node,
relationship or group. The operation name uses the
<interface_name>.<operation_name> notation. Optionally, assignments
for the operation inputs can also be provided. If provided, they will override
for this operation call the operation inputs assignment in the node template.
·
Inline workflow activity definition
Inline another workflow defined in the
topology (to allow reusability). The definition includes the name of a workflow
to be inlined and optional workflow input assignments.
3.6.23.1 Delegate workflow activity definition
3.6.23.1.1 Keynames
The following is a list of recognized keynames for a
delegate activity definition.
|
Keyname
|
Required
|
Type
|
Description
|
|
delegate
|
yes
|
string or empty
(see grammar below)
|
Defines the name of the
delegate workflow and optional input assignments.
This activity requires the target to be provided by the
orchestrator (no-op node or relationship).
|
|
workflow
|
no
|
string
|
The name of the delegate workflow. Required in the extended
notation.
|
|
inputs
|
no
|
map of
parameter assignments
|
The optional map of input parameter assignments for the delegate
workflow.
|
3.6.23.1.2 Grammar
A delegate activity definition has the following grammar.
The short notation can be used if no input assignments are provided.
3.6.23.1.2.1 Short
notation
3.6.23.1.2.2 Extended
notation
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
- delegate_workflow_name:
represents the name of the workflow of the node provided by the TOSCA
orchestrator
- parameter_assignments:
represents the optional map of property assignments for passing parameters
as inputs to this workflow delegation.
3.6.23.2 Set state activity definition
Sets the state of the target node.
3.6.23.2.1 Keynames
The following is a list of recognized keynames for a set
state activity definition.
|
Keyname
|
Required
|
Type
|
Description
|
|
set_state
|
yes
|
string
|
Value of the node state.
|
3.6.23.2.2 Grammar
A set state activity definition has the following grammar.
|
- set_state:
<new_node_state>
|
In the above
grammar, the pseudo values that appear in angle brackets have the following
meaning:
·
new_node_state: represents the state that will be affected to the
node once the activity is performed.
3.6.23.3 Call operation activity definition
This activity is used to call an operation on the target
node. Operation input assignments can be optionally provided.
3.6.23.3.1 Keynames
The following is a list of recognized keynames for a call operation
activity definition.
|
Keyname
|
Required
|
Type
|
Description
|
|
call_operation
|
yes
|
string or empty
(see grammar below)
|
Defines the opration call. The
operation name uses the <interface_name>.<operation_name>
notation.
Optionally, assignments for the operation inputs can also be
provided. If provided, they will override for this operation call the
operation inputs assignment in the node template.
|
|
operation
|
no
|
string
|
The name of the operation to call, using the
<interface_name>.<operation_name> notation.
Required in the extended notation.
|
|
inputs
|
no
|
map of
parameter assignments
|
The optional map of input parameter assignments for the called
operation. Any provided input assignments will override the operation input
assignment in the target node template for this operation call.
|
3.6.23.3.2 Grammar
A call operation activity definition has the following
grammar. The short notation can be used if no input assignments are provided.
3.6.23.3.2.1 Short
notation
|
- call_operation:
<operation_name>
|
3.6.23.3.2.2 Extended
notation
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
operation_name: represents the name of the operation that will be
called during the workflow execution. The notation used is <interface_sub_name>.<operation_sub_name>,
where interface_sub_name is the interface name and the operation_sub_name is the name of the operation whitin this interface.
·
parameter_assignments:
represents the optional map of property assignments for passing parameters as
inputs to this workflow delegation.
3.6.23.4 Inline workflow activity definition
This activity is used to inline a workflow in the activities
sequence. The definition includes the name of the inlined workflow and optional
input assignments.
3.6.23.4.1 Keynames
The following is a list of recognized keynames for an inline
workflow activity definition.
|
Keyname
|
Required
|
Type
|
Description
|
|
inline
|
yes
|
string or empty
(see grammar below)
|
The definition includes the name of a workflow to be inlined and
optional workflow input assignments.
|
|
workflow
|
no
|
string
|
The name of the inlined workflow. Required in the extended
notation.
|
|
inputs
|
no
|
map of
parameter assignments
|
The optional map of input parameter assignments for the inlined
workflow.
|
3.6.23.4.2 Grammar
An inline workflow activity definition has the following
grammar. The short notation can be used if no input assignments are provided.
3.6.23.4.2.1 Short
notation
|
- inline:
<inlined_workflow_name>
|
3.6.23.4.2.2 Extended
notation
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
inlined_workflow_name: represents the name of the workflow to inline.
·
parameter_assignments:
represents the optional map of property assignments for passing parameters as
inputs to this workflow delegation.
3.6.23.5 Example
The following represents a list of activity
definitions (using the short notation):
|
- delegate: deploy
-
set_state: started
-
call_operation: tosca.interfaces.node.lifecycle.Standard.start
-
inline: my_workflow
|
A workflow assertion is used to specify a single condition
on a workflow filter definition. The assertion allows to assert the value of an
attribute based on TOSCA constraints.
3.6.24.1 Keynames
The TOSCA workflow assertion definition has no
keynames.
3.6.24.2 Grammar
Workflow assertion definitions have the following
grammar:
|
<attribute_name>:
<list_of_constraint_clauses>
|
In the above grammars, the
pseudo values that appear in angle brackets have the following meaning:
·
attribute_name: represents the name of an attribute
defined on the assertion context entity (node instance, relationship instance,
group instance) and from which value will be evaluated against the defined
constraint clauses.
·
list_of_constraint_clauses: represents the list of
constraint clauses that will be used to validate the attribute assertion.
3.6.24.3 Example
Following represents a workflow assertion with a
single equals constraint:
|
my_attribute: [{equal : my_value}]
|
Following represents a
workflow assertion with mutliple constraints:
|
my_attribute:
-
min_length: 8
-
max_length : 10
|
3.6.25 Condition
clause definition
A workflow condition clause definition is used to specify a
condition that can be used within a workflow precondition or workflow filter.
3.6.25.1 Keynames
The following is the list of recognized keynames for
a TOSCA workflow condition definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
and
|
no
|
list of condition clause definition
|
An and clause allows to define sub-filter clause definitions
that must all be evaluated truly so the and clause is considered as true.
|
|
or
|
no
|
list of condition clause definition
|
An or clause allows to define sub-filter clause definitions
where one of them must all be evaluated truly so the or clause is considered
as true.
|
|
not
|
no
|
list of condition clause definition
|
A not clause allows to
define sub-filter clause definitions where one or more of them must be
evaluated as false.
|
|
assert
|
no
|
deprecated list of assertion definition
|
An assert clause defines
a list of filter assertions that must be evaluated on entity attributes. Assert acts as an and clause, i.e. every defined filter assertion must be true so the
assertion is considered as true.Because assert and and are
logically identical, the assert keyname has been deprecated.
|
Note : It is allowed to add direct
assertion definitions directly to the condition clause definition without using
any of the supported keynames. . In that case, an and clause is
performed for all direct assertion definition.
3.6.25.2 Grammar
Condition clause definitions have the following grammars:
3.6.25.2.1 And clause
In the above grammars, the
pseudo values that appear in angle brackets have the following meaning:
·
list_of_condition_clause_definition:
represents the list of condition clauses. All condition clauses MUST be
asserted to true so that the and clause is asserted to true.
3.6.25.2.2 Or clause
|
or:
<list_of_condition_clause_definition>
|
In the above grammars, the
pseudo values that appear in angle brackets have the following meaning:
·
list_of_condition_clause_definition:
represents the list of condition clauses. One of the condition clause have to
be asserted to true so that the or clause is asserted to true.
3.6.25.2.3 Not clause
|
not:
<list_of_condition_clause_definition>
|
In the above
grammars, the pseudo values that appear in angle brackets have the following
meaning:
·
list_of_condition_clause_definition:
represents the list of condition clauses. One of the condition clause have to
be asserted to false so that the not clause is asserted to true.
3.6.25.3 Direct assertion definition
|
<attribute_name>:
<list_of_constraint_clauses>
|
In the above grammars, the
pseudo values that appear in angle brackets have the following meaning:
·
attribute_name: represents the name of an attribute
defined on the assertion context entity (node instance, relationship instance,
group instance) and from which value will be evaluated against the defined
constraint clauses.
·
list_of_constraint_clauses: represents the list of constraint clauses that will be used to validate
the attribute assertion.
3.6.25.4 Additional Requirement
·
Keynames are mutually exclusive, i.e. a filter definition can
define only one of and, or, or not keyname.
3.6.25.5 Notes
·
The TOSCA processor SHOULD perform assertion in the order of the
list for every defined condition clause or direct assertion definition.
3.6.25.6 Example
Following represents a workflow condition clause
with a single direct assertion definition:
|
condition:
-
my_attribute: [{equal: my_value}]
|
Following represents a
workflow condition clause with single equals constraints on two
different attributes.
|
condition:
-
my_attribute: [{equal: my_value}]
-
my_other_attribute: [{equal: my_other_value}]
|
Note that these two direct
assertion constraints are logically and-ed. This means that the
following is logically identical to the previous example:
|
condition:
- and:
-
my_attribute: [{equal: my_value}]
-
my_other_attribute: [{equal: my_other_value}]
|
Following represents a workflow condition clause
with a or constraint on two different assertions:
|
condition:
- or:
-
my_attribute: [{equal: my_value}]
-
my_other_attribute: [{equal: my_other_value}]
|
The following shows
an example of the not operator. The condition yields TRUE when the
attribute my_attribute1 takes any value other than value1:
|
condition:
- not:
-
my_attribute1: [{equal: value1}]}
|
The following condition
yields TRUE when none of the attributes my_attribute1 and my_attribute2 is
equal to value1.
|
condition:
- not:
-
and:
-
my_attribute1: [{equal: value1}]
-
my_attribute2: [{equal: value1}]
|
The following condition is
a functional equivalent of the previous example:
|
condition:
- or:
-
not:
-
my_attribute1: [{equal: value1}]
-
not:
-
my_attribute2: [{equal: value1}]
|
Following represents
multiple levels of condition clauses with direct assertion definitions to build
the following logic: use http on port 80 or https on port 431:
|
condition:
- or:
- and:
-
protocol: { equal: http }
-
port: { equal: 80 }
- and:
-
protocol: { equal: https }
-
port: { equal: 431 }
|
A workflow condition can be used as a filter or precondition
to check if a workflow can be processed or not based on the state of the
instances of a TOSCA topology deployment. When not met, the workflow will not
be triggered.
3.6.26.1 Keynames
The following is the list of recognized keynames for
a TOSCA workflow condition definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
target
|
yes
|
string
|
The target of the precondition
(this can be a node template name, a group name)
|
|
target_relationship
|
no
|
string
|
The optional name of a
requirement of the target in case the precondition has to be processed on a
relationship rather than a node or group. Note that this is applicable only
if the target is a node.
|
|
condition
|
no
|
list of condition clause definitions
|
A list of workflow condition
clause definitions. Assertion between elements of the condition are evaluated
as an AND condition.
|
3.6.26.2 Grammar
Workflow precondition definitions have the following
grammars:
|
- target:
<target_name>
target_relationship: <target_requirement_name>
condition:
<list_of_condition_clause_definition>
|
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
target_name: represents the name
of a node template or group in the topology.
·
target_requirement_name:
represents the name of a requirement of the node template (in case target_name
refers to a node template.
·
list_of_condition_clause_definition:
represents the list of condition clauses to be evaluated. The value of the
resulting condition is evaluated as an AND clause between the different
elements.
A workflow step allows to define one or multiple sequenced
activities in a workflow and how they are connected to other steps in the
workflow. They are the building blocks of a declarative workflow.
3.6.27.1 Keynames
The following is the list of recognized keynames for
a TOSCA workflow step definition:
|
Keyname
|
Required
|
Type
|
Description
|
|
target
|
yes
|
string
|
The target of the step (this can
be a node template name, a group name)
|
|
target_relationship
|
no
|
string
|
The optional name of a
requirement of the target in case the step refers to a relationship rather
than a node or group. Note that this is applicable only if the target is a
node.
|
|
operation_host
|
no
|
string
|
The node on which operations
should be executed (for TOSCA call_operation activities).
This element is required only
for relationships and groups target.
If target is a relationships
operation_host is required and valid_values are SOURCE or TARGET – referring
to the relationship source or target node.
If target is a group
operation_host is optional.
If not specified the operation
will be triggered on every node of the group.
If specified the valid_value is
a node_type or the name of a node template.
|
|
filter
|
no
|
list of constraint clauses
|
Filter is a map of attribute
name, list of constraint clause that allows to provide a filtering logic.
|
|
activities
|
yes
|
list of activity definition
|
The list of sequential
activities to be performed in this step.
|
|
on_success
|
no
|
list of string
|
The optional list of step names
to be performed after this one has been completed with success (all
activities has been correctly processed).
|
|
on_failure
|
no
|
list of string
|
The optional list of step names
to be called after this one in case one of the step activity failed.
|
3.6.27.2 Grammar
Workflow step definitions have the following
grammars:
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
target_name: represents the name
of a node template or group in the topology.
·
target_requirement_name:
represents the name of a requirement of the node template (in case target_name
refers to a node template.
·
operation_host: the node
on which the operation should be executed
·
list_of_condition_clause_definition: represents a list of condition clause definition.
·
list_of_activity_definition: represents a list of activity definition
·
target_step_name: represents the name of another step of the
workflow.
An Entity Type is the common, base, polymorphic schema type
which is extended by TOSCA base entity type schemas (e.g., Node Type,
Relationship Type, Artifact Type, etc.) and serves to define once all the
commonly shared keynames and their types. This is a “meta” type which is
abstract and not directly instantiatable.
3.7.1.1 Keynames
The following is the list of recognized keynames for
a TOSCA Entity Type definition:
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
derived_from
|
no
|
string
|
‘None’
is the only allowed value
|
An optional parent Entity Type
name the Entity Type derives from.
|
|
version
|
no
|
version
|
N/A
|
An optional version for the Entity
Type definition.
|
|
metadata
|
no
|
map
of string
|
N/A
|
Defines a section used to
declare additional metadata information.
|
|
description
|
no
|
description
|
N/A
|
An optional description for the
Entity Type.
|
3.7.1.2 Grammar
Entity Types have following grammar:
|
<entity_keyname>:
# The
only allowed value is ‘None’
derived_from: None
version: <version_number>
metadata:
<metadata_map>
description: <interface_description>
|
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
version_number:
represents the optional TOSCA version number
for the entity.
·
entity_description:
represents the optional description
string for the entity.
·
metadata_map: represents
the optional map of string.
3.7.1.3 Additional Requirements
·
The TOSCA Entity Type SHALL be the common base type used to
derive all other top-level base TOSCA Types.
·
The TOSCA Entity Type SHALL NOT be used to derive or create new
base types apart from those defined in this specification or a profile of this
specification.
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.
3.7.2.1 Keynames
The following is the list of recognized keynames for
a TOSCA capability definition:
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
type
|
yes
|
string
|
N/A
|
The required name of the
Capability Type the capability definition is based upon.
|
|
description
|
no
|
description
|
N/A
|
The optional description of the
Capability definition.
|
|
properties
|
no
|
map of
property definitions
|
N/A
|
An optional map of property
definitions for the Capability definition.
|
|
attributes
|
no
|
map of
attribute
definitions
|
N/A
|
An optional map of attribute
definitions for the Capability definition.
|
|
valid_source_types
|
no
|
string[]
|
N/A
|
An optional list of one or more valid
names of Node Types that are supported as valid sources of any relationship
established to the declared Capability Type.
|
|
occurrences
|
no
|
range of integer
|
implied default of [1,UNBOUNDED]
|
The
optional minimum and maximum occurrences for the capability. By default, an exported Capability should allow at least
one relationship to be formed with it with a maximum of UNBOUNDED
relationships.
Note: the keyword UNBOUNDED is also
supported to represent any positive integer.
|
3.7.2.2 Grammar
Capability definitions have one of the following
grammars:
3.7.2.2.1 Short notation
The following single-line grammar may be used when
only the capability definition name needs to be declared, without further
refinement of the capability type definitions:
3.7.2.2.2 Extended notation
The following multi-line grammar may be used when
additional information on the capability definition is needed:
In the above grammars, the
pseudo values that appear in angle brackets have the following meaning:
·
capability_definition_name:
represents the symbolic name of the capability as a string.
·
capability_type:
represents the required name of a capability
type the capability definition is based upon.
·
capability_description:
represents the optional description of
the capability definition.
·
property_definitions:
represents the optional map of property
definitions for the capability definition.
·
attribute_definitions:
represents the optional map of attribute
definitions for the capability definition.
·
node_type_names:
represents the optional list of one or more names of Node Types that the Capability definition
supports as valid sources for a successful relationship to be established to
itself.
·
Range_of_occurrences:
represents he optional minimum and maximum occurrences for the capability.
3.7.2.3 Examples
The following examples show capability definitions
in both simple and full forms:
3.7.2.3.1 Simple notation example
|
# Simple notation, no properties defined or augmented
some_capability:
mytypes.mycapabilities.MyCapabilityTypeName
|
|
# Full notation, augmenting
properties of the referenced capability type
some_capability:
type:
mytypes.mycapabilities.MyCapabilityTypeName
properties:
limit:
type: integer
default: 100
|
3.7.2.4 Additional requirements
·
Any Node Type (names) provides as values for the valid_source_types keyname SHALL be
type-compatible (i.e., derived from the same parent Node Type) with any Node
Types defined using the same keyname in the parent Capability Type.
·
Capability symbolic names SHALL be unique; it is an error if a
capability name is found to occur more than once.
3.7.2.5 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.
3.7.3 Requirement
definition
The Requirement definition describes a named requirement
(dependencies) of a TOSCA Node Type or Node template which needs to be
fulfilled by a matching Capability definition declared by another TOSCA
modelable entity. The requirement definition may itself include the specific
name of the fulfilling entity (explicitly) or provide an abstract type, along
with additional filtering characteristics, that a TOSCA orchestrator can use to
fulfill the capability at runtime (implicitly).
3.7.3.1 Keynames
The following is the list of recognized keynames for
a TOSCA requirement definition:
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
capability
|
yes
|
string
|
N/A
|
The required reserved keyname
used that can be used to provide the name of a valid Capability Type that can fulfill the requirement.
|
|
node
|
no
|
string
|
N/A
|
The optional reserved keyname
used to provide the name of a valid Node
Type that contains the capability definition
that can be used to fulfill the requirement.
|
|
relationship
|
no
|
string
|
N/A
|
The optional reserved keyname
used to provide the name of a valid Relationship Type to construct when fulfilling the requirement.
|
|
occurrences
|
no
|
range of integer
|
implied default of [1,1]
|
The optional minimum and maximum
occurrences for the requirement.
Note: the keyword UNBOUNDED is also
supported to represent any positive integer.
|
3.7.3.1.1 Additional Keynames for multi-line relationship grammar
The Requirement definition contains the Relationship
Type information needed by TOSCA Orchestrators to construct relationships to
other TOSCA nodes with matching capabilities; however, it is sometimes
recognized that additional properties may need to be passed to the relationship
(perhaps for configuration). In these cases, additional grammar is provided so
that the Node Type may declare additional Property definitions to be used as
inputs to the Relationship Type’s declared interfaces (or specific operations
of those interfaces).
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
type
|
yes
|
string
|
N/A
|
The optional reserved keyname
used to provide the name of the Relationship Type for the requirement
definition’s relationship keyname.
|
|
interfaces
|
no
|
map of interface definitions
|
N/A
|
The optional reserved keyname
used to reference declared (named) interface definitions of the corresponding
Relationship Type in order to declare additional Property definitions for
these interfaces or operations of these interfaces.
|
3.7.3.2 Grammar
Requirement definitions have one of the following
grammars:
3.7.3.2.1 Simple grammar (Capability Type only)
3.7.3.2.2 Extended grammar (with Node and Relationship Types)
3.7.3.2.3 Extended grammar for declaring Property Definitions on the
relationship’s Interfaces
The following additional multi-line grammar is
provided for the relationship keyname in order to declare new Property
definitions for inputs of known Interface definitions of the declared
Relationship Type.
In the above grammars, the
pseudo values that appear in angle brackets have the following meaning:
·
requirement_definition_name: represents
the required symbolic name of the requirement definition as a string.
·
capability_type_name:
represents the required name of a Capability type that can be used to fulfill
the requirement.
·
node_type_name: represents
the optional name of a TOSCA Node Type that contains the Capability Type
definition the requirement can be fulfilled by.
·
relationship_type_name:
represents the optional name of a Relationship
Type to be used to construct a relationship between this requirement
definition (i.e., in the source node) to a matching capability definition (in a
target node).
·
min_occurrences, max_occurrences:
represents the optional minimum and maximum occurrences of the requirement
(i.e., its cardinality).
·
interface_definitions:
represents one or more already declared interface definitions in the
Relationship Type (as declared on the type
keyname) allowing for the declaration of new Property definition for these interfaces
or for specific Operation definitions of these interfaces.
3.7.3.3 Additional Requirements
·
Requirement symbolic names SHALL be unique; it is an error if a
requirement name is found to occur more than once.
·
If the occurrences
keyname is not present, then the occurrence of the requirement SHALL be
one and only one; that is a default declaration as follows would be assumed:
o occurrences: [1,1]
3.7.3.4 Notes
·
This element directly maps to the RequirementsDefinition of the Node Type
entity as defined in the TOSCA v1.0 specification.
·
The requirement symbolic name is used for identification of the
requirement definition only and not relied upon for establishing any
relationships in the topology.
3.7.3.5 Requirement Type definition is a tuple
A requirement definition allows type designers to
govern which types are allowed (valid) for fulfillment using three levels of
specificity with only the Capability Type being required.
1. Node Type
(optional)
2. Relationship
Type (optional)
3. Capability
Type (required)
The first level allows selection, as shown in both
the simple or complex grammar, simply providing the node’s type using the node keyname. The second level allows
specification of the relationship type to use when connecting the requirement
to the capability using the relationship
keyname. Finally, the specific named capability type on the target node is
provided using the capability keyname.
3.7.3.5.1 Property filter
In addition to the node, relationship and capability types,
a filter, with the keyname node_filter,
may be provided to constrain the allowed set of potential target nodes based
upon their properties and their capabilities’ properties. This allows TOSCA
orchestrators to help find the “best fit” when selecting among multiple
potential target nodes for the expressed requirements.
An Artifact Type is a reusable entity that defines the type
of one or more files that are used to define implementation or deployment
artifacts that are referenced by nodes or relationships on their operations.
3.7.4.1 Keynames
The Artifact Type is a TOSCA Entity and has the
common keynames listed in section 3.7.1 TOSCA Entity Schema.
In addition, the Artifact Type has the following
recognized keynames:
|
Keyname
|
Required
|
Type
|
Constraints
|
Description
|
|
mime_type
|
no
|
string
|
None
|
The required mime type property
for the Artifact Type.
|
|
file_ext
|
no
|
string[]
|
None
|
The required file extension
property for the Artifact Type.
|
|
properties
|
no
|
map of
property definitions
|
No
|
Anoptional map of property
definitions for the Artifact Type.
|
3.7.4.2 Grammar
Artifact Types have following grammar:
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
artifact_type_name:
represents the name of the Artifact Type being declared as a string.
·
parent_artifact_type_name:
represents the name of the Artifact Type this Artifact Type
definition derives from (i.e., its “parent” type).
·
version_number: represents
the optional TOSCA version number for the
Artifact Type.
·
artifact_description:
represents the optional description
string for the Artifact Type.
·
mime_type_string:
represents the optional Multipurpose Internet Mail Extensions (MIME) standard
string value that describes the file contents for this type of Artifact Type as
a string.
·
file_extensions:
represents the optional list of one or more recognized file extensions for this
type of artifact type as strings.
·
property_definitions:
represents the optional map of property
definitions for the artifact type.
3.7.4.3 Examples
|
my_artifact_type:
description: Java Archive artifact type
derived_from: tosca.artifact.Root
mime_type: application/java-archive
file_ext: [ jar ]
properties:
id:
description: Identifier of the jar
type: string
required: true
creator:
description: Vendor of the java implementation on which the jar is based
type: string
required: false
|
3.7.4.4 Additional Requirements
·
The ‘mime_type’ keyname is meant to have values that are Apache
mime types such as those defined here: http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
3.7.4.5 Notes
Information about artifacts can be broadly classified in two
categories that serve different purposes :
1. Selection
of artifact processor – This category includes informational elements such as
artifact version, checksum, checksum algorithm etc. and s used by TOSCA
Orchestrator to select the correct artifact processor for the artifact. These
informational elements are captured in TOSCA as keywords for the artifact.
2. Properties
processed by artifact processor - Some properties are not processed by the Orchestrator,
but passed on to the artifact processor to assist with proper processing of the
artifact. These informational elements are described through artifact
properties.
·
.
An Interface Type is a reusable entity that
describes a set of operations that can be used to interact with or manage a
node or relationship in a TOSCA topology.
3.7.5.1 Keynames
The Interface Type is a TOSCA Entity and has the
common keynames listed in section 3.7.1 TOSCA Entity Schema.
In addition, the Interface Type has the following
recognized keynames:
|
Keyname
|
Required
|
Type
|
Description
|
|
inputs
|
no
|
map of
property definitions
|
The optional map of input
parameter definitions.
|
|
operations
|
no
|
map of operation definitions
|
The optional map of operations
defined for this interface.
|
|
notifications
|
no
|
map of notification definitions
|
The optional map of
notifications defined for this interface.
|
3.7.5.2 Grammar
Interface Types have following grammar:
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
interface_type_name:
represents the required name of the interface as a string.
·
parent_interface_type_name:
represents the name of the Interface Type
this Interface Type definition derives from (i.e., its “parent” type).
·
version_number:
represents the optional TOSCA version number
for the Interface Type.
·
interface_description:
represents the optional description
string for the Interface Type.
·
property_definitions:
represents the optional map of property
definitions (i.e., parameters) which the TOSCA orchestrator would make available
(i.e., or pass) to all implementation artifacts for operations declared on the
interface during their execution.
·
operation_definitions:
represents the required map of one or more operation definitions.
·
notification_definitions:
represents the required name of one or more notification definitions.
3.7.5.3 Example
The following example shows a custom interface used
to define multiple configure operations.
|
mycompany.mytypes.myinterfaces.MyConfigure:
derived_from: tosca.interfaces.relationship.Root
description: My custom configure Interface Type
inputs:
mode:
type: string
operations:
pre_configure_service:
description:
pre-configure operation for my service
post_configure_service:
description:
post-configure operation for my service
|
3.7.5.4 Additional Requirements
·
Interface Types MUST NOT include any implementations for
defined operations or notifications; that is, the implementation keyname is
invalid in this context.
·
The inputs keyname is
reserved and SHALL NOT be used for an operation name.
3.7.5.5 Notes
Starting with Version 1.3 of this specification, interface
type definition grammar was changed to support notifications as well as
operations. As a result, operations must now be specified under the
newly-introduced operations keyname and
the notifications under the new notifications
keyname. For backward compatibility if neither the operations or notifications
are specified then we assume the symbolic names in the interface definition to
mean operations, but this use is deprecated. Operations and notifications names
should not overlap.
A Data Type definition defines the schema for new named
datatypes in TOSCA.
3.7.6.1 Keynames
The Data Type is a TOSCA Entity and has the common
keynames listed in section 3.7.1 TOSCA Entity Schema.
In addition, the Data Type has the following
recognized keynames:
|
Keyname
|
Required
|
Type
|
Description
|
|
constraints
|
no
|
list of
constraint clauses
|
The
optional list of sequenced constraint clauses for the Data
Type.
|
|
properties
|
no
|
map of
property definitions
|
The
optional map property definitions that comprise the schema for a complex Data
Type in TOSCA.
|
|
key_schema
|
no
|
schema_definition
|
For
data types that derive from the TOSCA map data type, the optional schema
definition for the keys used to identify entries in properties of this data
type.
|
|
entry_schema
|
no
|
schema_definition
|
For
data types that derive from the TOSCA map or list data types, the optional
schema definition for the entries in properties of this data type.
|
3.7.6.2 Grammar
Data Types have the following grammar:
In the above grammar, the
pseudo values that appear in angle brackets have the following meaning:
·
data_type_name:
represents the required symbolic name of the Data Type as a string.
·
version_number:
represents the optional TOSCA version number
for the Data Type.
·
datatype_description: represents
the optional description for the Data
Type.
·
existing_type_name: represents
the optional name of a valid TOSCA type this new Data Type would derive from.
·
type_constraints:
represents the optional list of one or more type-compatible constraint clauses that restrict
the Data Type.
·
property_definitions:
represents the optional map of one or more property
definitions that provide the schema for the Data Type.
·
key_schema_definition: if
the data_type derives from the TOSCA map type (i.e existing_type_name is a map
or derives from a map), represents the optional schema definition for they keys
used to identify entries properties of this type..
·
entry_schema_definition: if
the data_type derives from the TOSCA map or list types (i.e. existing_type name
is a map or list or derives from a map or list), represents the optional schema
definition for the entries in properties of this type.
3.7.6.3 Additional Requirements
·
A valid datatype definition MUST have either a valid derived_from declaration or at least one
valid property definition.
·
Any constraint clauses SHALL
be type-compatible with the type declared by the derived_from keyname.
·
If a properties keyname
is provided, it SHALL contain one or more valid property definitions.
3.7.6.4 Examples
The following example represents a Data Type definition based
upon an existing string type:
3.7.6.4.1 Defining a complex datatype
