The Second Five Minutes: Key Concepts

Templates and Types

This section contains a few TOSCA and AMP key terms that should make it easy to design and deploy TOSCA blueprints. All TOSCA concepts are described in the official TOSCA Oasis Reference Documentation.

A TOSCA Service Template (YAML) document contains element definitions of building blocks for cloud application, or complete models of cloud applications. It is also referred in this documentation as a TOSCA blueprint and it contains types that need to be added in the AMP catalog and a TOSCA topology template designed using those types and/or types existing in the catalog.

Service Template

Notes:

Currently in AMP: 1_3.
This description field is optional. If the service template contains a topology_template description this causes a conflict error.
namespaces is currently not supported in AMP.
template_name becomes the unique identifier for the topology_template of this service template when added to the catalog and the application name at deploy time.
dsl_definitions is not supported because of a conflict with YAML anchor syntax. imports are not supported because they don’t make sense in AMP, since AMP stores all types in the catalog.
capability_types and group_types are currently not supported in AMP. policy_types support is limited.
topology_template represents the deployable part of a service template .

A Node Type is a reusable entity that defines the type of one or more Node Templates.

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. An interface type declares a set of operations that are to be executed during the node template lifecycle.

A Requirement Type is a reusable entity that describes a kind of requirement that a Node Type can declare to expose.

A Capability Type is a reusable entity that describes a kind of capability that a Node Type can declare to expose.

A Data Type definition defines the schema for new named datatypes in TOSCA.

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.

A Policy Type defines a type of requirement that affects or governs an application or service’s topology at some stage of its lifecycle, but is not explicitly part of the topology itself (i.e., it does not prevent the application or service from being deployed or run if it did not exist). Support for custom policy types is currently limited in AMP, but policy types present in the catalog can be used and attached to node templates or groups of node templates and (topology templates too) using groups.

A Group Type defines logical grouping types for nodes, typically for different management purposes. Conceptually, group definitions allow the creation of logical “membership” relationships to nodes in a service template that are not a part of the application’s explicit requirement dependencies in the topology template (i.e. those required to actually get the application deployed and running). Instead, such logical membership allows for the introduction of things such as group management and uniform application of policies (i.e., requirements that are also not bound to the application itself) to the group’s members. In AMP, groups are also used to attach AMP components such as enrichers, policies, locations and initializers.

A TOSCA topology template is a reusable entity that defines a deployable blueprint. In AMP it can also be used as a type of one or more Node Templates.

Topology Template

This description field is optional. If the service template contains a description this causes a conflict error.
inputs represents an optional map of input values for this topology template.
node_templates groups all node templates of this topology template.
relationship_templates groups all relationship templates of this topology template. This allows for a more simple way to declare node templates, since the shorthand notation can be used, which means relationships between node templates are configured using relationship templates names.
groups represents logical grouping of node templates.
policies groups all policies applied to nodes in this topology template. Although supported, options are pretty limited and the recommendation is to use groups.
outputs represents the optional map of output parameters (i.e., as property definitions) for the Topology Template.
workflows groups all workflows applied to nodes in this topology template. Currently not supported in AMP.

A Node Template specifies the occurrence of a manageable software component as part of an application’s topology model which is defined in a TOSCA Service Template.

A Relationship Template specifies the occurrence of a manageable relationship between node templates as part of an application’s topology model that is defined in a TOSCA Service Template. A Relationship template is an instance of a specified Relationship Type and can provide customized properties, constraints or operations which override the defaults provided by its Relationship Type and its implementations.

A group definition defines a logical grouping of node templates, typically for management purposes, but is separate from the application’s topology template.

A workflow definition defines an imperative workflow that is associated with a TOSCA topology. A workflow definition can either include the steps that make up the workflow, or it can refer to an artifact that expresses the workflow using an external workflow language. Currently not supported in AMP.

Capabilities, Requirements, and Relationships

Capabilities, Requirements, and Relationships are the most powerful concepts in TOSCA. Basic support for all of them is provided by AMP, and further customized extensions is expected to be provided in the future, based on customers needs.

Capabilities

The TOSCA official specification defines a Capability Type as a reusable entity that describes a kind of capability that a Node Type can declare to expose. Requirements (implicit or explicit) that are declared as part of one node can be matched to (i.e., fulfilled by) the Capabilities declared by another node.

In AMP the following capabilities are supported:

host used to configure host container properties like memory and disk size, as shown in the following example:

node_templates:
vm_node:
  type: tosca.nodes.Compute
  capabilities:
    host:
      properties:
        mem_size: 16 gb
        disk_size: 1tb

cloudsoft used to configure node behaviour like ports to be exposed and customize behaviour at delete time, as shown in the following example:

node_templates:
vm_node:
  type: tosca.nodes.Compute
  attributes:
    app.port: 8020
  capabilities:
    cloudsoft:
      properties:
        required.ports: { get_attribute: [ SELF, app.port ] }
      brooklyn.tosca.capabilities.StandardLifecycleBehavior: 
        properties:
          delete_waits_on_dependents_timeout: 1m

vmware used to configure various node properties available only when deployment is done on a VMware vSphere environment.

node_templates:
  vm_node:
    type: tosca.nodes.Compute
    capabilities:
      vmware:
        properties:
          customIpAddress: 192.168.42.120
          customHostname: host
          customSubnetMask: 255.255.255.0
          osFamilyOverride : LINUX

Relationships

The TOSCA official specification defines a Relationship Type is a reusable entity that defines the type of one or more relationships between Node Types or Node Templates. AMP supports declaring your own relationship types as long as they derive from the basic tosca.interfaces.node.lifecycle.Standard, tosca.interfaces.relationship.Configure or any other interface types present in the catalog. The following YAML example shows the definition of an interface type describing a database requirement.

relationship_types:
  io.cloudsoft.depends-on-db:
    derived_from: tosca.relationships.DependsOn
    metadata:
      icon: classpath://icons/tosca-relationship.png
    interfaces:
      Configure:
        pre_configure_source:
          inputs:
            DB_URL: { get_attribute: [ TARGET, db_url ] }
            DB_DRIVER: { get_attribute: [ TARGET, db_driver ] }
          implementation: classpath://scripts/configure_db.sh

Requirements

The TOSCA official specification defines a Requirement definition as 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).

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.

Node Type (optional) - this level allows selection, as shown in both the simple or complex grammar, simply providing the node’s type using the node keyname.
Relationship Type (optional) - this level allows specification of the relationship type to use when connecting the requirement to the capability using the relationship keyname.
Capability Type (required) - this level allows the specific named capability type on the target node is provided using the capability keyname. This is not currently supported in AMP, since there was no use case for it yet.

The following example shows a node type declared to require a database node through the io.cloudsoft.depends-on-db relationship declared in the previous example.

node_types:
  tosca-tomcat8-node:
    derived_from: tosca.nodes.WebServer
    metadata:
      icon: classpath://icons/tomcat8.png
    # other config elements omitted for brevity
    requirements:
    - needs-db:
        relationship: io.cloudsoft.depends-on-db
        node: tosca.nodes.Root