TOSCA Enhancements for Operation Outputs

TOSCA Enhancements for Operation Outputs

March 28, 2018

Introduction

TOSCA allows service template designers to define thesignatureof interface operations by specifying the set ofinputs(and their types) that need to be provided when invoking an operation. However, no equivalent support currently exists for defining the expected return values for interface operations.

We recommend that TOSCA should be extended as follows:

-Allow service template designers to define operationoutputs: named values that are expected to be returned by interface operations.

-Provide a mechanism for reflecting output values returned by node operations into attributes on nodes or relationships.

Without this functionality, there is no mechanism for a TOSCA orchestrator to obtain values for attributes specified in TOSCA node templates.

This document presents two proposals for providing this functionality.

Output Definitions and Assignments

One possible approach is to mimic the behavior of operation input definitions as best as possible:

-Add an outputs keyname to the operation definition syntax that defines a map of named outputs and their associated types. Interface definitions in node and relationship type definitions use this syntax to define the expected operation outputs.

-Introduce an intrinsic set_attribute function that can be used in output assignments in node and relationship templates to specify the attribute into which the returned output value should be stored.

Output Definitions

These proposed extensions result in the following updated operation definition grammar that is to be used in node type or relationship type definitions:

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 / list of
parameter definitions / The optional list of input property 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.
outputs / no / list of
property definitions / The optional list of outputproperty 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.

Output Assignments

The values of the operation outputs are then specified in node and relationship templates using the following operation assignment syntax:

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 / list of
property assignments / The optional list 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 / list of
outputassignments / The optional list of outputproperty assignments that reflect the output value into a node or relationship template attribute. .

The following grammar must be used for output assignments:

output_name>: <set_attribute_function

set_attribute

The set_attribute function is used to store the values returned as operation outputs into the specified node or relationship attributes. It uses the following grammar:

set_attribute: [ <SELF | SOURCE | TARGET >, <optional_capability_name>, <attribute_name>, <nested_attribute_name_or_index_1>, ..., <nested_attribute_name_or_index_or_key_n> ]

Parameters

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 listor maptypes. 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.

The service template below shows an example of the operation output syntax. The template is used to create a tenant on a cloud. The tenant node template has anattribute that stores the tenant ID. This id is returned as an output value of the create method on the tenant’s lifecycle management interface:

tosca_definitions_version: tosca_simple_yaml_1_2_0
description: Template for creating cloud tenants
node_types:
Cloud:
derived_from: tosca.nodes.Root
capabilities:
host:
type: tosca.capabilities.Container
Tenant:
derived_from: tosca.nodes.Root
properties:
name:
type: string
attributes:
tenantId:
type: integer
requirements:
- cloud:
capability: tosca.capabilities.Container
node: Cloud
interfaces:
Standard:
create:
inputs:
name:
type: string
outputs:
tenantId:
type: integer
topology_template:
node_templates:
cloud:
type: Cloud
tenant:
type: Tenant
properties:
name: { get_input: name }
requirements:
- cloud: cloud
Interfaces:
Standard:
create:
inputs:
name: { get_property: [ SELF, name ] }
outputs:
tenantId: { set_attribute: [ SELF, tenantID ] }

Output Parameters

A second approach mimics the behavior of input parameters to create an output parameter mechanism: rather than separating output assignments from output definitions, the two are combined into an output parameter definition that defines the name of the operation and then immediately couples it with a set_attribute function to specify the attribute into which the output value needs to be stored.

The following code snippet shows the same example as above but with output parameter syntax rather than separate output definitions and assignments:

tosca_definitions_version: tosca_simple_yaml_1_2_0
description: Template for creating cloud tenants
node_types:
Cloud:
derived_from: tosca.nodes.Root
capabilities:
host:
type: tosca.capabilities.Container
Tenant:
derived_from: tosca.nodes.Root
properties:
name:
type: string
attributes:
tenantId:
type: integer
requirements:
- cloud:
capability: tosca.capabilities.Container
node: Cloud
interfaces:
Standard:
create:
inputs:
name:
type: string
outputs:
tenantId: { set_attribute: [ SELF, tenantID ] }
topology_template:
node_templates:
cloud:
type: Cloud
tenant:
type: Tenant
properties:
name: { get_input: name }
requirements:
- cloud: cloud
Interfaces:
Standard:
create:
inputs:
name: { get_property: [ SELF, name ] }

Note that when output parameter syntax is used, the only valid keyname in the set_attribute function is SELF—even in the context of interfaces on relationship types—since the type of the source or target nodes of the relationship may not be uniquely defined within the context of the relationship type.

1