Type Definitions
The following TOSCA types are available to all service templates.
Contents
TOSCA 1.3
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
tosca_definitions_version: tosca_simple_yaml_1_3
description: >
The content of this file reflects TOSCA Simple Profile in YAML version
1.3. It describes the definition for TOSCA types including Node Type,
Relationship Type, Capability Type and Interfaces.
##########################################################################
# Node Type.
# A Node Type is a reusable entity that defines the type of one or more
# Node Templates.
##########################################################################
node_types:
tosca.nodes.Root:
description: >
The TOSCA root node all other TOSCA base node types derive from.
attributes:
tosca_id:
type: string
tosca_name:
type: string
state:
type: string
capabilities:
feature:
type: tosca.capabilities.Node
requirements:
- dependency:
capability: tosca.capabilities.Node
node: tosca.nodes.Root
relationship: tosca.relationships.DependsOn
occurrences: [0, UNBOUNDED]
interfaces:
Standard:
type: tosca.interfaces.node.lifecycle.Standard
tosca.nodes.Abstract.Storage:
derived_from: tosca.nodes.Root
properties:
name:
type: string
description: >
The logical name of the store (or container).
size:
type: scalar-unit.size
default: 0 MB
constraints:
- greater_or_equal: 0 MB
description: >
The requested initial storage size.
tosca.nodes.Storage.BlockStorage:
derived_from: tosca.nodes.Abstract.Storage
description: >
The TOSCA BlockStorage node currently represents a server-local block storage device (i.e., not shared)
offering evenly sized blocks of data from which raw storage volumes can be created.
properties:
name:
type: string
default: ""
volume_id:
type: string
required: false
description: ID of an existing volume (that is in the accessible scope of the requesting application).
snapshot_id:
type: string
required: false
description: Some identifier that represents an existing snapshot that should be used when creating the block storage (volume).
attributes:
volume_id:
type: string
capabilities:
attachment:
type: tosca.capabilities.Attachment
tosca.nodes.BlockStorage:
derived_from: tosca.nodes.Storage.BlockStorage
metadata:
alias: true
deprecated: true
tosca.nodes.Storage.ObjectStorage:
derived_from: tosca.nodes.Abstract.Storage
description: >
The TOSCA ObjectStorage node represents storage that provides the ability
to store data as objects (or BLOBs of data) without consideration for the
underlying filesystem or devices
properties:
maxsize:
type: scalar-unit.size
required: false
constraints:
- greater_or_equal: 0 GB
description: >
The requested maximum storage size.
capabilities:
storage_endpoint:
type: tosca.capabilities.Endpoint
tosca.nodes.ObjectStorage:
derived_from: tosca.nodes.Storage.ObjectStorage
metadata:
alias: true
deprecated: true
tosca.nodes.Abstract.Compute:
derived_from: tosca.nodes.Root
capabilities:
host:
type: tosca.capabilities.Compute
valid_source_types: []
tosca.nodes.Compute:
derived_from: tosca.nodes.Abstract.Compute
attributes:
private_address:
type: string
public_address:
type: string
networks:
type: map
entry_schema:
type: tosca.datatypes.network.NetworkInfo
ports:
type: map
entry_schema:
type: tosca.datatypes.network.PortInfo
capabilities:
host:
type: tosca.capabilities.Compute
valid_source_types: [tosca.nodes.SoftwareComponent]
binding:
type: tosca.capabilities.network.Bindable
os:
type: tosca.capabilities.OperatingSystem
scalable:
type: tosca.capabilities.Scalable
endpoint:
type: tosca.capabilities.Endpoint.Admin
requirements:
- local_storage:
capability: tosca.capabilities.Attachment
node: tosca.nodes.storage.BlockStorage
relationship: tosca.relationships.AttachesTo
occurrences: [0, UNBOUNDED]
tosca.nodes.SoftwareComponent:
derived_from: tosca.nodes.Root
properties:
# domain-specific software component version
component_version:
type: version
required: false
description: >
Software component version.
admin_credential:
type: tosca.datatypes.Credential
required: false
requirements:
- host:
capability: tosca.capabilities.Compute
node: tosca.nodes.Compute
relationship: tosca.relationships.HostedOn
occurrences: [0, UNBOUNDED] # make optional
tosca.nodes.DBMS:
derived_from: tosca.nodes.SoftwareComponent
properties:
port:
required: false
type: integer
description: >
The port the DBMS service will listen to for data and requests.
root_password:
required: false
type: string
description: >
The root password for the DBMS service.
capabilities:
host:
type: tosca.capabilities.Compute
valid_source_types: [tosca.nodes.Database]
tosca.nodes.Database:
derived_from: tosca.nodes.Root
properties:
user:
required: false
type: string
description: >
User account name for DB administration
port:
required: false
type: integer
description: >
The port the database service will use to listen for incoming data and
requests.
name:
required: false
type: string
description: >
The name of the database.
password:
required: false
type: string
description: >
The password for the DB user account
requirements:
- host:
capability: tosca.capabilities.Compute
node: tosca.nodes.DBMS
relationship: tosca.relationships.HostedOn
capabilities:
database_endpoint:
type: tosca.capabilities.Endpoint.Database
tosca.nodes.WebServer:
derived_from: tosca.nodes.SoftwareComponent
capabilities:
data_endpoint:
type: tosca.capabilities.Endpoint
admin_endpoint:
type: tosca.capabilities.Endpoint.Admin
host:
type: tosca.capabilities.Compute
valid_source_types: [tosca.nodes.WebApplication]
tosca.nodes.WebApplication:
derived_from: tosca.nodes.Root
properties:
context_root:
type: string
required: false
requirements:
- host:
capability: tosca.capabilities.Compute
node: tosca.nodes.WebServer
relationship: tosca.relationships.HostedOn
capabilities:
app_endpoint:
type: tosca.capabilities.Endpoint
tosca.nodes.network.Network:
derived_from: tosca.nodes.Root
description: >
The TOSCA Network node represents a simple, logical network service.
properties:
ip_version:
type: integer
required: false
default: 4
constraints:
- valid_values: [4, 6]
description: >
The IP version of the requested network. Valid values are 4 for ipv4
or 6 for ipv6.
cidr:
type: string
required: false
description: >
The cidr block of the requested network.
start_ip:
type: string
required: false
description: >
The IP address to be used as the start of a pool of addresses within
the full IP range derived from the cidr block.
end_ip:
type: string
required: false
description: >
The IP address to be used as the end of a pool of addresses within
the full IP range derived from the cidr block.
gateway_ip:
type: string
required: false
description: >
The gateway IP address.
network_name:
type: string
required: false
description: >
An identifier that represents an existing Network instance in the
underlying cloud infrastructure or can be used as the name of the
newly created network. If network_name is provided and no other
properties are provided (with exception of network_id), then an
existing network instance will be used. If network_name is provided
alongside with more properties then a new network with this name will
be created.
network_id:
type: string
required: false
description: >
An identifier that represents an existing Network instance in the
underlying cloud infrastructure. This property is mutually exclusive
with all other properties except network_name. This can be used alone
or together with network_name to identify an existing network.
segmentation_id:
type: string
required: false
description: >
A segmentation identifier in the underlying cloud infrastructure.
E.g. VLAN ID, GRE tunnel ID, etc..
network_type:
type: string
required: false
description: >
It specifies the nature of the physical network in the underlying
cloud infrastructure. Examples are flat, vlan, gre or vxlan.
For flat and vlan types, physical_network should be provided too.
physical_network:
type: string
required: false
description: >
It identifies the physical network on top of which the network is
implemented, e.g. physnet1. This property is required if network_type
is flat or vlan.
dhcp_enabled:
type: boolean
required: false
default: true
description: >
Indicates should DHCP service be enabled on the network or not.
capabilities:
link:
type: tosca.capabilities.network.Linkable
tosca.nodes.network.Port:
derived_from: tosca.nodes.Root
description: >
The TOSCA Port node represents a logical entity that associates between
Compute and Network normative types. The Port node type effectively
represents a single virtual NIC on the Compute node instance.
properties:
ip_address:
type: string
required: false
description: >
Allow the user to set a static IP.
order:
type: integer
required: false
default: 0
constraints:
- greater_or_equal: 0
description: >
The order of the NIC on the compute instance (e.g. eth2).
is_default:
type: boolean
required: false
default: false
description: >
If is_default=true this port will be used for the default gateway
route. Only one port that is associated to single compute node can
set as is_default=true.
ip_range_start:
type: string
required: false
description: >
Defines the starting IP of a range to be allocated for the compute
instances that are associated with this Port.
ip_range_end:
type: string
required: false
description: >
Defines the ending IP of a range to be allocated for the compute
instances that are associated with this Port.
attributes:
ip_address:
type: string
requirements:
- binding:
description: >
Binding requirement expresses the relationship between Port and
Compute nodes. Effectively it indicates that the Port will be
attached to specific Compute node instance
capability: tosca.capabilities.network.Bindable
relationship: tosca.relationships.network.BindsTo
node: tosca.nodes.Compute
- link:
description: >
Link requirement expresses the relationship between Port and Network
nodes. It indicates which network this port will connect to.
capability: tosca.capabilities.network.Linkable
relationship: tosca.relationships.network.LinksTo
node: tosca.nodes.network.Network
tosca.nodes.network.FloatingIP:
derived_from: tosca.nodes.Root
description: >
The TOSCA FloatingIP node represents a floating IP that can associate to a Port.
properties:
floating_network:
type: string
required: true
floating_ip_address:
type: string
required: false
port_id:
type: string
required: false
requirements:
- link:
capability: tosca.capabilities.network.Linkable
relationship: tosca.relationships.network.LinksTo
node: tosca.nodes.network.Port
tosca.nodes.LoadBalancer:
derived_from: tosca.nodes.Root
properties:
algorithm:
type: string
required: false
status: experimental
capabilities:
client:
type: tosca.capabilities.Endpoint.Public
occurrences: [0, UNBOUNDED]
description: the Floating (IP) client’s on the public network can connect to
requirements:
- application:
capability: tosca.capabilities.Endpoint
relationship: tosca.relationships.RoutesTo
occurrences: [0, UNBOUNDED]
description: Connection to one or more load balanced applications
tosca.nodes.Container.Runtime:
derived_from: tosca.nodes.SoftwareComponent
capabilities:
host:
type: tosca.capabilities.Container
valid_source_types: [tosca.nodes.Container.Application]
scalable:
type: tosca.capabilities.Scalable
tosca.nodes.Container.Application:
derived_from: tosca.nodes.Root
requirements:
- host:
capability: tosca.capabilities.Container
node: tosca.nodes.Container.Runtime
relationship: tosca.relationships.HostedOn
- storage:
capability: tosca.capabilities.Storage
- network:
capability: tosca.capabilities.Endpoint
# note: missing from 1.3 spec
tosca.nodes.Container.Runtime.Docker:
derived_from: tosca.nodes.Container.Runtime
capabilities:
host:
type: tosca.capabilities.Container.Docker
valid_source_types: [tosca.nodes.Container.Application.Docker]
tosca.nodes.Container.Application.Docker:
derived_from: tosca.nodes.Container.Application
requirements:
- host:
capability: tosca.capabilities.Container.Docker
##########################################################################
# Relationship Type.
# A Relationship Type is a reusable entity that defines the type of one
# or more relationships between Node Types or Node Templates.
##########################################################################
relationship_types:
tosca.relationships.Root:
description: >
The TOSCA root Relationship Type all other TOSCA base Relationship Types
derive from.
attributes:
tosca_id:
type: string
tosca_name:
type: string
interfaces:
Configure:
type: tosca.interfaces.relationship.Configure
tosca.relationships.DependsOn:
derived_from: tosca.relationships.Root
tosca.relationships.HostedOn:
derived_from: tosca.relationships.Root
tosca.relationships.ConnectsTo:
derived_from: tosca.relationships.Root
valid_target_types: [tosca.capabilities.Endpoint]
properties:
credential:
type: tosca.datatypes.Credential
required: false
tosca.relationships.AttachesTo:
derived_from: tosca.relationships.Root
valid_target_types: [tosca.capabilities.Attachment]
properties:
location:
required: true
type: string
constraints:
- min_length: 1
device:
required: false
type: string
tosca.relationships.RoutesTo:
derived_from: tosca.relationships.ConnectsTo
valid_target_types: [tosca.capabilities.Endpoint]
tosca.relationships.network.LinksTo:
derived_from: tosca.relationships.DependsOn
valid_target_types: [tosca.capabilities.network.Linkable]
tosca.relationships.network.BindsTo:
derived_from: tosca.relationships.DependsOn
valid_target_types: [tosca.capabilities.network.Bindable]
##########################################################################
# Capability Type.
# A Capability Type is a reusable entity that describes a kind of
# capability that a Node Type can declare to expose.
##########################################################################
capability_types:
tosca.capabilities.Root:
description: >
The TOSCA root Capability Type all other TOSCA base Capability Types
derive from.
tosca.capabilities.Node:
derived_from: tosca.capabilities.Root
tosca.capabilities.Container:
derived_from: tosca.capabilities.Root
tosca.capabilities.Storage:
derived_from: tosca.capabilities.Root
properties:
name:
type: string
required: false
tosca.capabilities.Compute:
derived_from: tosca.capabilities.Container
properties:
name:
type: string
required: false
num_cpus:
required: false
type: integer
constraints:
- greater_or_equal: 1
cpu_frequency:
required: false
type: scalar-unit.frequency
constraints:
- greater_or_equal: 0.1 GHz
disk_size:
required: false
type: scalar-unit.size
constraints:
- greater_or_equal: 0 MB
mem_size:
required: false
type: scalar-unit.size
constraints:
- greater_or_equal: 0 MB
tosca.capabilities.Endpoint:
derived_from: tosca.capabilities.Root
properties:
protocol:
type: string
required: true
default: tcp
port:
type: tosca.datatypes.network.PortDef
required: false
secure:
type: boolean
required: false
default: false
url_path:
type: string
required: false
port_name:
type: string
required: false
network_name:
type: string
required: false
default: PRIVATE
initiator:
type: string
required: false
default: source
constraints:
- valid_values: [source, target, peer]
ports:
type: map
required: false
constraints:
- min_length: 1
entry_schema:
type: tosca.datatypes.network.PortSpec
attributes:
ip_address:
type: string
tosca.capabilities.Endpoint.Admin:
derived_from: tosca.capabilities.Endpoint
properties:
secure:
type: boolean
default: true
constraints:
- equal: true
tosca.capabilities.Endpoint.Public:
derived_from: tosca.capabilities.Endpoint
properties:
# Change the default network_name to use the first public network found
network_name:
type: string
default: PUBLIC
constraints:
- equal: PUBLIC
floating:
description: >
Indicates that the public address should be allocated from a pool of
floating IPs that are associated with the network.
type: boolean
default: false
status: experimental
dns_name:
description: The optional name to register with DNS
type: string
required: false
status: experimental
tosca.capabilities.Scalable:
derived_from: tosca.capabilities.Root
properties:
min_instances:
type: integer
required: true
default: 1
description: >
This property is used to indicate the minimum number of instances
that should be created for the associated TOSCA Node Template by
a TOSCA orchestrator.
max_instances:
type: integer
required: true
default: 1
description: >
This property is used to indicate the maximum number of instances
that should be created for the associated TOSCA Node Template by
a TOSCA orchestrator.
default_instances:
type: integer
required: false
description: >
An optional property that indicates the requested default number
of instances that should be the starting number of instances a
TOSCA orchestrator should attempt to allocate.
The value for this property MUST be in the range between the values
set for min_instances and max_instances properties.
tosca.capabilities.Endpoint.Database:
derived_from: tosca.capabilities.Endpoint
tosca.capabilities.Attachment:
derived_from: tosca.capabilities.Root
tosca.capabilities.network.Linkable:
derived_from: tosca.capabilities.Root
description: >
A node type that includes the Linkable capability indicates that it can
be pointed by tosca.relationships.network.LinksTo relationship type, which
represents an association relationship between Port and Network node types.
tosca.capabilities.network.Bindable:
derived_from: tosca.capabilities.Root
description: >
A node type that includes the Bindable capability indicates that it can
be pointed by tosca.relationships.network.BindsTo relationship type, which
represents a network association relationship between Port and Compute node
types.
tosca.capabilities.OperatingSystem:
derived_from: tosca.capabilities.Root
properties:
architecture:
required: false
type: string
description: >
The host Operating System (OS) architecture.
type:
required: false
type: string
description: >
The host Operating System (OS) type.
distribution:
required: false
type: string
description: >
The host Operating System (OS) distribution. Examples of valid values
for an “type” of “Linux” would include:
debian, fedora, rhel and ubuntu.
version:
required: false
type: version
description: >
The host Operating System version.
tosca.capabilities.Container.Docker:
derived_from: tosca.capabilities.Container
properties:
version:
type: list
required: false
entry_schema:
type: version
description: >
The Docker version capability.
publish_all:
type: boolean
default: false
required: false
description: >
Indicates that all ports (ranges) listed in the dockerfile
using the EXPOSE keyword be published.
publish_ports:
type: list
entry_schema:
type: tosca.datatypes.network.PortSpec
required: false
description: >
List of ports mappings from source (Docker container)
to target (host) ports to publish.
expose_ports:
type: list
entry_schema:
type: tosca.datatypes.network.PortSpec
required: false
description: >
List of ports mappings from source (Docker container) to expose
to other Docker containers (not accessible outside host).
volumes:
type: list
entry_schema:
type: string
required: false
description: >
The dockerfile VOLUME command which is used to enable access
from the Docker container to a directory on the host machine.
##########################################################################
# Interfaces Type.
# The Interfaces element describes a list of one or more interface
# definitions for a modelable entity (e.g., a Node or Relationship Type)
# as defined within the TOSCA Simple Profile specification.
##########################################################################
interface_types:
tosca.interfaces.Root:
description: >
The TOSCA root Interface Type all other TOSCA Interface types derive from
tosca.interfaces.node.lifecycle.Standard:
operations:
create:
description: Standard lifecycle create operation.
configure:
description: Standard lifecycle configure operation.
start:
description: Standard lifecycle start operation.
stop:
description: Standard lifecycle stop operation.
delete:
description: Standard lifecycle delete operation.
tosca.interfaces.relationship.Configure:
operations:
pre_configure_source:
description: Operation to pre-configure the source endpoint.
pre_configure_target:
description: Operation to pre-configure the target endpoint.
post_configure_source:
description: Operation to post-configure the source endpoint.
post_configure_target:
description: Operation to post-configure the target endpoint.
add_target:
description: Operation to add a target node.
remove_target:
description: Operation to remove a target node.
add_source:
description: >
Operation to notify the target node of a source node which
is now available via a relationship.
remove_source:
description: >
Operation to notify the target node of a source node which
is no longer available via a relationship.
target_changed:
description: >
Operation to notify source some property or attribute of the
target changed
##########################################################################
# Data Type.
# A Datatype is a complex data type declaration which contains other
# complex or simple data types.
##########################################################################
data_types:
tosca.datatypes.Root:
description: >
The TOSCA root Data Type all other TOSCA base Data Types derive from
tosca.datatypes.network.NetworkInfo:
derived_from: tosca.datatypes.Root
properties:
network_name:
type: string
network_id:
type: string
addresses:
type: list
entry_schema:
type: string
tosca.datatypes.network.PortInfo:
derived_from: tosca.datatypes.Root
properties:
port_name:
type: string
port_id:
type: string
network_id:
type: string
mac_address:
type: string
addresses:
type: list
entry_schema:
type: string
tosca.datatypes.network.PortDef:
type: integer
constraints:
- in_range: [1, 65535]
tosca.datatypes.network.PortSpec:
derived_from: tosca.datatypes.Root
properties:
protocol:
type: string
required: true
default: tcp
constraints:
- valid_values: [udp, tcp, icmp]
target:
type: tosca.datatypes.network.PortDef
required: false
target_range:
type: range
required: false
constraints:
- in_range: [1, 65535]
source:
type: tosca.datatypes.network.PortDef
required: false
source_range:
type: range
required: false
constraints:
- in_range: [1, 65535]
tosca.datatypes.Credential:
derived_from: tosca.datatypes.Root
properties:
protocol:
type: string
required: false
token_type:
type: string
default: password
required: true
token:
type: string
required: true
keys:
type: map
entry_schema:
type: string
required: false
user:
type: string
required: false
tosca.datatypes.json:
type: string
tosca.datatypes.xml:
type: string
tosca.datatypes.TimeInterval:
derived_from: tosca.datatypes.Root
properties:
start_time:
type: timestamp
required: true
end_time:
type: timestamp
required: true
##########################################################################
# Artifact Type.
# An Artifact Type is a reusable entity that defines the type of one or more
# files which Node Types or Node Templates can have dependent relationships
# and used during operations such as during installation or deployment.
##########################################################################
artifact_types:
tosca.artifacts.Root:
description: >
The TOSCA Artifact Type all other TOSCA Artifact Types derive from
tosca.artifacts.File:
derived_from: tosca.artifacts.Root
tosca.artifacts.Deployment:
derived_from: tosca.artifacts.Root
description: TOSCA base type for deployment artifacts
tosca.artifacts.Deployment.Image:
derived_from: tosca.artifacts.Deployment
tosca.artifacts.Deployment.Image.VM:
derived_from: tosca.artifacts.Deployment.Image
description: Virtual Machine (VM) Image
tosca.artifacts.Implementation:
derived_from: tosca.artifacts.Root
description: TOSCA base type for implementation artifacts
tosca.artifacts.Implementation.Bash:
derived_from: tosca.artifacts.Implementation
description: Script artifact for the Unix Bash shell
mime_type: application/x-sh
file_ext: [sh]
tosca.artifacts.Implementation.Python:
derived_from: tosca.artifacts.Implementation
description: Artifact for the interpreted Python language
mime_type: application/x-python
file_ext: [py]
tosca.artifacts.Deployment.Image.Container.Docker:
derived_from: tosca.artifacts.Deployment.Image
description: Docker container image
tosca.artifacts.Deployment.Image.VM.ISO:
derived_from: tosca.artifacts.Deployment.Image
description: Virtual Machine (VM) image in ISO disk format
mime_type: application/octet-stream
file_ext: [iso]
tosca.artifacts.Deployment.Image.VM.QCOW2:
derived_from: tosca.artifacts.Deployment.Image
description: Virtual Machine (VM) image in QCOW v2 standard disk format
mime_type: application/octet-stream
file_ext: [qcow2]
tosca.artifacts.template:
derived_from: tosca.artifacts.Root
description: TOSCA base type for template type artifacts
##########################################################################
# Policy Type.
# TOSCA Policy Types represent logical grouping of TOSCA nodes that have
# an implied relationship and need to be orchestrated or managed together
# to achieve some result.
##########################################################################
policy_types:
tosca.policies.Root:
description: The TOSCA Policy Type all other TOSCA Policy Types derive from.
tosca.policies.Placement:
derived_from: tosca.policies.Root
description: The TOSCA Policy Type definition that is used to govern
placement of TOSCA nodes or groups of nodes.
tosca.policies.Scaling:
derived_from: tosca.policies.Root
description: The TOSCA Policy Type definition that is used to govern
scaling of TOSCA nodes or groups of nodes.
tosca.policies.Monitoring:
derived_from: tosca.policies.Root
description: The TOSCA Policy Type definition that is used to govern
monitoring of TOSCA nodes or groups of nodes.
tosca.policies.Update:
derived_from: tosca.policies.Root
description: The TOSCA Policy Type definition that is used to govern
update of TOSCA nodes or groups of nodes.
tosca.policies.Performance:
derived_from: tosca.policies.Root
description: The TOSCA Policy Type definition that is used to declare
performance requirements for TOSCA nodes or groups of nodes.
tosca.policies.Reservation:
derived_from: tosca.policies.Root
description: The TOSCA Policy Type definition that is used to create
TOSCA nodes or group of nodes based on the reservation.
##########################################################################
# Group Type.
# Group Type represents logical grouping of TOSCA nodes that have an
# implied membership relationship and may need to be orchestrated or
# managed together to achieve some result.
##########################################################################
group_types:
tosca.groups.Root:
description: The TOSCA Group Type all other TOSCA Group Types derive from
interfaces:
Standard:
type: tosca.interfaces.node.lifecycle.Standard
Unfurl types
# Copyright (c) 2020 Adam Souzis
# SPDX-License-Identifier: MIT
tosca_definitions_version: tosca_simple_unfurl_1_0_0 # unfurl/v1alpha1.ServiceTemplate
metadata:
template_name: Unfurl types
template_author: onecommons.org
template_version: 1.0.0
artifact_types:
unfurl.artifacts.Executable:
derived_from: tosca.artifacts.Root
description: >
Base type for declaring abstract executable artifacts that only define its expected inputs and outputs.
interfaces:
Executable:
type: unfurl.interfaces.Executable
unfurl.artifacts.HasConfigurator:
derived_from: tosca.artifacts.Implementation
properties:
className:
type: string
description: Name of the python class that implements the configurator interface
interfaces:
Executable:
type: unfurl.interfaces.Executable
unfurl.artifacts.TemplateOperation:
derived_from: unfurl.artifacts.HasConfigurator
properties:
className:
type: string
default: unfurl.configurators.TemplateConfigurator
resultTemplate:
type: any
required: false
description: >
A Jinja2 template or runtime expression that is processed after the operation completes.
Note: This evaluate in the context of the task executing this artifact, so "SELF" will be the current task's target, not the artifact.
The artifact can be accessed through the "implementation" variable.
unfurl.artifacts.ShellExecutable:
derived_from: unfurl.artifacts.TemplateOperation
properties:
className:
type: string
default: unfurl.configurators.shell.ShellConfigurator
command:
type: any
required: false
default: "{{ '.::contents' | eval or '.path' | eval }}"
description: >
The command to execute. It can be either a string or a list of command arguments.
Defaults to the artifact's file, or that can embedded in the command using {{ '.path' | eval }}
cwd:
type: string
required: false
description: Set the current working directory to execute the command in.
keeplines:
type: boolean
default: false
description: If true, preserve line breaks in the given command.
shell:
type: any
required: false
description: >
If a string, the executable of the shell to execute the command in (e.g. ``/usr/bin/bash``).
A boolean indicates whether the command if invoked through the default shell or not.
If omitted, it will be set to true if ``command`` is a string or false if it is a list.
echo:
type: boolean
required: false
description: >
A boolean that indicates whether or not should be standard output (and stderr)
should be echoed to Unfurl's stdout while the command is being run.
If omitted, true unless running with ``--quiet``.
(Doesn't affect the capture of stdout and stderr.)
input:
type: string
required: false
description: Optional string to pass as stdin.
outputsTemplate:
type: any
required: false
description: >
A `Jinja2 template or runtime expression that is processed after shell command completes, with same variables as `resultTemplate`.
The template should evaluate to a map to be used as the operation's outputs or null to skip.
dryrun:
type: string
required: false
description: >
During a during a dryrun job this will be either appended to the command line
or replace the string ``%dryrun%`` if it appears in the command. (``%dryrun%`` is stripped out when running regular jobs.)
If not set, the task will not be executed at all during a dry run job.
unfurl.artifacts.AnsiblePlaybook:
derived_from: unfurl.artifacts.TemplateOperation
properties:
className:
type: string
default: unfurl.configurators.ansible.AnsibleConfigurator
playbook:
type: any
default: "{{ '.::contents' | eval or '.path' | eval }}"
description: >
If a string, treat as a file path to the Ansible playbook to run, otherwise treat as an inline playbook
If omitted, it will use the artifact's ``contents`` if present or else the artifact's resolved file path.
playbookArgs:
type: list
required: false
description: >
A list of strings that will be passed to ``ansible-playbook`` as command-line arguments.
unfurl.artifacts.TerraformModule:
derived_from: unfurl.artifacts.TemplateOperation
properties:
className:
type: string
default: unfurl.configurators.terraform.TerraformConfigurator
main:
type: any
default: "{{ '.::contents' | eval or '.path' | eval }}"
description: >
The contents of the root Terraform module or a path to a directory containing the Terraform configuration.
If it is a directory path, the configurator will treat it as a local Terraform module.
Otherwise, if ``main`` is a string it will be treated as HCL and if it is a map, it will be written out as JSON.
If omitted, it will use the artifact's ``contents`` if present or else the artifact's resolved file path as the directory.
dryrun_mode:
type: string
constraints:
- valid_values: [plan, real]
default: plan
description: >
How to run during a dry run job. If set to "plan" just generate the Terraform plan. If set to "real", run the task without any dry run logic. Default: "plan"
dryrun_outputs:
type: any
required: false
description: >
During a dry run job, this map of outputs will be used simulate the task's outputs (otherwise outputs will be empty).
node_types:
tosca.nodes.Root:
interfaces:
Install: # all nodes can implement this interface
type: unfurl.interfaces.Install
Standard:
type: tosca.interfaces.node.lifecycle.Standard
unfurl.nodes.Repository:
derived_from: tosca.nodes.Root
description: >
Reification of a TOSCA repository. Artifacts listed in the "artifacts" section
of this node template will able available in the repository.
properties:
repository:
description: The name of the repository this node instance represent.
type: string
required: false
url:
description: The url of this repository
type: string
required: false
credential:
description: >
The credential, if present, of the repository this node instance represents.
type: tosca.datatypes.Credential
required: false
metadata:
sensitive: true
unfurl.nodes.LocalRepository:
derived_from: unfurl.nodes.Repository
description: >
Represents the collection of artifacts available to the local operation host.
unfurl.nodes.ArtifactBuilder:
derived_from: tosca.nodes.Root
description: >
Creates or builds the given artifact and "uploads" it to the artifact's repository.
unfurl.nodes.ArtifactInstaller:
derived_from: tosca.nodes.Root
description: >
Reification of an artifact that needs to be installed.
Node templates of this type are "discovered" when artifacts need to be installed on an operation_host.
artifacts:
install:
type: tosca.artifacts.Root
interfaces:
defaults:
# delegate operations to the associated artifact
implementation:
className: unfurl.configurators.DelegateConfigurator
inputs:
target:
eval: .artifacts::install
inputs: {}
Standard:
operations:
delete:
create:
configure:
start:
stop:
Install:
operations:
check:
Mock:
operations:
delete:
create:
configure:
start:
stop:
check:
unfurl.nodes.Installer:
derived_from: tosca.nodes.Root
capabilities:
installer:
type: unfurl.capabilities.Installer
unfurl.nodes.Installation:
derived_from: tosca.nodes.Root
requirements:
- installer:
capability: unfurl.capabilities.Installer
node: unfurl.nodes.Installer
relationship: unfurl.relationships.InstalledBy
occurrences: [0, 1] # it isn't necessarily required
unfurl.nodes.Default:
derived_from: unfurl.nodes.Installation
description: "Used if pre-existing instances are declared with no TOSCA template"
metadata:
additionalProperties: true
unfurl.nodes.Generic:
derived_from: tosca.nodes.Root
description: An open, generic type that allows your template to declare arbitrary properties.
metadata:
additionalProperties: true
unfurl.nodes.CloudAccount:
derived_from: tosca.nodes.Root
attributes:
account_id:
description: "Cloud provider specific account identifier"
type: string
unfurl.nodes.CloudObject:
derived_from: tosca.nodes.Root
attributes:
uri:
description: "Unique identifier"
type: string
name:
description: "Human-friendly name of the resource"
type: string
console_url:
description: "URL for viewing this resource in its cloud provider's console"
type: string
required: False
# XXX re-enable this when we handle subtypes of requirements properly
# requirements:
# - cloud:
# node: unfurl.nodes.CloudAccount
# relationship: unfurl.relationships.ConnectsTo.CloudAccount
# occurrences: [0, 1] # make optional so we aren't forced to always explicitly declare this
unfurl.nodes.AWSAccount:
derived_from: unfurl.nodes.CloudAccount
unfurl.nodes.AWSResource:
derived_from: unfurl.nodes.CloudObject
requirements:
- cloud:
node: unfurl.nodes.AWSAccount
relationship: unfurl.relationships.ConnectsTo.AWSAccount
occurrences: [0, 1] # make optional so we aren't forced to always explicitly declare this
metadata:
visibility: hidden
unfurl.nodes.AzureAccount:
derived_from: unfurl.nodes.CloudAccount
unfurl.nodes.AzureResource:
derived_from: unfurl.nodes.CloudObject
requirements:
- cloud:
node: unfurl.nodes.AzureAccount
relationship: unfurl.relationships.ConnectsTo.Azure
occurrences: [0, 1] # make optional so we aren't forced to always explicitly declare this
metadata:
visibility: hidden
data_types:
unfurl.datatypes.EnvVar:
derived_from: tosca.datatypes.Root
type: string
description: The value of an environment variable whose name matches the property's name
unfurl.datatypes.EnvironmentVariables:
derived_from: tosca.datatypes.Root
description: An open type (properties don't need to be declared) that serializes as a map of environment variables.
metadata:
additionalProperties: true
transform:
eval:
to_env:
eval: $value
capability_types:
unfurl.capabilities.Installer:
derived_from: tosca.capabilities.Root
unfurl.capabilities.Endpoint.Ansible:
derived_from: tosca.capabilities.Endpoint.Admin
description: Capability to connect to Ansible
properties:
connection:
description: The connection type (sets "ansible_connection")
type: string
default: local
port:
type: tosca.datatypes.network.PortDef
description: sets "ansible_port"
required: false
host:
type: string
description: Sets "ansible_host"
required: false
user:
description: Sets "ansible_user" if not set in credentials
type: string
required: false
authentication_type:
description: "Type of authentication required, should match the credential's token_type"
type: string
required: false
hostvars:
type: map
required: false
description: >
Passed to ansible as host vars
See https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#connecting-to-hosts-behavioral-inventory-parameters
unfurl.capabilities.Endpoint.SSH:
derived_from: unfurl.capabilities.Endpoint.Ansible
description: Capability to connect to the host via SSH
properties:
protocol:
type: string
value: ssh
default: ssh
connection:
type: string
default: ssh
port:
type: tosca.datatypes.network.PortDef
default: 22
relationship_types:
unfurl.relationships.InstalledBy:
derived_from: tosca.relationships.Root
valid_target_types: [unfurl.capabilities.Installer]
unfurl.relationships.Configures:
derived_from: tosca.relationships.Root
unfurl.relationships.ConfiguringHostedOn:
derived_from:
[unfurl.relationships.Configures, tosca.relationships.HostedOn]
unfurl.relationships.ConnectsTo.Ansible:
derived_from: tosca.relationships.ConnectsTo
valid_target_types: [unfurl.capabilities.Endpoint.Ansible]
properties:
credential:
description: Its "user" property sets "ansible_user", add properties like "ssh_private_key_file" to "keys"
type: tosca.datatypes.Credential
required: false
metadata:
sensitive: true
hostvars:
type: map
required: false
description: >
Passed to ansible as host vars
See https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#connecting-to-hosts-behavioral-inventory-parameters
unfurl.relationships.ConnectsTo.ComputeMachines:
derived_from: tosca.relationships.ConnectsTo
metadata:
exclude-from-configuration: true
unfurl.relationships.ConnectsTo.ObjectStorage:
derived_from: tosca.relationships.ConnectsTo
metadata:
exclude-from-configuration: true
properties:
access_key:
type: string
secret_key:
type: string
metadata:
sensitive: true
region:
type: string
default: us-east-1
endpoint_hostname:
type: string
description: hostname
required: false
unfurl.relationships.ConnectsTo.CloudAccount:
derived_from: unfurl.relationships.ConnectsTo.ComputeMachines
# valid_target_types: [unfurl.capabilities.Endpoint.CloudAccount]
unfurl.relationships.ConnectsTo.GoogleCloudProject:
derived_from: unfurl.relationships.ConnectsTo.CloudAccount
properties:
CLOUDSDK_CORE_PROJECT:
description: id of the project
type: unfurl.datatypes.EnvVar
default: { get_env: CLOUDSDK_CORE_PROJECT }
required: false
CLOUDSDK_COMPUTE_REGION:
description: default region to use
type: unfurl.datatypes.EnvVar
default: { get_env: CLOUDSDK_COMPUTE_REGION }
required: false
CLOUDSDK_COMPUTE_ZONE:
description: default zone to use
type: unfurl.datatypes.EnvVar
default: { get_env: CLOUDSDK_COMPUTE_ZONE }
required: false
GOOGLE_APPLICATION_CREDENTIALS:
description: "Path to file containing service account private keys in JSON format"
type: unfurl.datatypes.EnvVar
default: { get_env: GOOGLE_APPLICATION_CREDENTIALS }
required: false
# other authentication options:
GOOGLE_OAUTH_ACCESS_TOKEN:
description: A temporary OAuth 2.0 access token obtained from the Google Authorization server
type: unfurl.datatypes.EnvVar
default: { get_env: GOOGLE_OAUTH_ACCESS_TOKEN }
required: false
GCP_SERVICE_ACCOUNT_CONTENTS:
description: "Content of file containing service account private keys"
type: tosca.datatypes.json
default: { get_env: GCP_SERVICE_ACCOUNT_CONTENTS }
required: false
metadata:
sensitive: true
# some of the keys in the credential json:
# project_id
# type: auth_kind: type of authentication being used (choices: machineaccount, serviceaccount, application)
# client_email: email associated with the project
# scopes: The specific scopes that you want the actions to use.
GCP_AUTH_KIND:
type: unfurl.datatypes.EnvVar
constraints:
- valid_values: [application, machineaccount, serviceaccount]
default: { get_env: [GCP_AUTH_KIND, "serviceaccount"] }
required: false
scopes:
type: list
entry_schema:
type: string
required: false
interfaces:
Install:
check:
implementation:
className: unfurl.configurators.gcp.CheckGoogleCloudConnectionConfigurator
# XXX defined in artifacts.yaml
# dependencies:
# - google-auth
unfurl.relationships.ConnectsTo.AWSAccount:
derived_from:
[
unfurl.relationships.ConnectsTo.CloudAccount,
unfurl.relationships.ConnectsTo.ObjectStorage,
]
properties:
endpoints:
description: custom service endpoints
type: map
required: false
AWS_DEFAULT_REGION:
description: "The default region to use, e.g. us-west-1, us-west-2, etc."
type: unfurl.datatypes.EnvVar
default: { get_env: AWS_DEFAULT_REGION }
required: false
AWS_ACCESS_KEY_ID:
description: "The access key for your AWS account"
type: unfurl.datatypes.EnvVar
default: { get_env: AWS_ACCESS_KEY_ID }
required: false
AWS_SECRET_ACCESS_KEY:
description: "The secret key for your AWS account."
type: unfurl.datatypes.EnvVar
default: { get_env: AWS_SECRET_ACCESS_KEY }
required: false
metadata:
sensitive: true
# other authentication options:
AWS_SESSION_TOKEN:
description: "The session key for your AWS account."
type: unfurl.datatypes.EnvVar
default: { get_env: AWS_SESSION_TOKEN }
required: false
metadata:
sensitive: true
AWS_PROFILE:
type: unfurl.datatypes.EnvVar
default: { get_env: AWS_PROFILE }
required: false
AWS_SHARED_CREDENTIALS_FILE:
type: unfurl.datatypes.EnvVar
default: { get_env: AWS_SHARED_CREDENTIALS_FILE }
required: false
AWS_CONFIG_FILE:
type: unfurl.datatypes.EnvVar
default: { get_env: AWS_CONFIG_FILE }
required: false
# see https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-environment-variables
# for more environment variables
access_key:
default: "{{ SELF.AWS_ACCESS_KEY_ID }}"
required: false
secret_key:
default: "{{ SELF.AWS_SECRET_ACCESS_KEY }}"
required: false
region:
default: "{{ SELF.AWS_DEFAULT_REGION }}"
required: false
unfurl.relationships.ConnectsTo.DigitalOcean:
derived_from:
[
unfurl.relationships.ConnectsTo.CloudAccount,
unfurl.relationships.ConnectsTo.ObjectStorage,
]
properties:
credential:
metadata:
user_settable: false
sensitive: true
DIGITALOCEAN_TOKEN:
type: unfurl.datatypes.EnvVar
default: { get_env: DIGITALOCEAN_TOKEN }
metadata:
user_settable: true
sensitive: true
SPACES_ACCESS_KEY_ID:
description: "The access key for Spaces object storage."
type: unfurl.datatypes.EnvVar
default: { get_env: SPACES_ACCESS_KEY_ID }
required: false
metadata:
user_settable: true
env_vars: [SPACES_ACCESS_KEY_ID]
SPACES_SECRET_ACCESS_KEY:
description: "The secret key for Spaces object storage."
type: unfurl.datatypes.EnvVar
default: { get_env: SPACES_SECRET_ACCESS_KEY }
required: false
metadata:
user_settable: true
sensitive: true
env_vars: [SPACES_SECRET_ACCESS_KEY]
default_region:
type: string
title: Default Region
default: nyc3
description: "The default region to use, e.g. fra1, nyc3, etc."
metadata:
user_settable: true
access_key:
default: "{{ SELF.SPACES_ACCESS_KEY_ID }}"
required: false
secret_key:
default: "{{ SELF.SPACES_SECRET_ACCESS_KEY }}"
required: false
endpoint_hostname:
default: "{{ SELF.default_region }}.digitaloceanspaces.com"
region:
default: "{{ SELF.default_region }}"
unfurl.relationships.ConnectsTo.Azure:
derived_from:
[
unfurl.relationships.ConnectsTo.CloudAccount,
unfurl.relationships.ConnectsTo.ObjectStorage,
]
properties:
AZURE_CLIENT_ID:
description: >
Also known as an Application ID or `appId`.
Can be created via [CLI](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/service_principal_client_certificate)
or through the [Azure portal](https://learn.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal).
type: string
metadata:
env_vars: [ARM_CLIENT_ID, AZURE_CLIENT_ID]
title: Client ID
user_settable: true
default: { get_env: [ARM_CLIENT_ID, { get_env: AZURE_CLIENT_ID }] }
required: false
AZURE_TENANT:
description: >
[Find your Azure active directory tenant](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id#find-your-azure-ad-tenant)
type: string
metadata:
env_vars: [ARM_TENANT_ID, AZURE_TENANT]
title: Tenant
user_settable: true
default: { get_env: [ARM_TENANT_ID, { get_env: AZURE_TENANT }] }
required: false
AZURE_SUBSCRIPTION_ID:
description: >
[Find your Azure subscription](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription)
type: string
required: false
metadata:
env_vars: [ARM_SUBSCRIPTION_ID, AZURE_SUBSCRIPTION_ID]
title: Azure Subscription
user_settable: true
default:
{ get_env: [ARM_SUBSCRIPTION_ID, { get_env: AZURE_SUBSCRIPTION_ID }] }
AZURE_SECRET:
description: >
For authentication with service principal. [(Portal link)](https://learn.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret)
type: string
required: false
default: { get_env: [ARM_CLIENT_SECRET, { get_env: AZURE_SECRET }] }
metadata:
env_vars: [ARM_CLIENT_SECRET, AZURE_SECRET]
sensitive: true
title: Client Secret
user_settable: true
AZURE_AD_USER:
description: for authentication with Active Directory
type: unfurl.datatypes.EnvVar
default: { get_env: AZURE_AD_USER }
required: false
AZURE_PASSWORD:
description: for authentication with Active Directory
type: unfurl.datatypes.EnvVar
default: { get_env: AZURE_PASSWORD }
required: false
metadata:
sensitive: true
AZURE_ADFS_AUTHORITY_URL:
description: set if you have your own ADFS authority
type: unfurl.datatypes.EnvVar
default: { get_env: AZURE_ADFS_AUTHORITY_URL }
required: false
AZURE_STORAGE_ACCOUNT:
description: The storage account name.
type: unfurl.datatypes.EnvVar
default: { get_env: AZURE_STORAGE_ACCOUNT }
required: false
AZURE_STORAGE_KEY:
description: The storage account key.
type: unfurl.datatypes.EnvVar
default: { get_env: AZURE_STORAGE_KEY }
required: false
metadata:
sensitive: true
AZURE_STORAGE_CONNECTION_STRING:
description: A connection string that includes the storage account key or a SAS token.
type: unfurl.datatypes.EnvVar
default: { get_env: AZURE_STORAGE_CONNECTION_STRING }
required: false
metadata:
sensitive: true
access_key:
default: "{{ SELF.AZURE_STORAGE_ACCOUNT }}"
required: false
secret_key:
default: "{{ SELF.AZURE_STORAGE_KEY }}"
required: false
unfurl.relationships.ConnectsTo.Packet:
derived_from: unfurl.relationships.ConnectsTo.CloudAccount
properties:
project:
description: UUID to packet project
type: string
PACKET_API_TOKEN:
type: unfurl.datatypes.EnvVar
default: { get_env: PACKET_API_TOKEN }
metadata:
sensitive: true
unfurl.relationships.ConnectsTo.OpenStack:
derived_from: unfurl.relationships.ConnectsTo.CloudAccount
# from pyrax (rackspace, openstack)
# RAX_CREDS_FILE
# CLOUD_ID_TYPE "rackspace" or "keystone"
# CLOUD_REGION default: "DFW"
# also CLOUD_* in https://github.com/pycontribs/pyrax/blob/master/docs/getting_started.md#available-configuration-settings
unfurl.relationships.ConnectsTo.Rackspace:
derived_from: unfurl.relationships.ConnectsTo.OpenStack
interface_types:
Mock:
derived_from: tosca.interfaces.Root
unfurl.interfaces.Executable:
derived_from: tosca.interfaces.Root
operations:
execute:
description: Execute the artifact
unfurl.interfaces.Install:
derived_from: tosca.interfaces.Root
operations:
check:
description: Checks and sets the status and attributes of the instance
discover:
description: Discovers current state of the current instance and (possibly) related instances, updates the spec as needed.
revert:
description: Restore the instance to the state it was original found in.
connect:
description: Connect to a pre-existing resource.
restart:
description: Restart the resource.
group_types:
unfurl.groups.AnsibleInventoryGroup:
derived_from: tosca.groups.Root
description: Use this to place hosts in Ansible inventory groups
properties:
hostvars:
description: Ansible hostvars for members of this group
type: map
default: {}
members: [tosca.nodes.Compute, unfurl.groups.ansibleInventoryGroup]