------- # TOSCA Version 2.0 ## Committee Specification Draft 07 ## 9 October 2024 #### This Stage https://docs.oasis-open.org/tosca/TOSCA/v2.0/csd07/TOSCA-v2.0-csd07.md (Authoritative) \ https://docs.oasis-open.org/tosca/TOSCA/v2.0/csd07/TOSCA-v2.0-csd07.html \ https://docs.oasis-open.org/tosca/TOSCA/v2.0/csd07/TOSCA-v2.0-csd07.pdf #### Previous Stage https://docs.oasis-open.org/tosca/TOSCA/v2.0/csd06/TOSCA-v2.0-csd06.docx (Authoritative) \ https://docs.oasis-open.org/tosca/TOSCA/v2.0/csd06/TOSCA-v2.0-csd06.html \ https://docs.oasis-open.org/tosca/TOSCA/v2.0/csd06/TOSCA-v2.0-csd06.pdf #### Latest Stage https://docs.oasis-open.org/tosca/TOSCA/v2.0/TOSCA-v2.0.md (Authoritative) \ https://docs.oasis-open.org/tosca/TOSCA/v2.0/TOSCA-v2.0.html \ https://docs.oasis-open.org/tosca/TOSCA/v2.0/TOSCA-v2.0.pdf #### Technical Committee [OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA) TC](https://groups.oasis-open.org/communities/tc-community-home2?CommunityKey=f9412cf3-297d-4642-8598-018dc7d3f409) #### Chair Chris Lauwers ([email protected]), Individual Member #### Editors Chris Lauwers ([email protected]), Individual Member \ Calin Curescu ([email protected]), [Ericsson](http://ericsson.com/) #### Related Work This specification replaces or supersedes: * _Topology and Orchestration Specification for Cloud Applications Version 1.0._ Edited by Derek Palma and Thomas Spatzier. OASIS Standard. Latest version: http://docs.oasis-open.org/tosca/TOSCA/v1.0/TOSCA-v1.0.html. * _TOSCA Simple Profile in YAML Version 1.3._ Edited by Matt Rutkowski, Chris Lauwers, Claude Noshpitz, and Calin Curescu. Latest stage: https://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.3/TOSCA-Simple-Profile-YAML-v1.3.html. This specification is related to: * _Introduction to TOSCA Version 2.0._ Edited by Chris Lauwers and Calin Curescu. Work in progress. #### Abstract The Topology and Orchestration Specification for Cloud Applications (TOSCA) provides a language for describing application components and their relationships by means of a service topology, and for specifying the lifecycle management procedures for creation or modification of services using orchestration processes. The combination of topology and orchestration enables not only the automation of deployment but also the automation of the complete service lifecycle management. The TOSCA specification promotes a model-driven approach, whereby information embedded in the model structure (the dependencies, connections, compositions) drives the automated processes. #### Status This document was last revised or approved by the OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA) TC on the above date. The level of approval is also listed above. Check the "Latest stage" location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://groups.oasis-open.org/communities/tc-community-home2?CommunityKey=f9412cf3-297d-4642-8598-018dc7d3f409#technical. TC members should send comments on this specification to the TC's email list. Any individual may submit comments to the TC by sending email to [email protected]. Please use a Subject line like "Comment on TOSCA". This specification is provided under the [RF on Limited Terms](https://www.oasis-open.org/policies-guidelines/ipr/#RF-on-Limited-Mode) of the [OASIS IPR Policy](https://www.oasis-open.org/policies-guidelines/ipr/), 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). Note that any machine-readable content ([Computer Language Definitions](https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26/#wpComponentsCompLang)) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails. #### Key Words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [[RFC2119](#rfc2119)] and [[RFC8174](#rfc8174)] when, and only when, they appear in all capitals, as shown here. #### Citation Format When referencing this specification the following citation format should be used: **[TOSCA-v2.0]** _TOSCA Version 2.0_. Edited by Chris Lauwers and Calin Curescu. 9 October 2024. OASIS Committee Specification Draft 06. https://docs.oasis-open.org/tosca/TOSCA/v2.0/csd07/TOSCA-v2.0-csd07.html. Latest stage: https://docs.oasis-open.org/tosca/TOSCA/v2.0/TOSCA-v2.0.html. #### Notices Copyright © OASIS Open 2024. All Rights Reserved. Distributed under the terms of the OASIS [IPR Policy](https://www.oasis-open.org/policies-guidelines/ipr/). The name "OASIS" is a trademark of [OASIS](https://www.oasis-open.org/), the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. For complete copyright information please see the full Notices section in [Appendix E](#appendix-e-notices). ------- # Table of Contents - [1 Introduction ](#introduction) - [1.1 Changes from Earlier Versions ](#changes-from-earlier-versions) - [1.2 Document Conventions ](#document-conventions) - [1.2.1 Specification Conventions](#specification-conventions) - [1.2.1.1 Code Snippets](#code-snippets) - [1.2.1.2 Placeholders](#placeholders) - [1.2.2 TOSCA Naming Conventions](#tosca-naming-conventions) - [1.3 Glossary ](#glossary) - [1.3.1 Definitions of Terms ](#definitions-of-terms) - [1.3.2 Acronyms and Abbreviations ](#acronyms-and-abbreviations) - [2 TOSCA Overview ](#tosca-overview) - [2.1 Objectives ](#objectives) - [2.2 TOSCA Features and Benefits ](#tosca-features-and-benefits) - [2.2.1 TOSCA Is Model-Driven ](#tosca-is-model-driven) - [2.2.2 TOSCA Models Are Graphs ](#tosca-models-are-graphs) - [2.2.3 TOSCA Promotes Reuse and Modularity ](#tosca-promotes-reuse-and-modularity) - [2.2.4 TOSCA Is Domain-Independent ](#tosca-is-domain-independent) - [2.3 TOSCA Core Concepts ](#tosca-core-concepts) - [2.4 Using TOSCA ](#using-tosca) - [2.4.1 TOSCA Files ](#tosca-files) - [2.4.2 Archive Format for Cloud Applications ](#archive-format-for-cloud-applications) - [3 TOSCA Language Abstractions ](#tosca-language-abstractions) - [3.1 Service Templates, Node Templates, and Relationship Templates ](#service-templates-node-templates-and-relationship-templates) - [3.2 Requirements and Capabilities ](#requirements-and-capabilities) - [3.3 Decomposition of Node Representations ](#decomposition-of-node-representations) - [3.4 Interfaces, Operations, and Artifacts ](#interfaces-operations-and-artifacts) - [3.5 Workflows ](#workflows) - [3.6 Policies ](#policies) - [4 TOSCA Operational Model ](#tosca-operational-model) - [4.1 TOSCA Functional Architecture ](#tosca-functional-architecture) - [4.2 TOSCA Processor ](#tosca-processor) - [4.2.1 Parser ](#parser) - [4.2.2 Resolver ](#resolver) - [4.3 Orchestrator ](#orchestrator) - [4.4 Changes in the Representation Graph ](#changes-in-the-representation-graph) - [5 TOSCA Grammar Overview ](#tosca-grammar-overview) - [5.1 TOSCA Modeling Concepts ](#tosca-modeling-concepts) - [5.1.1 Type Definitions and Entity Definitions ](#type-definitions-and-entity-definitions) - [5.1.2 Templates and Entity Assignments ](#templates-and-entity-assignments) - [5.1.3 Type Derivation, Augmentation, and Refinement ](#type-derivation-augmentation-and-refinement) - [5.1.4 TOSCA File Reuse ](#tosca-file-reuse) - [5.2 Mandatory Keynames ](#mandatory-keynames) - [5.3 Common Keynames ](#common-keynames) - [5.3.1 `metadata` ](#metadata) - [5.3.2 `description` ](#description) - [6 TOSCA File Definition ](#tosca-file-definition) - [6.1 Keynames ](#keynames) - [6.2 TOSCA Definitions Version ](#tosca-definitions-version) - [6.3 DSL Definitions ](#dsl-definitions) - [6.4 Type Definitions ](#type-definitions) - [6.4.1 Common Keynames in Type Definitions ](#common-keynames-in-type-definitions) - [6.4.2 Type Derivation ](#type-derivation) - [6.4.3 Types of Types ](#types-of-types) - [6.4.3.1 Artifact Types ](#artifact-types) - [6.4.3.2 Data Types ](#data-types) - [6.4.3.3 Capability Types ](#capability-types) - [6.4.3.4 Interface Types ](#interface-types) - [6.4.3.5 Relationship Types ](#relationship-types) - [6.4.3.6 Node Types ](#node-types) - [6.4.3.7 Group Types ](#group-types) - [6.4.3.8 Policy Types ](#policy-types) - [6.5 Repository Definitions ](#repository-definitions) - [6.6 Function Definitions ](#function-definitions) - [6.7 Profiles ](#profiles) - [6.7.1 Grammar ](#grammar) - [6.7.2 TOSCA Simple Profile](#tosca-simple-profile) - [6.7.3 Profile Versions ](#profile-versions) - [6.8 Imports and Namespaces ](#imports-and-namespaces) - [6.8.1 Import Definitions ](#import-definitions) - [6.8.2 Import Processing Rules ](#import-processing-rules) - [6.8.2.1 Importing Profiles ](#importing-profiles) - [6.8.2.2 Importing a TOSCA File ](#importing-a-tosca-file) - [6.8.3 Examples ](#examples) - [6.8.4 Namespaces ](#namespaces) - [6.9 Service Template Definition ](#service-template-definition) - [6.9.1 Service Template Grammar ](#service-template-grammar) - [6.9.2 Input Parameters ](#input-parameters) - [6.9.3 Node Templates ](#node-templates) - [6.9.4 Relationship Templates ](#relationship-templates) - [6.9.5 Output Parameters ](#output-parameters) - [6.9.6 Workflow Definitions ](#workflow-definitions) - [6.9.7 Group Definitions ](#group-definitions) - [6.9.8 Policy Definitions ](#policy-definitions) - [6.9.9 Substitution Mappings ](#substitution-mappings) - [7 Nodes and Relationships ](#nodes-and-relationships) - [7.1 Node Type ](#node-type) - [7.2 Node Template ](#node-template) - [7.2.1 Node Template Directives](#node-template-directives) - [7.3 Relationship Type ](#relationship-type) - [7.4 Relationship Template ](#relationship-template) - [8 Capabilities and Requirements ](#capabilities-and-requirements) - [8.1 Capability Type ](#capability-type) - [8.2 Capability Definition ](#capability-definition) - [8.2.1 Capability Refinement ](#capability-refinement) - [8.3 Capability Assignment ](#capability-assignment) - [8.4 Requirement Definition ](#requirement-definition) - [8.4.1 Requirement Refinement ](#requirement-refinement) - [8.5 Requirement Assignment ](#requirement-assignment) - [8.5.1 Supported Keynames ](#supported-keynames) - [8.5.2 Requirement Assignment Grammar ](#requirement-assignment-grammar) - [8.5.4 Requirement Count ](#requirement-count) - [8.5.5 Capability Allocation ](#capability-allocation) - [8.6 Node Filter Definition ](#node-filter-definition) - [9 Properties, Attributes, and Parameters ](#properties-attributes-and-parameters) - [9.1 TOSCA Built-In Types ](#tosca-built-in-types) - [9.1.1 Primitive Types ](#primitive-types) - [9.1.1.1 `string` ](#string) - [9.1.1.2 `integer` ](#integer) - [9.1.1.3 `float` ](#float) - [9.1.1.4 `boolean` ](#boolean) - [9.1.1.5 `bytes` ](#bytes) - [9.1.1.6 `nil` ](#nil) - [9.1.2 Special Types ](#special-types) - [9.1.2.1 `timestamp` ](#timestamp) - [9.1.2.2 `scalar` ](#scalar) - [9.1.2.2.2 Examples ](#examples) - [9.1.2.3 `version` ](#version) - [9.1.3 Collection Types ](#collection-types) - [9.1.3.1 `list` ](#list) - [9.1.3.2 `map` ](#map) - [9.2 Data Type ](#data-type) - [9.3 Schema Definition ](#schema-definition) - [9.4 Property Definition ](#property-definition) - [9.5 Property Assignment ](#property-assignment) - [9.6 Attribute Definition ](#attribute-definition) - [9.7 Attribute Assignment ](#attribute-assignment) - [9.8 Parameter Definition ](#parameter-definition) - [9.9 Parameter Value Assignment ](#parameter-value-assignment) - [9.10 Parameter Mapping Assignment ](#parameter-mapping-assignment) - [9.11 Validation Clause ](#validation-clause) - [10 TOSCA Functions ](#tosca-functions) - [10.1 Function Syntax ](#function-syntax) - [10.2 TOSCA Built-In Functions](#tosca-built-in-functions) - [10.2.1 Representation Graph Query Functions](#representation-graph-query-functions) - [10.2.1.1 `$get_input` ](#get_input) - [10.2.1.2 `$get_property` ](#get_property) - [10.2.1.3 `$get_attribute` ](#get_attribute) - [10.2.1.4 `$get_artifact` ](#get_artifact) - [10.2.1.5 `$value` ](#value) - [10.2.1.6 `$node_index` ](#node_index) - [10.2.1.7 `$relationship_index` ](#relationship_index) - [10.2.1.8 `$available_allocation` ](#available_allocation) - [10.2.2 Boolean Functions ](#boolean-functions) - [10.2.2.1 Boolean Logic Functions ](#boolean-logic-functions) - [10.2.2.1.1 `$and` ](#and) - [10.2.2.1.2 `$or` ](#or) - [10.2.2.1.3 `$not` ](#not) - [10.2.2.1.4 `$xor` ](#xor) - [10.2.2.2 Comparison Functions ](#comparison-functions) - [10.2.2.2.1 `$equal` ](#equal) - [10.2.2.2.2 `$greater_than` ](#greater_than) - [10.2.2.2.3 `$greater_or_equal` ](#greater_or_equal) - [10.2.2.2.4 `$less_than` ](#less_than) - [10.2.2.2.5 `$less_or_equal` ](#less_or_equal) - [10.2.2.2.6 `$valid_values` ](#valid_values) - [10.2.2.2.7 `$matches` ](#matches) - [10.2.2.3 Boolean List, Map and String Functions ](#boolean-list-map-and-string-functions) - [10.2.2.3.1 `$has_suffix` ](#has_suffix) - [10.2.2.3.2 `$has_prefix` ](#has_prefix) - [10.2.2.3.3 `$contains` ](#contains) - [10.2.2.3.4 `$has_entry` ](#has_entry) - [10.2.2.3.5 `$has_key` ](#has_key) - [10.2.2.3.6 `$has_all_entries` ](#has_all_entries) - [10.2.2.3.7 `$has_all_keys` ](#has_all_keys) - [10.2.2.3.8 `$has_any_entry` ](#has_any_entry) - [10.2.2.3.9 `$has_any_key` ](#has_any_key) - [10.2.3 String, List, and Map Functions ](#string-list-and-map-functions) - [10.2.3.1 `$length` ](#length) - [10.2.3.2 `$concat` ](#concat) - [10.2.3.3 `$join` ](#join) - [10.2.3.4 `$token` ](#token) - [10.2.4 Set Functions ](#set-functions) - [10.2.4.1 `$union` ](#union) - [10.2.4.2 `$intersection` ](#intersection) - [10.2.5 Arithmetic Functions ](#arithmetic-functions) - [10.2.5.1 `$sum` ](#sum) - [10.2.5.2 `$difference` ](#difference) - [10.2.5.3 `$product` ](#product) - [10.2.5.4 `$quotient` ](#quotient) - [10.2.5.5 `$remainder` ](#remainder) - [10.2.5.6 `$round` ](#round) - [10.2.5.7 `$floor` ](#floor) - [10.2.5.8 `$ceil` ](#ceil) - [10.3 TOSCA Path ](#tosca-path) - [10.4 Function Definitions ](#function-definitions) - [11 Interfaces, Operations, and Notifications ](#interfaces-operations-and-notifications) - [11.1 Interface Type ](#interface-type) - [11.2 Interface Definition ](#interface-definition) - [11.3 Interface Assignment ](#interface-assignment) - [11.4 Operation Definition ](#operation-definition) - [11.5 Operation Assignment ](#operation-assignment) - [11.6 Notification Definition ](#notification-definition) - [11.7 Notification Assignment ](#notification-assignment) - [11.8 Operation and Notification Implementations ](#operation-and-notification-implementations) - [12 Artifacts ](#artifacts) - [12.1 Artifact Type ](#artifact-type) - [12.2 Artifact Definition ](#artifact-definition) - [13 Workflows ](#workflows) - [13.1 Declarative Workflows ](#declarative-workflows) - [13.2 Imperative Workflows ](#imperative-workflows) - [13.2.1 Workflow Precondition Definition ](#workflow-precondition-definition) - [13.2.2 Workflow Step Definition ](#workflow-step-definition) - [13.2.3 Activity Definition ](#activity-definition) - [13.2.3.1 Delegate Workflow Activity Definition ](#delegate-workflow-activity-definition) - [13.2.3.2 Set State Activity Definition ](#set-state-activity-definition) - [13.2.3.3 Call Operation Activity Definition ](#call-operation-activity-definition) - [13.2.3.4 Inline Workflow Activity Definition ](#inline-workflow-activity-definition) - [14 Creating Multiple Representations from Templates ](#creating-multiple-representations-from-templates) - [14.1 Specifying Number of Node Representations ](#specifying-number-of-node-representations) - [14.2 Node-Specific Input Values ](#node-specific-input-values) - [14.3 Cardinality of Relationships ](#cardinality-of-relationships) - [14.3.1 Many-to-One Relationships ](#many-to-one-relationships) - [14.3.2 One-to-Many Relationships ](#one-to-many-relationships) - [14.3.3 Full Mesh ](#full-mesh) - [14.3.4 Matched Pairs ](#matched-pairs) - [14.3.5 Random Pairs ](#random-pairs) - [14.3.6 Many-to-Many Relationships ](#many-to-many-relationships) - [15 Substitution ](#substitution) - [15.1 Substitution Mapping ](#substitution-mapping) - [15.2 Property Mapping ](#property-mapping) - [15.3 Attribute Mapping ](#attribute-mapping) - [15.4 Capability Mapping ](#capability-mapping) - [15.5 Requirement Mapping ](#requirement-mapping) - [15.5.1 Mapping Multiple Requirements with the Same Name ](#mapping-multiple-requirements-with-the-same-name) - [15.5.2 Mapping a Requirement Multiple Times ](#mapping-a-requirement-multiple-times) - [15.5.3 Requirement Mapping and Selectable Nodes ](#requirement-mapping-and-selectable-nodes) - [15.5.4 Requirement Mapping Rules ](#requirement-mapping-rules) - [15.5.5 Handling `UNBOUNDED` Requirement Count Ranges ](#handling-unbounded-requirement-count-ranges) - [15.6 Interface Mapping ](#interface-mapping) - [16 Groups and Policies ](#groups-and-policies) - [16.1 Group Type ](#group-type) - [16.2 Group Definition ](#group-definition) - [16.3 Policy Type ](#policy-type) - [16.4 Policy Definition ](#policy-definition) - [16.5 Trigger Definition ](#trigger-definition) - [17 Cloud Service Archive (CSAR) Format ](#cloud-service-archive-csar-format) - [17.1 Overall Structure of a CSAR ](#overall-structure-of-a-csar) - [17.1.1 CSAR Archiving Formats ](#csar-archiving-formats) - [17.1.1.1 Tarballs ](#tarballs) - [17.1.1.2 Zip Files ](#zip-files) - [17.2 `TOSCA.meta` File ](#toscameta-file) - [17.2.1 Block 0 Keynames in the `TOSCA.meta` File ](#block-0-keynames-in-the-toscameta-file) - [17.2.2 Custom Keynames in the `TOSCA.meta` File ](#custom-keynames-in-the-toscameta-file) - [17.3 CSAR Without a `TOSCA.meta` File ](#csar-without-a-toscameta-file) - [18 Conformance ](#conformance) - [18.1 Conformance Targets ](#conformance-targets) - [18.2 Conformance Clause 1: TOSCA File ](#conformance-clause-1-tosca-file) - [18.3 Conformance Clause 2: TOSCA Processor ](#conformance-clause-2-tosca-processor) - [18.4 Conformance Clause 3: TOSCA Orchestrator ](#conformance-clause-3-tosca-orchestrator) - [18.5 Conformance Clause 4: TOSCA Generator ](#conformance-clause-4-tosca-generator) - [18.6 Conformance Clause 5: TOSCA Archive ](#conformance-clause-5-tosca-archive) - [Appendix A. References](#appendix-a-references) - [A.1 Normative References](#a1-normative-references) - [A.2 Informative References](#a2-informative-references) - [Appendix B. Safety, Security and Privacy Considerations](#appendix-b-safety-security-and-privacy-considerations) - [Appendix C. Acknowledgments](#appendix-c-acknowledgments) - [C.1 Special Thanks](#c1-special-thanks) - [C.2 Participants](#c2-participants) - [Appendix D. Revision History](#appendix-d-revision-history) - [Appendix E. Notices ](#appendix-e-notices) ------- # 1 Introduction The Topology and Orchestration Specification for Cloud Applications (TOSCA) provides a language for describing components and their relationships by means of a service topology, and for specifying the lifecycle management procedures for creation or modification of services using orchestration processes. The combination of topology and orchestration enables not only the automation of deployment but also the automation of the complete service lifecycle management. The TOSCA specification promotes a model-driven approach, whereby information embedded in the model structure (the dependencies, connections, compositions) drives the automated processes. The content in this section is non-normative. ## 1.1 Changes from Earlier Versions This version of the specification includes significant changes from TOSCA 1.3. In particular: 1. TOSCA v2.0 removes the *Simple Profile* type definitions from the standard. These type definitions are now managed as an open source project in the [tosca-community-contributions](https://github.com/oasis-open/tosca-community-contributions) github repository. 2. Rather than bundling Profiles with the TOSCA standard, TOSCA v2.0 provides support for user-defined domain-specific profiles as follows: - It allows collections of type definitions to be bundled together into named profiles. - It supports importing profiles using their profile name. 3. TOSCA v2.0 formalizes support for in-life operation of a running service. - It formalizes the role of a representation model and clarifies how to create representation models from service templates. - It documents how to create multiple node representations from the same node template and multiple relationships from the same requirement assignment. - It defines an operational model that provides guidance for updating and/or upgrading a running service and for responding to notifications about state changes or errors. 4. TOSCA v2.0 introduces a new TOSCA Path syntax that allows a defined traversal of an arbitrary graph of nodes and relationships to an attribute or property. 5. TOSCA v2.0 significantly enhances support for functions. It formalizes function syntax, it extends the set of built-in functions, and it introduces support for user-defined custom functions. 6. TOSCA v2.0 harmonizes constraint syntax, filter syntax, and condition syntax using Boolean functions. 7. TOSCA v2.0 addresses shortcomings of the v1.3 substitution mapping grammar. 8. TOSCA v2.0 simplifies and extends the CSAR file format. 9. TOSCA v2.0 includes a broad set of syntax clarifications, including but not limited to: - The service template is renamed TOSCA file and service template is redefined. - Grammar for relationship types, requirement definitions, and requirement assignments has been extended and clarified. - Short notation for `entry_schema` and `key_schema` has been documented ## 1.2 Document Conventions ### 1.2.1 Specification Conventions #### 1.2.1.1 Code Snippets Within this document we use monospace font sections to denote code snippets, primarily for TOSCA (YAML), but also for other textual file formats (e.g. CSAR meta files). For example: ```yaml MyMap: property1: value property2: [ value1, value2 ] ``` #### 1.2.1.2 Placeholders Within this document we use angle brackets (`<...>`) with snake case names in monospace font to denote specification placeholders: values that must be provided by service template and profile authors. These are used both in the explanatory language of the specification as well as in the TOSCA (YAML) code snippets. We use snake case in order to avoid spaces that could introduce rendering problems due to malformed code parsing. The names in the angle brackets are a brief description of the value and sometimes also hint at the type of value when appropriate and helpful. Examples: ``, ``, ``. Note that if you copy a TOSCA code snippet that includes this notation you must replace the placeholders with your own content. Also note that while some placeholders are for specific YAML types (e.g. strings, numbers, booleans), some may allow for complex values (sequences and maps), and indeed allow for nested complex values. Refer to the explanations for details. Variations: * ` | `: placeholder for one of several kinds of value. Each kind has a different meaning, use, or rule, and is often (but not always) of a different data type. There can be multiple pipes `|` if more than two kinds of value are possible. Example: ` | | `. * `[ , , ... ]`: placeholder for a YAML sequence of placeholders of the same kind. Note that in some cases this may mean "one or more", but in other cases an empty sequence is also possible. See the explanatory text for rules. The sequence may also appear in long YAML notation: ```yaml - - - ... ``` Note that elements may have more than one kind, noted with a `|` as above. Example: `[ | , | , ... ]` * Placeholders for YAML map entries always appear nested in the long YAML notation: ```yaml key: ... ``` * `` is used to refer to any or all of the placeholders in the sequence or map notations. ### 1.2.2 TOSCA Naming Conventions In the TOSCA examples included in this specification we adhere to a few conventions. Note that TOSCA parser should not normally enforce these conventions and you are generally free to use other conventions in your service templates and profiles. However, we encourage authors to adopt our conventions if possible in order to encourage consistent readability within the TOSCA ecosystem. * *TOSCA keynames*: snake case. Future versions of TOSCA, as well as forked variants, will continue to use this convention when introducing new keynames. Examples: `service_template`, `node_filter`, `valid_relationship_types`. In this document we use monospace font for all TOSCA keynames in order to clearly differentiate the language specification from user values. * *TOSCA value names*: dash case (also called kebab case). This includes names of node templates, properties, attributes, inputs, operations, capabilities, relationships, metadata keys, repository names, artifacts names, etc. Dash case is preferred in order to differentiate these names from keynames. Examples: "control-plane", "max-bandwidth", "source-url", "deployment-host", "connection-pool-size". * *TOSCA entity type names*: camel case. This includes all TOSCA entity types: nodes, relationships, capabilities, artifacts, data, etc. Examples: "Server", "BlockStorage", "OperatingSystem", "VirtualLink". *All* words in the name should be capitalized, *including prepositions*. Examples: "AddressAndPort", "NetworkOrFile". Acronyms and abbreviations should be treated as words, *except* when the name is just a single acronym. Examples: "HttpEndpoint", "TcpOrUdp", "TCP", "DBMS". * *TOSCA relationship type names*: prefer fragments that appear between nouns, which usually are verbs in present simple form and may include a preposition. Examples: "Includes", "Rejects", "DependsOn", "LinksTo", "RunAt", "FromSource". * *TOSCA capability type names*: these are commonly -able adjectives or other typifying, characterizing, or modifying words. Examples: "Bindable", "Linkable", "Scalable", "Host", "DataSource". * *TOSCA primitive data type names*: we prefer single lower-case whole words: `string`, `integer`, `float`, `boolean`. Note that previous versions of TOSCA also had types with the "scalar-unit." prefix, however we now prefer to to use normal camel case type names for these. See [`scalar`](#scalar) for more examples. As primitive data type names are part of the language specification, they are represented in monospace font. * *TOSCA function names*: snake case. This includes the built-in functions as well as custom functions. Examples: `$greater_than`, `$has_any_key`, `$my_custom_function`. As function names are part of the language specification, they are represented in monospace font. ## 1.3 Glossary ### 1.3.1 Definitions of Terms The following terms are used throughout this specification and have the following definitions when used in context of this document. |Term|Definition| |---|---| |External implementation|An external implementation is a *component* in the real world that can be used or managed by an Orchestrator. External implementations can consist of physical resources deployed in the real world as well as logical or virtual components provisioned or configured on those resources.| |System|A *collection* of one or more external implementations that is designed to work together to deliver a specific mission.| |Service|A system that can be deployed, provisioned, or configured *on-demand* by an Orchestrator.| |Topology|A topology defines the *structure* of a system. Topologies define the external implementations that make up the system as well as the interactions or other dependencies between these components.| |Representation|A representation is a *model* maintained by an Orchestrator that represents external implementations. Representations capture those aspects of external implementations that are relevant for management purposes.| |Service representation|A model that represents a *system* of one or more external implementations. Service representations model the topology of systems as *directed graphs* that consist of node representations and relationship representations.| |Node representation|Node representations are the *vertices* in a service representation graph. They represent external implementations.| |Relationship representation|Relationship representations are the *edges* in a service representation graph. They represent the interactions or other dependencies between the external implementations in a system.| |Template|Templates are *blueprints* that capture the design of external implementations. Representations are created from templates.| |Service template|A template that captures the design of a entire system or service. Service templates consist of node templates from which node representations can be created. Node templates can include requirements (and associated relationship templates) from which relationship representations can be created. Service templates can also define the actions required to create or configure external implementations based on these node and relationship representations.| |Node template|A template that captures the design of an individual component. Node templates define values for the configurable properties of components, specify observable runtime state, and define requirements and capabilities that specify how components interact. Node representations are created from node templates.| |Relationship template|A template that captures the design of *interactions* between components. Relationship representations are created from relationship templates.| ### 1.3.2 Acronyms and Abbreviations Defined in this document: - TOSCA: Topology and Orchestration Specification for Cloud Applications - CSAR: Cloud Service Archive A file format defined by OASIS TOSCA to contain TOSCA files Used by this specification: - YAML: Yet Another Markup Language The Language TOSCA uses for files - MACD: Moves, Adds, Changes, and Deletions - DSL: Domain Specific Language Used as examples: - DBMS: Database Management System - EJB: Enterprise Java Beans - SD-WAN: Software-Defined Wide Area Network - SQL: Structured Query Language - TAR: Tape Archive (a file format originally used in Unix) - VPN: Virtual Private Network - USD: United States Dollar ------- # 2 TOSCA Overview The *Topology and Orchestration Specification for Cloud Applications* (TOSCA) is a *domain-specific language* (DSL) for automating *Lifecycle Management* of large complex systems. The TOSCA language allows service designers to describe system components and their relationships by means of a service topology, and to specify the lifecycle management procedures for the creation and modification of services using orchestration processes. The combination of *topology* and *orchestration* enables not only the automation of deployment but also the automation of the complete service lifecycle management (including scaling, patching, upgrading, monitoring, etc.). The content in this section is non-normative. ## 2.1 Objectives Large systems such a cloud applications, telecommunications networks, and software services are becoming increasingly more difficult to manage. This challenge is the result of a recent technology trends such as the adoption of cloud-native architectures that build systems as collections of microservices, the disaggregation of large hardware appliances, the decoupling of hardware and software, and the adoption of edge deployments that move application functionality closer to the end-user. As a result of the above technology trends, large systems typically involve a wide variety of technologies and include components from multiple vendors. This results in management systems based on vendor-specific tools, dedicated component management systems, and special-purpose controllers, each of which manages only a small subset of the system. To make matters worse, these tools often use incompatible interfaces or data schemas, resulting in integration nightmares. As the number of components grows—because the scale of the system increases and disaggregation becomes the norm—so will the number of required management tools. Management of such systems can be greatly simplified if the creation and lifecycle management of application, infrastructure, and network services can be fully automated and supported across a variety of deployment environments. TOSCA was expressly designed to address the complexity associated with managing large systems by providing a language for specifying an information model and automating the lifecycle management of large complex systems. The goal of TOSCA is to define a language that is agnostic to specific technological and commercial ecosystems and that supports the design and operation of large systems without being tied to specific technologies or specific vendors. This enables a uniform management approach that can be used for all parts of the system and can integrate components across all layers of the technology stack. The capabilities offered by TOSCA will facilitate higher service continuity, reduce service disruption and manual mitigation, increase interoperability, avoid lock-in, and achieve the intended orchestration. Ultimately, this will benefit the consumers, developers, and providers of more and more complex and heterogeneous networks, systems, and cloud-native applications. ## 2.2 TOSCA Features and Benefits ### 2.2.1 TOSCA Is Model-Driven The TOSCA specification promotes a *model-driven management* approach, whereby TOSCA processors maintain service models (*digital twins*) for all system components under management. In a model-driven approach, all management actions are performed on service models first and then propagated to the external real-world entities by the management system. Similarly, changes to external resources are reflected into models first and then handled by management system. TOSCA's model-driven management approach is what enables its use for all Lifecycle Management Phases: information embedded in the model structure (the dependencies, connections, compositions) drives the automated processes. Specifically, it allows service models to be used: - As desired state for Moves, Adds, Changes, and Deletions (MACDs) - As context for handling faults and events using Closed Loop Automation In addition, changing or augmenting the model also automatically adapts the LCM / orchestration behavior. Without the context provided by service models, lifecycle management cannot be fully automated. ### 2.2.2 TOSCA Models Are Graphs TOSCA models systems as graphs, where the vertices represent the components of the system and the edges represents relationships, dependencies, and other interactions between these components. The use of graphs enables *declarative* orchestration, where system designers can simply create descriptions ("models") of their systems, and delegate to the orchestrator the task of translating these descriptions into the commands required to realize the systems being described. The use of graphs enables this as follows: - Relationships in a TOSCA graph encode dependencies that allow an orchestrator to automatically determine the *sequencing* between the management operations on invoked on various components in the system, thereby avoiding the need for human-defined workflows. Implementing lifecycle or other management operations on the service can be achieved by traversing the graph. - Relationships in a TOSCA graph allow an orchestrator to automatically determine which system components may be affected by a component failure or by a change to an external resource. The orchestrator can then determine corrective actions that restore the system as a whole to its nominal state, rather than just fixing individual components. Declarative management is often also referred to as *desired state* or *intent-based* orchestration. ### 2.2.3 TOSCA Promotes Reuse and Modularity TOSCA models are based on *service templates* that are created by service designers. Service templates consist of node templates and relationship templates that have associated node types and relationship types. Types in TOSCA represent reusable components that can be used as building blocks from which services are constructed, thereby promoting modularity and reuse. In addition, TOSCA allows modular designs whereby service templates describe only parts of a system rather than a complete end-to-end system definition. Composition of partial system descriptions into complete system models can be done by an orchestrator at deployment time. This enables automation of placement decisions, resource allocation, and system integration. TOSCA's modularity features allow some service design decisions to be made by an orchestrator at deployment time rather than by a service designer at service design time. TOSCA also allows for the definition of abstract components that hide technology and vendor-specific implementation details, via mechanisms such as derivation of types and substitution of nodes. The choice of how to *implement* abstract components can be left to the orchestrator at deployment time. This further increases the value of TOSCA as a technology and vendor-neutral technology language orchestration. TOSCA supports the use of *policies* to guide the service design decisions made by orchestrators at deployment time. ### 2.2.4 TOSCA Is Domain-Independent Since the fundamental abstraction defined by the TOSCA language is a *graph*, TOSCA is not tied to any specific application domain. For example, TOSCA can be used to specify automated lifecycle management of the following: - Infrastructure-as-a-Service Clouds: automate the deployment and management of workloads in IaaS clouds such as OpenStack, Amazon Web Services, Microsoft Azure, Google Cloud, and others. - Cloud-Native Applications: deploy containerized applications, micro-services, and service meshes, for example by interfacing to orchestration platforms such as Kubernetes. - Network Function Virtualization: define the management of Virtual Network Functions and their composition into complex network services. - Software Defined Networking: support on-demand creation of network services (for example SD-WAN). - Functions-as-a-Service: define software applications without any deployment or operational considerations. - IoT and Edge computing: deploy many very similar copies of a service at the network edge. - Process Automation: support open and interoperable process control architectures. This list is by no means intended to be exhaustive and only serves to demonstrate the breadth of application domains that can benefit from TOSCA's automated lifecycle management capabilities. ## 2.3 TOSCA Core Concepts As stated above, the TOSCA language assumes a *model-driven* management paradigm. Using model-driven management, a model representing the managed external components is maintained and all management operations are performed on this model first and any resulting changes to the model are then propagated to the external components. Similarly, any status changes or errors experienced by the external components are reflected in the model first before they are handled by the management system. The model maintained by the management system must capture all aspects of the external components that are relevant for the purpose of managing those components. External components under management can consist of physical resources deployed in the real world as well as logical or virtual components provisioned or configured on those resources. In the context of TOSCA, we will refer to the physical or virtual components under management as **external implementations**, and we will refer to the models as **representations**. Note that the TOSCA language does not standardize any object models or schemas for representations. It presumes the existence of such models, but the model details are implementation specific. A model-driven management system must include a component that is responsible for keeping the *representations* and the *external implementations* synchronized. In the context of this specification, we will refer to this component as the **orchestrator**. An orchestrator may perform this synchronization task based on workflows, policies, or other mechanisms that are defined using statements expressed in the TOSCA language, in which case we will refer to the component as a **TOSCA orchestrator**. Alternatively, an orchestrator may also perform this task based on domain-specific knowledge that is built-in to the orchestrator rather than being defined using TOSCA. This specification allows for either approach. The following diagram shows how external implementations are modeled using representations, and how the Orchestrator synchronizes the two. **Figure 1: Representations and Implementations**  TOSCA representations don't just track individual components and their management aspects; they also capture how the various components interact, with the goal of providing complete system functionality. TOSCA accomplishes this by modeling the *topology* of systems as *graphs* where nodes in the graph represent the components under management and vertices in the graph represent containment, dependencies, interactions, or other relationships between these components. In this specification, we use the term **service representation** to refer to a graph that models the topology of an entire system or subsystem, and we use the terms **node representation** and **relationship representation** respectively to model the nodes and vertices in a service representation graph. Information about how node and relationship representations are organized in service representation graphs is captured in designs (a.k.a blueprints) that are created by service designers and expressed in the TOSCA language. In this specification, we refer to those designs as **service templates** and we use the term **resolver** to refer to the management component that *instantiates* service representations based on *service templates*. TOSCA *service templates* define service elements and their relationships which results in the *service representations* to be created as graphs. Service templates consist of **node templates** from which node representations are created, and **relationship templates** from which relationship representations are created. Note that while TOSCA does not standardize representations, it does standardize the grammar for defining templates. The use of templates supports reuse of service designs while at the same time allowing for service-specific variability. Specifically, node templates and relationship templates can use **TOSCA functions** to specify that configuration values need to be provided as **template inputs** to each deployment, or that configuration values need to be retrieved at deployment time from other node or relationship representations in the service representation graph. At deployment time, TOSCA resolvers evaluate these functions to generate the values to be used when creating new service representations. TOSCA also includes grammar for creating multiple node representations from the same node template and for creating multiple relationship representations from the same relationship template. TOSCA supports modular designs where different deployments can combine sub-system representations created from different service templates into deployment-specific system representations. The following diagram shows how representations are created from templates by a resolver: **Figure 2: TOSCA Templates and Representations**  To allow for *design-time validation* of service templates, all TOSCA templates defined by those service templates have associated **TOSCA types**. TOSCA types define *schemas* and *constraints* with which TOSCA templates have to comply. For example, a *TOSCA node type* defines configurable properties that must be provided for the associated component, it defines the runtime attributes that are expected to be available for the component, and it specifies allowed and required interactions with other components. A TOSCA-based management system must include a **TOSCA parser/validator** that checks if the templates used in a TOSCA file are valid for the types with which they are associated. This allows many kinds of errors to be flagged at service *design time* rather than at service *deployment time*. The following diagram shows how templates are created from and validated against TOSCA type definitions: **Figure 3: TOSCA Types and TOSCA Templates**  The use of types in TOSCA also provides the additional benefits of abstraction, information hiding, and reuse. TOSCA types can be organized in a *type hierarchy* where one or more type definitions can inherit from another type, each derived type may then be refined. This promotes reuse. The base type may be more generic and the derived types may be more concrete which promotes abstraction. **TOSCA node types** and **TOSCA relationship types** define an externally visible *management façade* for entities of that type while hiding internal implementation details. This management façade defines interfaces that can be used by an orchestrator to interact with the external implementations represented by the entity. When node types and relationship types are packaged together with internal implementation artifacts for their interfaces, they become *reusable building blocks* that can greatly facilitate the creation of end-to-end services. TOSCA types that define such reusable building blocks are typically organized in domain-specific **TOSCA profiles**. The following figure summarizes the various concepts introduced in this section. When a TOSCA implementation implements multiple TOSCA processing modules such as parsing, validating, and resolving, such an implementation is commonly referred to as a **TOSCA processor**. **Figure 4: Summary of Core TOSCA Concepts**  Note that this diagram is only intended to highlight concepts used in this specification, not to suggest software architectures or implementations. Nor is this diagram intended to be comprehensive or exclusive. Other kinds of processors and modules may qualify as implementations of TOSCA, for example: - TOSCA translator: A tool that translates TOSCA files into documents that use another language, such as Kubernetes Helm charts or Amazon CloudFormation templates. - TOSCA template generator: A tool that generates a TOSCA file. An example of generator is a modeling tool capable of generating or editing a system design expressed using TOSCA. ## 2.4 Using TOSCA ### 2.4.1 TOSCA Files TOSCA files are files describing TOSCA service templates, TOSCA types, or a combination thereof. ### 2.4.2 Archive Format for Cloud Applications In order to support in a certain environment the execution and management of the lifecycle of a cloud application, all corresponding artifacts have to be available in that environment. This means that beside the TOSCA file of the cloud application, the deployment artifacts and implementation artifacts have to be available in that environment. To ease the task of ensuring the availability of all of these, this specification defines a corresponding archive format called CSAR (Cloud Service ARchive). A CSAR is a container file, i.e. it contains multiple files of possibly different file types. These files are typically organized in several subdirectories, each of which contains related files (and possibly other subdirectories etc.). The organization into subdirectories and their content is specific for a particular cloud application. CSARs are zip or tar files, typically compressed. A CSAR may contain a file called `TOSCA.meta` that describes the organization of the CSAR. ------- # 3 TOSCA Language Abstractions The TOSCA language introduces a YAML-based grammar for automating the lifecycle management of application, infrastructure, and network services. The language defines a *metamodel* for specifying both the structure of a service as well as its management aspects. Using TOSCA statements expressed in a TOSCA file, service designers create a *service template* that defines the *structure* of a service. *Interfaces, operations, and workflows* define how service elements can be created and terminated as well as how they can be managed during their whole lifetimes. Policies specify operational behavior of the service such as quality-of-service objectives, performance objectives, and security constraints, and allow for closed-loop automation. The content in this section is non-normative. ## 3.1 Service Templates, Node Templates, and Relationship Templates Within a TOSCA file, a **service template** defines the topology model of a service as a directed graph. Each node in this graph is represented by a **node template**. A node template specifies the presence of an entity of a specific **node type** as a component of a service. A node type defines the semantics of such a component, including the configurable properties of the component (via **property definitions**), its runtime state (via **attribute definitions**) and the operations (via **interface definitions**) available to manipulate the component. In a service template, a node template assigns values to the properties defined in the corresponding node type. An orchestrator updates attribute values as a result of performing lifecycle management operations or in response to notifications about changes in component state. For example, consider a service that consists of an some computing application, a database and some computing resource to run them on. A service template defining that service would include one node template of the node type for the particular software application, another node template of node type *database management system* or a more specific derivative (MariaDB,perhaps), and a third node template of node type *compute* or more likely a more specific derivative. The DBMS node type defines properties like the IP address of an instance of this type, an operation for installing the database application with the corresponding IP address, and an operation for shutting down an instance of this DBMS. A constraint in the node template can specify a range of IP addresses available when making a concrete application server available. Node templates may include one or more **relationship templates** to other node templates in the service template. These relationship templates represent the edges in the service topology graph and model dependencies and other interactions between components. Note that in this specification, relationship templates are more frequently referred to as **requirements** for reasons that will be explained below. Relationship templates in TOSCA are unidirectional: the node template that includes the relationship template is implicitly defined as the **source node** of that relationship template and the relationship template explicitly specifies its **target node**. Each relationship template refers to a **relationship type** that defines the semantics of the relationship. Just like node types, relationship types define properties, attributes, and interfaces. Node types and relationship types are typically defined separately for reuse purposes and organized into profiles. In the example above, a relationship can be established from the application server node template to the database node template with the meaning *depends on*, and from both the application and DBMS node templates to the compute node template with meaning *deployed on*. ## 3.2 Requirements and Capabilities We discussed earlier how relationship templates are used to link node templates together into a service topology graph. However, it may not always be possible to define all node templates for a given service topology within a single service template. For example, modular design practices may dictate that different service sub-components be modelled using separate service templates. This may result in relationships across multiple service templates. Additionally, relationships may need to target components that already exist and do not need to be instantiated by an orchestrator. For example, relationships may reference physical resources that are managed in a resource inventory. Service templates may not include node templates for these resources. TOSCA accommodates both service template internal and external relationships using **requirements** and **capabilities** of node templates. Requirements express that a component depends on a feature provided by another component, or that the component has certain requirements against the hosting environment such as for the allocation of certain resources or the enablement of a specific mode of operation. Capabilities represent features exposed by components that can be targeted by requirements of other components. A requirement defined in one node template is fulfilled by establishing a relationship to a corresponding capability defined in a second node template. If a requirement explicitly specifies a target node template defined in the same service template, it acts as a [relationship template](#relationship-template). A requirement that does not explicitly specify a target node template is referred to as a **dangling requirement**. For simplicity, this specification uses the term *requirement* for both relationship templates and dangling requirements. All mandatory dangling requirements must be fulfilled by the TOSCA processor at service deployment time. While dangling requirements are defined in the context of *node templates*, fulfilling dangling requirements is done in the context of *node representations*. This means that when finding candidates for fulfilling a dangling requirement, the TOSCA processor must consider node representations rather than the templates from which these representations were created. When fulfilling requirements, template directives to the TOSCA processor can be used to specify if the target candidates are template-internal node representations, or external representations created from multiple service templates, or representations for external resources managed in an inventory. Thus, requirement fulfillment may result in relationships that are established across service template boundaries. Requirements and capabilities are modelled by annotating node types with **requirement definitions** and **capability definitions** respectively. Capability definitions themselves have associated **capability types** that are defined as reusable entities so that those definitions can be used in the context of several node types. Just like node types and relationship types, capability types can define properties and attributes. Requirement definitions are effectively *relationship definitions* that specify the relationship type that will be used when creating the relationship that fulfils the requirement. The following figure summarizes the various TOSCA abstractions used for defining requirements and capabilities: **Figure 5: Requirements and Capabilities**  ## 3.3 Decomposition of Node Representations TOSCA provides support for decomposing service components using its **substitution mapping** feature. This feature allows for the definition of *abstract* service designs that consist of generic components that are largely independent of specific technologies or vendor implementations. Technology or vendor-specific implementation details can be defined for each generic component using *substituting* service templates that describe the internals of that component. For example, a service template for a business application that is hosted on an application server tier might focus on defining the structure and manageability behavior of the business application itself. The internals of the application server tier hosting the application can be provided in a separate service template built by another vendor specialized in deploying and managing application servers. This approach enables separation of concerns as well as re-use of common infrastructure templates. **Figure 6: Node Decomposition**  From the point of view of a service template (e.g. the business application service template from the example above) that uses another service template, the other service template (e.g. the application server tier) *looks* just like a node template. During deployment, however, the node representation created from this node template can be *substituted* by a service created from the second service template if it exposes the same external *façade* (i.e. properties, capabilities, requirements, etc.) as the node for which it is a substitution. Thus, a substitution by any service template that has the same *façade* as the substituted node becomes possible, allowing for a hierarchical decomposition of service representations. This concept also allows for providing alternative substitutions that can be selected by a TOSCA processor at service deployment time. For example there might exist two service templates, one for a single node application server tier and another for a clustered application server tier, and the appropriate option can be selected on a deployment-by-deployment basis. ## 3.4 Interfaces, Operations, and Artifacts Both node types and relationship types may define lifecycle **operations** that define the actions an orchestration engine can invoke when instantiating a service from a service template or when managing a deployed service. 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 allow an orchestration engine to start or stop the software component. Operations that are related to the same management mission (e.g. lifecycle management) are grouped together in **interface definitions** in node and relationship types. Just like other TOSCA entities, interfaces have a corresponding **interface type** that defines the group of operations that are part of the interface, the input parameters that are required by those operations, and any output parameters returned by the operations. Interface types can also define **notifications** that represent external events that are generated by the external implementations and received by the orchestrator. The implementations of interface operations can be provided as TOSCA **artifacts**. An artifact represents the content needed to provide an implementation for an interface operation. A TOSCA artifact could be an executable (e.g. a script, an executable program, an image), a configuration file or data file, or something that might be needed so that another executable can run (e.g. a library). Artifacts can be of different types, for example Ansible playbooks or Python scripts. The content of an artifact depends on its **artifact type**. Typically, descriptive metadata (such as properties) will also be provided along with the artifact. This metadata might be needed by an orchestrator to properly process the artifact, for example by describing the appropriate execution environment. ## 3.5 Workflows A deployed service is an instance of a service template. More precisely, a service is deployed by first creating a *service representation* based on the *service template* describing the service and then *orchestrating* the *external implementations* modelled by those representations. If TOSCA orchestration is used, the external implementations are created by running workflows that invoke interface operations defined in the types of the nodes and relationships in the representation graph. TOSCA workflows can often be generated automatically by the orchestrator by using the relationships in the service representation graph to determine the order in which external implementations must be created. 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). Interface operations invoked by workflows must use actual values for the various properties in the node templates and relationship templates in the service template. These values are tracked in the node representations and relationship representations in the service representation graph. They can be provided as inputs passed in by users as triggered by human interactions with the TOSCA processor. Alternatively, the templates can specify default values for some properties, or use TOSCA functions to retrieve those values from other entities in the service representation graph. For example, the application server node template will be instantiated by installing an actual application server at a concrete IP address considering the specified range of IP addresses. Next, the process engine node template will be instantiated by installing a concrete process engine on that application server (as indicated by the "hosted-on" relationship template). Finally, the process model node template will be instantiated by deploying the process model on that process engine (as indicated by the "deployed-on" relationship template). ## 3.6 Policies Non-functional behavior or quality-of-services are defined in TOSCA by means of **policies**. A policy can express such diverse things like monitoring behavior, payment conditions, scalability, or continuous availability, for example. A node template can be associated with a set of policies collectively expressing the non-functional behavior or quality-of-services that each instance of the node template will expose. Each policy specifies the actual properties of the non-functional behavior, like the concrete payment information (payment period, currency, amount etc.) about the individual instances of the node template. These properties are defined by a **policy type**. Policy types might be defined in hierarchies to properly reflect the structure of non-functional behavior or quality-of-services in particular domains. Furthermore, a policy type might be associated with a set of node types the non-functional behavior or quality-of-service it describes. **Policy templates** provide actual values of properties of the types defined by policy types. For example, a policy template for monthly payments for customers located in the USA will set the "payment-period" property to "monthly" and the "currency" property to "USD", leaving the "amount" property open. The "amount" property will be set when the corresponding policy template is used for a policy within a node template. Thus, a policy template defines the invariant properties of a policy, while the policy sets the variant properties resulting from the actual usage of a policy template in a node template. ------- # 4 TOSCA Operational Model The content in this section is normative unless otherwise labeled except for: - the examples - references (unless they are labelled as normative) TOSCA is designed to support all three phases of the service lifecycle: 1. **Day 0—Service Design**: Service designers use TOSCA to model services as topology graphs that consist of nodes and relationships. Nodes model the components of which a service is composed, and relationships model dependencies between these service components. 2. **Day 1—Service Deployment**: TOSCA can also be used to define mechanisms for deploying TOSCA service topologies on external platforms. 3. **Day 2—Service Management**: TOSCA can enable run-time management of services by providing support for updating and/or upgrading deployed services and by providing service assurance functionality. This section presents a TOSCA *functional architecture* and an associated *operational model* that supports the three service lifecycle phases outlined above. Note that this functional architecture is not intended to prescribe how TOSCA must be implemented. Instead, it aims to provide users of TOSCA with a mental model of how TOSCA implementations are expected to process TOSCA files. Note that it is not mandatory for compliant TOSCA implementations to four kinds of TOSCA abstractions defined in Section 2.4 support all three service lifecycle phases. Some implementations may use TOSCA only for service design and delegate orchestration and ongoing lifecycle management functionality to external (non-TOSCA) orchestrators. Other implementations may decide to use TOSCA for all three phases of the service lifecycle. However, a complete architecture must anticipate all three lifecycle phases and must clearly distinguish between the different types of TOSCA abstractions introduced in the section [TOSCA language abstractions](#tosca-language-abstractions). ## 4.1 TOSCA Functional Architecture The following Figure shows the TOSCA functional architecture defined in this section. It illustrates how the various TOSCA entities are used by the different functional blocks and how they are related. **Figure 7: TOSCA Functional Architecture**  The functional architecture defines the following three blocks: 1. **TOSCA Processor**: This functional block defines functionality that must be provided by all TOSCA implementations. TOSCA processors convert TOSCA-based service definitions into service representations that can be processed by an Orchestrator. 2. **Orchestrator**: This functional block creates external implementations on various resource platforms based on the service representations created by a TOSCA processor. The orchestration functionality can itself be defined using TOSCA or can be provided by external (non-TOSCA) orchestration platforms. 3. **Platform**: In the context of a TOSCA architecture, platforms represent external cloud, networking, or other infrastructure resources on top of which service entities can be created. The remainder of this section describes each of these functional blocks in more detail. ## 4.2 TOSCA Processor At the core of a compliant TOSCA implementation is a TOSCA Processor that can create service representations from TOSCA service templates. A TOSCA Processor contains the following functional blocks: ### 4.2.1 Parser A TOSCA parser performs the following functions: - Accepts a single TOSCA file plus imported TOSCA files (files without a `service_template`) - Can (optionally) import these files from one or more repositories, either individually or as complete profiles - Outputs valid normalized node templates. Note that normalized node templates may include unresolved (*dangling*) requirements. ### 4.2.2 Resolver A resolver creates service representations based on normalized service templates. It performs the following functions: 1. Creating Node Representations based on Normalized Node Templates. - Either one-to-one or one-to-many if multiplicity is involved. - Node templates with a "select" directive create a node in the local representation graph that is a reference to the selected node (from the local or a remote representation graph). - Node templates with a "substitute" directive create a node in the local representation graph that is associated to a remote representation graph created from the substitution template. - The resolver assigns values to node properties and attributes in node representations based on values or functions defined in the corresponding node templates. - Some property and attribute values cannot be initialized since they either depend on other uninitialized properties or attributes or need to access other node representations via relationships that have not been yet initialized. 2. Creating Relationships that Connect Node Representations - Some relationships can be created directly based on target node templates specified in node template requirements. - Other relationships are created by fulfilling dangling requirements - If a requirement uses a node_filter that refers to uninitialized properties or attributes, then the fulfillment of this requirement is postponed until all referred properties or attributes are initialized. - A circular dependency signifies a erroneous template and shall report an error - After a relationship is created, properties and attributes that depend on it to be initialized will be initialized. - At the end of this process all mandatory requirements must be satisfied and all relationships are added to the representation graph. An unsatisfied non-optional requirement results in an error. 3. Substitution Mapping - When substitution is directed for a node, the resolver creates a new service representation based on the substituting template, basically creating a service that represents the internals of the substituted node. - The substituting service is initialized from the properties of the substituted node and the workflows of the substituting service act as operations for the substituted node (that is, the behavior of the node is substituted by the substituting service). - This is defined via substitution mapping rules. ## 4.3 Orchestrator An orchestrator performs the following actions: - (Continuously) turns node representations into one or more node implementations - (Continuously) updates node representation attribute values (error if they do not adhere to TOSCA type validation clauses or property definition validation clauses) - (Continuously) reactivates the resolver: outputs may change attribute values, which can require refulfillment of dangling requirements or resubsitution of substituted nodes. - (Optionally) changes the node representations themselves for day 2 transformations. ## 4.4 Changes in the Representation Graph During the lifetime of a service there can be several actions or events that change the representation graph of the running service. We can identify the several situations that mandate the change of the representation graph, for example: - Update: - The service input values have changed and need to be re-evaluated while the service is running. - Upgrade: - The service template has changed and needs to be re-evaluated while the service is running. - Runtime failures: - Nodes or relationships in the representation graph have failed and need to be recreated or healed while the service is running. - Change in dependencies - External nodes or relationships to external nodes have failed and new relationships to external nodes need to be created (i.e. external requirements need to be fulfilled again) while the service is running. For the service to reach the new desired runtime state, operations that are associated with the creation, deletion, and modification of nodes and relationships in the representation graph need to be performed. We can visualize (and the orchestrator can perform) these restorative actions via graph traversals on the "old" and "new" representation graph. First let's categorize the nodes and relationships in the "old" and "new" representation graphs in the following four categories: - Unchanged: These are nodes and relationships that appear in both the "old" and "new" representation graphs and have the same property values. Given that a template can be upgraded, we correlate the same nodes and relationships via their symbolic node names and requirement names. - Modified: These are nodes and relationships that appear in both the "old" and "new" representation graphs and have different property values. - Obsolete: These are nodes and relationships that appear in the "old" representation graph but not in the "new" representation graph. - Novel: These are nodes and relationships that do not appear in the "old" representation graph but appear in the "new" representation graph. We then perform deletions of the obsolete nodes by traversing the representation graph in reverse dependency order as follows: - We start in parallel with all nodes that have no incoming dependency relationship - we perform operations associated with deleting on all adjacent relationships to this node that are in the "obsolete" category. - we perform operations associated with deleting on the node itself if it is in the "obsolete" category. - we move to nodes that have no incoming dependency relationship to nodes that have not been processed yet. After we have processed the deletion of the obsolete elements we traverse the "new" representation graph in dependency order to perform the modifications and creations: - we start in parallel with the nodes that have no outgoing dependency relationship - we perform operations associated with creation resp. modification on the node itself if it is in the "novel" resp. "modified" category - we perform operations associated with creation resp. modification on all adjacent relationships in the "novel" resp. "modified" category if the node on the other side of the relationship has been processed. - we move to nodes that have no outgoing dependency relationship to nodes that have not been processed yet. After this we can consider the service to be in the new desired runtime state, and the "old" representation graph can be discarded and the "new" representation graph becomes the current representation graph of the service. Note that this graph traversal behavior should be associated with the relevant interface types that are defined in a TOSCA profile, where it should be specified which relationship types form the dependency relationships, which operation(s) are associated with the deletion, modification, and creation of the nodes and relationships when the representation graph changes. ------- # 5 TOSCA Grammar Overview The content in this section is normative unless otherwise labeled except for: - the examples - references (unless they are labelled as normative) ## 5.1 TOSCA Modeling Concepts This section defines concepts used in support of the modeling functionality of the TOSCA Version 2.0 specification. Specifically, it introduces grammar for defining TOSCA types and templates as defined in [the Chapter TOSCA Core Concepts](#tosca-core-concepts), it introduces the concepts of entity definitions and entity assignments, and presents rules for type derivation and entity refinement. ### 5.1.1 Type Definitions and Entity Definitions TOSCA **templates** are defined in TOSCA files and expressed using statements in the TOSCA language. All TOSCA templates are *typed* using TOSCA types that are also defined in TOSCA files and expressed in the TOSCA language. Not only do types promote reuse, they also simplify the design of TOSCA templates by allowing relevant TOSCA entities to use and/or modify definitions already specified in the types. TOSCA **type definitions** consist of pairs of keynames and associated values that specify information relevant to the type. While all TOSCA types share a number of common keynames, each type definition has its own set of keynames with their own syntax and semantics. TOSCA supports *node types*, *relationship types*, *capability types*, *interface types*, *artifact types*, *policy types*, *group types*, and *data types*. Some keynames in TOSCA type definitions are used to specify TOSCA **entity definitions** that *declare* the presence of those entities in the context of the type being defined. For example, most TOSCA type definitions include *property definitions* and *attribute definitions*. Node types and relationship types also include *interface definitions*, and node types have *requirement definitions* and *capability definitions*. Interface types can include *parameter definitions* that specify required inputs and expected outputs for interface operations and notifications. Just like type definitions, entity definitions consist of pairs of keynames and values. Each entity definition has it own syntax, semantics and set of keynames, but all entity definitions share a `type` keyname that references the TOSCA type of the entity being defined. Other keynames in entity definitions are used to further define or refine definitions already specified in the corresponding entity type. TOSCA supports *capability definitions*, *requirement definitions*, *interface definitions*, *policy definitions*, *group definitions*, *property definitions*, *attribute definitions*, and *parameter definitions*. ### 5.1.2 Templates and Entity Assignments The service templates introduced in the [section on Reuse and Modularity](#tosca-promotes-reuse-and-modularity) are defined in TOSCA files and expressed using statements in the TOSCA language. Service templates define directed graphs that consist of *node templates* and *requirements*. Node templates specify a node type used for the template and then add additional information using pairs of keynames and associated values. Service templates may include other templates as well such as relationship templates, groups, policies etc. Node types specified in node templates will typically include definition of entities, many node templates will use keynames to specify additional information for those entity definitions. Such information is referred to as an **entity assignment**. In general for each entity definition in the type of a template, the template can include a corresponding entity assignment that provides template-specific information about the entity. For example, node templates can include property assignments that assign template-specific values for the properties defined using *property definitions* in the *node type*. Property assignments can be provided as fixed values, but more often they will be specified using a TOSCA function that retrieve input values or that retrieve property or attribute values from other entities in a service representation graph. Entity assignments make sure that the service template can be used to generate a complete representation of the system under management. ### 5.1.3 Type Derivation, Augmentation, and Refinement The TOSCA type system supports *inheritance* which means that types can be derived from a parent type. A parent type can in turn be derived from its own parent type. There is no limit to the depth of a chain of derivations. Inheritance is a useful feature in support of abstraction. For example, base node types can be used to define generic components without specifying technology or vendor-specific details about those components. Concrete derived node types can the be used to define technology-specific or vendor-specific specializations of the generic types. The TOSCA specification includes *type derivation rules* that describe which keyname definitions are inherited from the parent type and which definitions are *intrinsic* to the type declaration and are not inherited. An example of an intrinsic definition is version, all type definitions include a `version` keyname the value of which is not inherited from a parent type. Except for keynames that are explicitly flagged as *intrinsic* to each type definition, derived types inherit all the definitions of their parent type. Specifically, derived types inherit all *entity definitions* from their parent. In addition, these entity definitions can be expanded or modified. - Expansion of entity definitions is done through **entity augmentation**. Derived types use entity augmentation to *add* entity definitions to those already defined in the parent type. Augmentation rules pertaining to an entity describe how derived types can add to the entity definitions in the inherited parent type. - Modification of entity definitions is done through **entity refinement**. Derived types use entity refinement to further constrain or otherwise *specialize* entities already defined in the parent type. Refinement rules pertaining to an entity describe how such entity definitions that are inherited from the parent type during a type derivation can be expanded or modified. The main reason for augmentation and refinement rules is to create a framework useful for a consistent TOSCA type profile creation. The intuitive idea is that a derived type follows to a large extent the structure and behavior of a parent type, otherwise it would be better to define a new "not derived" type. The guideline regarding the derivation rules is that a node of a derived type should be usable instead of a node of the parent type during the selection and substitution mechanisms. These two mechanisms are used by TOSCA templates to connect to TOSCA nodes and services defined by other TOSCA templates: - The selection mechanism allows a node representation created a-priori from another service template to be selected for usage (i.e., building relationships) by node representations created from the current TOSCA template. - The substitution mechanism allows a node representation to be decomposed by a service created simultaneously from a substituting template. ### 5.1.4 TOSCA File Reuse A single TOSCA file may be reused by including it in one or more other TOSCA file. Each file may be separately maintained and use it's own naming scheme. The resolution of naming scheme conflicts is discussed later in this document. ## 5.2 Mandatory Keynames The TOSCA metamodel includes complex definitions used in types (e.g., node types, relationship types, capability types, data types, etc.), definitions and refinements (e.g., requirement definitions, capability definitions, property and parameter definitions, etc.) and templates (e.g., service template, node template, etc.) all of which include their own list of reserved keynames that are sometimes marked as **mandatory**. If a keyname is marked as mandatory it MUST be defined in that particular definition context. In some definitions, certain keynames may be mandatory depending on the value of other keynames in the definition. In that case, the keyname will be marked as **conditional** and the condition will be explained in the description column. Note that in the context of type definitions, types may be used to derive other types, and keyname definitions MAY be inherited from parent types (according to the derivation rules of that type entity). A derived type does not have to provide a keyname definition if this has already been defined in a parent type. ## 5.3 Common Keynames Except where explicitly noted, all multi-line TOSCA grammar elements support the following keynames: |Keyname|Mandatory|Type|Description| | :---- | :------ | :---- | :------ | |`metadata`|no|map of [metadata](#metadata)|Defines a section used to declare additional information about the element being defined.| |`description`|no|str|Declares a [description](#description) for the TOSCA element being defined.| Grammar for these keynames is described here and may not be repeated for each entity definition. ### 5.3.1 `metadata` This optional keyname is used to associate domain-specific metadata with a TOSCA element. The `metadata` keyname allows a declaration of a map of keynames with values that can use all types supported by the [\[YAML-1.2\] chapter 10 recommended schemas](https://yaml.org/spec/1.2.2/#chapter-10-recommended-schemas) as follows: ```yaml metadata: : : ... ``` Specifically, the following YAML types can be used for metadata values: "!!map", "!!seq", "!!str", "!!null", "!!bool", "!!int", "!!float". The following shows an example that uses `metadata` to track revision status of a TOSCA file: ```yaml metadata: creation-date: 2024-04-14 date-updated: 2024-05-01 status: developmental ``` Data provided within metadata, wherever it appears, MAY be ignored by TOSCA Orchestrators and SHOULD NOT affect runtime behavior. ### 5.3.2 `description` This optional keyname provides a means to include single or multiline descriptions within a TOSCA element as a *YAML string value*, as follows: ```yaml description: ``` Standard YAML block and flow formats are supported for the description string. Simple descriptions are treated as a single literal that includes the entire contents of the line that immediately follows the description keyname: ```yaml description: This is an example of a single line description (no folding). ``` The following shows a multiline flow example: ```yaml description: "A multiline description using a quoted string" ``` The YAML *folded* format may also be used for multiline descriptions, which *folds* line breaks as space characters: ```yaml 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. ``` # 6 TOSCA File Definition The content in this section is normative unless otherwise labeled except: - the examples - references unless labelled as normative. A TOSCA file can contain definitions of reusable building blocks for use in cloud applications, complete models of cloud applications, or both. This section describes the top-level TOSCA keynames—along with their grammars—that are allowed to appear in a TOSCA file. The major entities that can be defined in a TOSCA file are depicted in Figure 8. **Figure 8: Structural Elements of a TOSCA File**  ## 6.1 Keynames The following is the list of recognized keynames for a TOSCA file: |Keyname|Mandatory|Type|Description| | :---- | :------ | :---- | :------ | |`tosca_definitions_version`|yes|str|Defines the [version of the TOSCA specification](#tosca-definitions-version) used in this TOSCA file.| |`description`|no|str|Declares a [description](#description) for this TOSCA file and its contents.| |`metadata`|no|map of [metadata](#metadata)|Defines a section used to declare additional information. Domain-specific TOSCA profile specifications may define keynames that are mandatory for their implementations.| |`dsl_definitions`|no|N/A|Defines [reusable YAML aliases](#dsl-definitions) (i.e., YAML alias anchors) for use throughout this TOSCA file.| |`artifact_types`|no|map of [artifact types](#artifact-type)|Declares a map of artifact type definitions for use in this TOSCA file and/or external TOSCA files.| |`data_types`|no|map of [data types](#data_types)|Declares a map of TOSCA data type definitions for use in this TOSCA file and/or external TOSCA files.| |`capability_types`|no|map of [capability types](#capability-types)|Declares a map of capability type definitions for use in this TOSCA file and/or external TOSCA files.| |`interface_types`|no|map of [interface types](#interface-types)|Declares a map of interface type definitions for use in this TOSCA file and/or external TOSCA files.| |`relationship_types`|no|map of [relationship types](#relationship-type)|Declares a map of relationship type definitions for use in this TOSCA file and/or external TOSCA files.| |`node_types`|no|map of [node types](#node-type)|Declares a map of node type definitions for use in this TOSCA file and/or external TOSCA files.| |`group_types`|no|map of [group types](#group-types)|Declares a map of group type definitions for use in this TOSCA file and/or external TOSCA files.| |`policy_types`|no|map of [policy types](#policy-types)|Declares a map of policy type definitions for use in this TOSCA file and/or external TOSCA files.| |`repositories`|no|map of [repository definitions](#repository-definitions)|Declares a map of external repositories that contain artifacts that are referenced in this TOSCA file along with the addresses used to connect to them in order to retrieve the artifacts.| |`functions`|no|map of [function definitions](#function-definitions)|Declares a map of function definitions for use in this TOSCA file and/or external TOSCA files.| |`profile`|no|str|The [profile](#profiles) name that can be used by other TOSCA files to import the type definitions in this document.| |`imports`|no|seq of [import definitions](#import-definitions)|Declares a list of import statements pointing to external TOSCA files or well-known profiles. For example, these may be file locations or URIs relative to the TOSCA file within the same TOSCA CSAR file.| |`service_template`|no|[service template definition](#service-template-definition)|Defines a template from which to create a mode/representation of an application or service. Service templates consist of node templates that represent the application's or service's components, as well as relationship templates representing relations between these components.| The following rules apply: - The key `tosca_definitions_version` MUST be the first line of each TOSCA file. - TOSCA files do not have to define a `service_template` and MAY contain simply type definitions, repository definitions, function definitions, or other import statements and be imported for use in other TOSCA files. However, a TOSCA file that defines a `profile` MUST NOT define a `service_template`. The remainder of this chapter provides detailed descriptions of the keynames and associated grammars used in a TOSCA file definition. ## 6.2 TOSCA Definitions Version The mandatory `tosca_definitions_version` keyname provides a means to specify the TOSCA version used within the TOSCA file as follows: ```yaml tosca_definitions_version: ``` It is an indicator for the version of the TOSCA grammar that MUST be used to parse the remainder of the TOSCA file. TOSCA uses the following version strings for the various revisions of the TOSCA specification: | Version String | TOSCA Specification | |-----------------------|------------------------------------------| | tosca_2_0 | TOSCA Version 2.0 | | tosca_simple_yaml_1_3 | TOSCA Simple Profile in YAML Version 1.3 | | tosca_simple_yaml_1_2 | TOSCA Simple Profile in YAML Version 1.2 | | tosca_simple_yaml_1_1 | TOSCA Simple Profile in YAML Version 1.1 | | tosca_simple_yaml_1_0 | TOSCA Simple Profile in YAML Version 1.0 | The version for this specification is `tosca_2_0`. The following shows an example `tosca_definitions_version` in a TOSCA file created using the TOSCA Version 2.0 specification: ```yaml tosca_definitions_version: tosca_2_0 ``` Note that it is not mandatory for TOSCA Version 2.0 implementations to support older versions of the TOSCA specifications. ## 6.3 DSL Definitions The optional `dsl_definitions` keyname provides a section where template designers can define YAML-style macros for use elsewhere in the TOSCA file. DSL definitions use the following grammar: ```yaml dsl_definitions: ... ``` The grammar for each `` is as follows: ```yaml : & ``` where `` defines a set of reusable YAML definitions (the ``) for which `` can be used as an alias elsewhere in the document. An example of defining and using a DSL definition, a YAML anchor, is given in [`scalar`](#scalar). ## 6.4 Type Definitions TOSCA provides a type system to describe reusable building blocks to construct a service template (i.e. for the nodes, relationship, group and policy templates, and the data, capabilities, interfaces, and artifacts used in the node and relationship templates). TOSCA types are reusable TOSCA entities and are defined in their specific sections in the TOSCA file. In this section, we present the definitions of common keynames that are used by all TOSCA type definitions. Type-specific definitions for the different TOSCA type entities are presented further in the document: - [Node Types](#node-types) - [Relationship Types](#relationship-types) - [Interface Types](#interface-types) - [Capability Types](#capability-types) - [Data Types](#data-types) - [Artifact Types](#artifact-types) - [Group Types](#group-types) - [Policy Types](#policy-types) ### 6.4.1 Common Keynames in Type Definitions The following keynames are used by all TOSCA type entities in the same way. This section serves to define them at once. |Keyname|Mandatory|Type|Description| | :---- | :------ | :---- | :------ | |`derived_from`|no|str|An optional parent type name from which this type derives.| |`version`|no|[version](#version)|An optional version for the type definition.| |`metadata`|no|map of [metadata](#metadata)|Defines a section used to declare additional information. |`description`|no|str|An optional [description](#description) for the type.| The common keynames in type definitions have the following grammar: ```yaml : derived_from: version: metadata: : : ... description: ``` In the above grammar, the placeholders that appear in angle brackets have the following meaning: - ``: represents the optional parent type name. - ``: represents the optional version number for the type. - ``: represents the optional description string for the type. - ``, ``: represents the optional metadata map of string. ### 6.4.2 Type Derivation To simplify type creation and to promote type extensibility TOSCA allows the definition of a new type (the derived type) based on another type (the parent type). The derivation process can be applied recursively, where a type may be derived from a long list of ancestor types (the parent, the parent of the parent, etc). Unless specifically stated in the derivation rules, when deriving new types from parent types the keyname definitions are inherited from the parent type. Moreover, the inherited definitions may be refined according to the derivation rules of that particular type entity. For definitions that are not inherited, a new definition MUST be provided (if the keyname is mandatory) or MAY be provided (if the keyname is not mandatory). If not provided, the keyname remains undefined. For definitions that are inherited, a refinement of the inherited definition is not mandatory even for mandatory keynames (since it has been inherited). A definition refinement that is exactly the same as the definition in the parent type does not change in any way the inherited definition. While unnecessary, it is not wrong. The following are some generic derivation rules used during type derivation (the specific rules of each TOSCA type entity are presented in their respective sections): - If not refined, usually a keyname/entity definition, is inherited unchanged from the parent type, unless explicitly specified in the rules that it is "not inherited". - New entities (such as properties, attributes, capabilities, requirements, interfaces, operations, notification, parameters) may be added during derivation. - Already defined entities that have a type may be redefined to have a type derived from the original type. - New validation clause is added to already defined keynames/entities (i.e. the defined validation clause does not replace the validation clauses of the parent type but are added to them). - Some definitions must be totally flexible, so they will overwrite the definition in the parent type. - Some definitions must not be changed at all once defined (i.e. they represent some sort of "signature" fundamental to the type). During type derivation the common keynames in type definitions use the following rules: - `derived_from`: obviously, the definition is not inherited from the parent type. If not defined, it remains undefined and this type does not derive from another type. If defined, then this type derives from another type, and all its keyname definitions must respect the derivation rules of the type entity. - `version`: the definition is not inherited from the parent type. If undefined, it remains undefined. - `metadata`: the definition is not inherited from the parent type. If undefined, it remains undefined. - `description`: the definition is not inherited from the parent type. If undefined, it remains undefined. ### 6.4.3 Types of Types TOSCA supports eight different *types of types*. These types can be defined in a TOSCA file using the grammars described in this section. #### 6.4.3.1 Artifact Types Artifact types can be defined in a TOSCA file using the optional `artifact_types` keyname using the following grammar: ```yaml artifact_types: ... ``` The following code snippet shows an example artifact type definition: ```yaml artifact_types: MyFile: derived_from: foobar:File ``` A detailed description of the artifact type definition grammar is provided in the [Artifacts chapter](#artifacts). #### 6.4.3.2 Data Types Data types can be defined in a TOSCA file using the optional `data_types` keyname using the following grammar: ```yaml data_types: ... ``` The following code snippet shows an example of data type definition: ```yaml data_types: # A complex datatype definition SimpleContactInfo: properties: name: type: string email: type: string phone: type: string # datatype definition derived from an existing type FullContactInfo: derived_from: SimpleContactInfo properties: street-address: type: string city: type: string state: type: string postal-code: type: string ``` A detailed description of the data type definition grammar is provided in the [Data Type section](#data-type). #### 6.4.3.3 Capability Types Capability types can be defined in a TOSCA file using the optional `capability_types` keyname using the following grammar: ```yaml capability_types: ... ``` The following code snippet shows example capability type definitions: ```yaml capability_types: MyGenericFeature: properties: # more details ... MyFirstCustomFeature: derived_from: MyGenericFeature properties: # more details ... TransactSQL: derived_from: MyGenericFeature properties: # more details ... ``` A detailed description of the capability type definition grammar is provided in the [Capability Type section](#capability-type). #### 6.4.3.4 Interface Types Interface types can be defined in a TOSCA file using the optional `interface_types` keyname using the following grammar: ```yaml interface_types: ... ``` The following code snippet shows an example interface type definition: ```yaml interface_types: Signal: operations: signal-begin-receive: description: Operation to signal start of some message processing. signal-end-receive: description: Operation to signal end of some message processed. ``` A detailed description of the interface type definition grammar is provided in the [Interface Type section](#interface-type). #### 6.4.3.5 Relationship Types Relationship types can be defined in a TOSCA file using the optional `relationship_types` keyname using the following grammar: ```yaml relationship_types: ... ``` The following code snippet shows example relationship type definitions: ```yaml relationship_types: HostedOn: properties: # more details ... MyCustomClientServer: derived_from: HostedOn properties: # more details ... MyCustomConnectionType: properties: # more details ... ``` A detailed description of the relationship type definition grammar is provided in the [Interface Type section](#relationship-type). #### 6.4.3.6 Node Types Node types can be defined in a TOSCA file using the optional `node_types` keyname using the following grammar: ```yaml node_types: ... ``` The following code snippet shows example node type definitions: ```yaml node_types: Database: description: A generic node type for all databases WebApplication: description: A generic node type MyWebApplication: derived_from: WebApplication properties: my-port: type: integer MyDatabase: derived_from: Database capabilities: TransactSQL ``` A detailed description of the node type definition grammar is provided in the [Node Type section](#node-type). #### 6.4.3.7 Group Types Group types can be defined in a TOSCA file using the optional `group_types` keyname using the following grammar: ```yaml group_types: ... ``` The following code snippet shows an example group type definition: ```yaml group_types: MyScalingGroup: derived_from: foobar:MyGroup ``` A detailed description of the group type definition grammar is provided in the [Group Type section](#group-type). #### 6.4.3.8 Policy Types Policy types can be defined in a TOSCA file using the optional `policy_types` keyname using the following grammar: ```yaml policy_types: ... ``` The following code snippet shows an example policy type definition: ```yaml policy_types: MyScalingPolicy: derived_from: foobar:Scaling ``` A detailed description of the policy type definition grammar is provided in the [Policy Type section](#policy-type). ## 6.5 Repository Definitions A repository definition defines an external *repository* that contains TOSCA files and/or artifacts that are referenced or imported by this TOSCA file. Repositories are defined using the optional `repositories` keyname as follows: ```yaml repositories: ... ``` The following is the list of recognized keynames for a TOSCA repository definition: |Keyname|Mandatory|Type|Description| | :---- | :------ | :---- | :------ | |`description`|no|str|Declares a [description](#description) for the repository being defined.| |`metadata`|no|map of [metadata](#metadata)|Defines a section used to declare additional information. |`url`|yes|str|The URL or network address used to access the repository.| These keynames can be used to define a repository using a grammar as follows: ```yaml : description: metadata: : : ... url: ``` In the above grammar, the placeholders that appear in angle brackets have the following meaning: - ``: represents the mandatory symbolic name of the repository as a string - ``: contains an optional description of the repository. - ``, ``: contains an optional map of metadata using YAML types - ``: represents the mandatory URL to access the repository as a string. If only the `url` needs to be specified, repository definitions can also use a single-line grammar as follows: ```yaml : ``` The following example show repository definitions using both multiline as well as single-line grammars. ```yaml repositories: my-project: description: My project's code repository in GitHub url: https://github.com/my-project/ external-repo: https://foo.bar ``` ## 6.6 Function Definitions A function definition defines an custom *function* that can be used within this TOSCA file. Function definitions may include one or more *function signatures* as well as function implementations. Functions are defined using the optional `functions` keyname as follows: ```yaml functions: ... ``` The following example shows the definition of a square root function: ```yaml functions: sqrt: signatures: - arguments: - type: integer validation: { $greater_or_equal: [ $value, 0 ] } result: type: float implementation: scripts/sqrt.py - arguments: - type: float validation: { $greater_or_equal: [ $value, 0.0 ] } result: type: float implementation: scripts/sqrt.py description: > This is a square root function that defines two signatures: the argument is either integer or float and the function returns the square root as a float. ``` ## 6.7 Profiles A TOSCA profile is a named collection of TOSCA type definitions, repository definitions, artifacts, and function definitions that logically belong together. One can think of TOSCA profiles as platform libraries exposed by the TOSCA processor and made available to all services that use that processor. Profiles in TOSCA are similar to libraries in traditional computer programming languages. They are intended to define collections of domain-specific components that can be used by service designers to compose complex service templates. Entities defined in TOSCA profiles are used as follows: - Types defined in a TOSCA profile provide reusable building blocks on which services can be composed. - Artifacts defined in a TOSCA profile can provide implementations for the TOSCA types defined in the profile. TOSCA implementations can organize supported profiles in a catalog to allow other service templates to import those profiles by profile name. This avoids the need for every service that uses those profiles to include the profile type definitions in their service definition packages. TOSCA files that define profiles can be bundled together with other TOSCA files in the same CSAR package. For example, a TOSCA profile that defines more abstract node types can be packaged together with TOSCA files that define substituting service templates for those types. ### 6.7.1 Grammar A TOSCA file defines a TOSCA Profile using the `profile` keyname as follows: ```yaml profile: ``` Using this grammar, the `profile` keyname assigns a *profile name* to the collection of types, repositories, and functions defined in this TOSCA file. The specified `` can be an arbitrary string value that defines the name by which other TOSCA files can import this profile. TOSCA does not place any restrictions on the value of the profile name string. However, we encourage a Java-style reverse-domain notation with version as a best-practice convention. For example, the following profile statement is used to define Version 2.0 of a set of definitions suitable for describing cloud computing in an example company: ```yaml profile: com.example.tosca_profiles.cloud_computing:2.0 ``` The following defines a domain-specific profile for Kubernetes: ```yaml profile: io.kubernetes:1.30 ``` TOSCA parsers MUST process profile definitions according to the following rules: - TOSCA files that define a profile (i.e., that contain a `profile` keyname) MUST NOT also define a service template. - If the parser encounters the `profile` keyname in a TOSCA file, then the corresponding profile name will be applied to all types defined in that file as well as to types defined in any imported TOSCA files. - If one of those imported files itself contains also defines the `profile` keyname—and that profile name is different from the name of the importing profile, then that profile name overrides the profile name value from that point in the import tree onward, recursively. ### 6.7.2 TOSCA Simple Profile Version 1.x of the TOSCA specification included a collection of normative type definitions for building cloud applications. This collection of type definitions was defined as the **TOSCA Simple Profile**. Implementations of TOSCA Version 1.x were expected to include implementations for the types defined in the TOSCA Simple Profile, and service templates defined using TOSCA Version 1.x implicitly imported the corresponding TOSCA Simple Profile version. Starting with TOSCA Version 2.0, the TOSCA Simple Profile type definitions are no longer part of the TOSCA standard and support for the TOSCA Simple Profile is no longer mandatory. Instead, the definition of the TOSCA Simple Profile has been moved to an OASIS Open Github repository with the goal of being maintained by the TOSCA community and governed as an open-source project. In addition, TOSCA Version 2.0 removes the implicit import of the TOSCA Simple Profile. Service templates that want to continue to use the TOSCA Simple Profile type definitions must explicitly import that profile. Eliminating mandatory support for the TOSCA Simple Profile makes it easier for TOSCA to be used for additional application domains. For example, the European Telecommunications Standards Institute (ETSI) has introduced a TOSCA profile for **Network Functions Virtualization** defines Virtualized Network Function Descriptors (VNFDs), Network Service Descriptors (NSDs) and a Physical Network Function Descriptors (PNFDs). ### 6.7.3 Profile Versions TOSCA Profiles are likely to evolve over time and profile designers will release different versions of their profiles. For example, the TOSCA Simple Profile has gone through minor revisions with each release of the TOSCA Version 1 standard. It is expected that profile designers will use a version qualifier to distinguish between different versions of their profiles, and service template designers must use the proper string name to make sure they import the desired versions of these profiles. When multiple versions of the same profile exist, it is possibly that service templates could mix and match different versions of a profile in the same service definition. The following code snippets illustrate this scenario: Assume a profile designer creates version 1 of a base profile that defines (among other things) a "Host" capability type and a corresponding "HostedOn" relationship type as follows: ```yaml tosca_definitions_version: tosca_2_0 profile: org.base:v1 capability_types: Host: description: Hosting capability relationship_types: HostedOn: valid_capability_types: [ Host ] ``` Now let's assume a different profile designer creates a platform-specific profile that defines (among other things) a "Platform" node type. The Platform node type defines a capability of type "Host". Since the "Host" capability is defined in the "org.base:v1" profile, that profile must be imported as shown in the snippet below: ```yaml tosca_definitions_version: tosca_2_0 profile: org.platform imports: - profile: org.base:v1 namespace: p1 node_types: Platform: capabilities: host: type: p1:Host ``` At some later point in time, the original profile designer updates the "org.base" profile to Version 2. The updated version of this profile just adds a "Credential" data type (in addition to defining the "Host" capability type and the "HostedOn" relationship type), as follows: ```yaml tosca_definitions_version: tosca_2_0 profile: org.base:v2 capability_types: Host: description: Hosting capability relationship_types: HostedOn: valid_capability_types: [ Host ] data_types: Credential: properties: key: type: string ``` Finally, let's assume a service designer creates a template for a service that is to be hosted on the platform defined in the "org.platform" profile. The template introduces a "Service" node type that has a requirement for the platform's "Host" capability. It also has a credential property of type "Credential" as defined in "org.base:v2": ```yaml tosca_definitions_version: tosca_2_0 imports: - profile: org.base:v2 namespace: p2 - profile: org.platform namespace: pl node_types: Service: properties: credential: type: p2:Credential requirements: - host: capability: p2:Host relationship: p2:HostedOn service_template: node_templates: service: type: Service properties: credential: key: password requirements: - host: platform platform: type: pl:Platform ``` This service template is invalid, since the "platform" node template does not define a capability of a type that is compatible with the `valid_capability_types` specified by the "host" requirement in the "service" node template. TOSCA grammar extensions are needed to specify that the "Host" capability type defined in "org.base:v2" is the same as the "Host" capability type defined in "org.base:v1". The example in this section illustrates a general version compatibility issue that exists when different versions of the same profile are used in a TOSCA service. ## 6.8 Imports and Namespaces Modern software projects typically use *modular designs* that divide large systems into smaller subsystems (*modules*) that together achieve complete system functionality. TOSCA includes a number of features in support of functionality, including the ability for a TOSCA file to *import* TOSCA definitions from another TOSCA file. For example, a first TOSCA file could contain reusable TOSCA type definitions (e.g., node types, relationship types, artifact types, etc.), function definitions, or repository definitions created by a domain expert. A system integrator could create a second TOSCA file that defines a *service template* comprised of node templates and relationship templates that use those types. TOSCA supports this scenario by allowing the second TOSCA file to *import* the first TOSCA file, thereby making the definitions in the first file available to the second file. This mechanism provides an effective way for companies and organizations to define domain-specific types and/or describe their software applications for reuse in other TOSCA files. ### 6.8.1 Import Definitions *Import definitions* are used within a TOSCA file to uniquely identify and locate other TOSCA files that have type, repository, and function definitions to be imported (included) into this TOSCA file. Import definitions are defined in a TOSCA file using the optional `imports` keyname as follows: ```yaml imports: - - - ... ``` The value of the `imports` keyname consists of a list of import definitions that identify the TOSCA files to be imported. The following is the list of recognized keynames for a TOSCA import definition: |Keyname|Mandatory|Type|Description| | :---- | :------ | :---- | :------ | |`url`|conditional|str|The [url](#importing-a-tosca-file) that references a TOSCA file to be imported. An import statement must include either a URL or a profile, but not both.| |`profile`|conditional|str|The [profile](#profiles) name that references a named type profile to be imported. An import statement must include either a URL or a profile, but not both.| |`repository`|conditional|str|The optional symbolic name of the [repository definition](#repository-definitions) where the imported file can be found as a string. The repository name can only be used when a URL is specified.| |`namespace`|no|str|The optional name of the [namespace](#namespaces) into which to import the type definitions from the imported template or profile.| |`description`|no|str|Declares a [description](#description) for the import definition.| |`metadata`|no|map of [metadata](#metadata)|Defines a section used to declare additional information about the import definition.| These keynames can be used to import individual TOSCA files using the following grammar: ```yaml imports: - url: repository: namespace: ``` The following grammar can be used for importing TOSCA profiles: ```yaml imports: - profile: namespace: ``` In the above grammars, the placeholders that appear in angle brackets have the following meaning: - ``: contains the URL that references the service template file to be imported as a string. - ``: represents the optional symbolic name of the repository definition where the imported file can be found as a string - ``: the name of the well-known profile to be imported. - ``: represents the optional name of the namespace into which type definitions will be imported. The namespace name can be used to form a namespace-qualified name that uniquely references type definitions from the imported file or profile. If no namespace name is specified, type definitions will be imported into the root namespace. If only the `` needs to be specified, import definitions can also use a single-line grammar as follows: ```yaml imports: - - ``` ### 6.8.2 Import Processing Rules TOSCA processors and tooling MUST handle import statements as follows: #### 6.8.2.1 Importing Profiles If the `profile` keyname is used in the import definition, then the TOSCA processor SHOULD attempt to import the profile by name: - If `` represents the name of a profile that is known to the TOSCA processor, then it SHOULD cause that profile's type definitions to be imported. - If `` is not known, the import SHOULD be considered a failure. #### 6.8.2.2 Importing a TOSCA File If the `url` keyname is used, the TOSCA processor SHOULD attempt to import the file referenced by `` as follows: - If the `` includes a URL scheme (e.g. "file:" or "https:") then `` is considered to be a network accessible resource. If the resource identified by `` represents a valid TOSCA file, then it SHOULD cause that TOSCA file to be imported. - Note that if in addition to a URL with a URL scheme, the import definition also specifies a `` (using the repository key), then that import definition SHOULD be considered invalid. - If the `` does not include a URL scheme, it is considered a relative path URL. The TOSCA processor SHOULD handle such a `` as follows: - If the import definition also specifies a `` (using the `repository` keyname), then `` refers to the path name of a file relative to the root of the named repository - If the import definition does not specify a `` then `` refers to a TOSCA file located in the repository that contains the TOSCA file that includes the import definition. If the importing TOSCA file is located in a CSAR file, then that CSAR file should be treated as the repository in which to locate the TOSCA file that must be imported. - If `` starts with a leading slash ("/") then `` specifies a path name starting at the root of the repository. - If `` does not start with a leading slash, then `` specifies a path that is relative to the importing document's location within the repository. Double dot notation ("../") can be used to refer to parent directories in a file path name. - If `` does not reference a valid TOSCA file file, then the import SHOULD be considered a failure. ### 6.8.3 Examples The first example shows how to use an import definition import a well-known profile by name: ```yaml # Importing a profile imports: - profile: org.oasis-open.tosca.simple:2.0 ``` The next example shows an import definition used to import a network-accessible resource using the https protocol: ```yaml # Absolute URL with scheme imports: - url: https://myorg.org/tosca/types/mytypes.yaml ``` The following shows an import definition used to import a TOSCA file located in the same repository as the importing file. The file to be imported is referenced using a path name that is relative to the location of the importing file. This example shows the short notation: ```yaml # Short notation supported imports: - ../types/mytypes.yaml ``` The following shows the same example but using the long notation: ```yaml # Long notation imports: - url: ../types/mytypes.yaml ``` The following example mixes short-notation and long-notation import definitions: ```yaml # Short notation and long notation supported imports: - relative_path/my_defns/my_typesdefs_1.yaml - url: my_defns/my_typesdefs_2.yaml repository: my-company-repo namespace: mycompany ``` The following example shows how to import TOSCA files using absolute path names (i.e. path names that start at the root of the repository): ```yaml # Root file imports: - url: /base.yaml ``` And finally, the following shows how to import TOSCA files from a repository that is different than the repository that contains the importing TOSCA file: ```yaml # External repository imports: - url: types/mytypes.yaml repository: my-repository ``` ### 6.8.4 Namespaces When importing TOSCA files or TOSCA profiles, there exists a possibility for name collision. For example, an imported file may define a node type with the same name as a node type defined in the importing file. For example, let say we have two TOSCA files, A and B, both of which contain a node type definition for "MyNode": **TOSCA File B** ```yaml tosca_definitions_version: tosca_2_0 description: TOSCA File B node_types: MyNode: derived_from: SoftwareComponent properties: # omitted here for brevity capabilities: # omitted here for brevity ``` **TOSCA File A** ```yaml tosca_definitions_version: tosca_2_0 description: TOSCA File A imports: - url: /templates/TOSCAFileB.yaml node_types: MyNode: properties: # omitted here for brevity capabilities: # omitted here for brevity service_template: node_templates: my-node: type: MyNode ``` As you can see, TOSCA file A imports TOSCA file B which results in duplicate definitions of the MyNode node type. In this example, it is not clear which type is intended to be used for the my_node node template. To address this issue, TOSCA uses the concept of namespaces: - Each TOSCA file defines a root namespace for all type definitions defined in that file. Root namespaces are unnamed. - When a TOSCA file imports other TOSCA files, it has two options: - It can import any type definitions from the imported TOSCA files into its root namespace. - Or it can import type definitions from the imported TOSCA files into a separate named namespace. This is done using the `namespace` keyname in the associated import definition. When using types imported into a named namespace, those type names must be qualified by using the namespace name as a prefix. The following snippets update the previous example using namespaces to disambiguate between the two "MyNode" type definitions. This first snippet shows the scenario where the "MyNode" definition from TOSCA file B is intended to be used: ```yaml tosca_definitions_version: tosca_2_0 description: TOSCA file A imports: - url: /templates/TOSCAFileB.yaml namespace: fileB node_types: MyNode: properties: # omitted here for brevity capabilities: # omitted here for brevity service_template: node_templates: my-node: type: fileB:MyNode ``` The second snippet shows the scenario where the "MyNode" definition from TOSCA file A is intended to be used: ```yaml tosca_definitions_version: tosca_2_0 description: TOSCA file A imports: - url: /templates/TOSCAFileB.yaml namespace: fileB node_types: MyNode: properties: # omitted here for brevity capabilities: # omitted here for brevity service_template: node_templates: my-node: type: MyNode ``` In many scenarios, imported TOSCA files may in turn import their own TOSCA files, and introduce their own namespaces to avoid name collisions. In those scenarios, nested namespace names are used to uniquely identify type definitions in the import tree. The following example shows a mytypes.yaml TOSCA file that imports a Kubernetes profile into the "k8s" namespace. It defines a "SuperPod" node type that derives from the "Pod" node type defined in that Kubernetes profile: ```yaml tosca_definitions_version: tosca_2_0 description: mytypes.yaml imports: - profile: io.kubernetes:1.30 namespace: k8s node_types: MyNode: {} SuperPod: derived_from: k8s:Pod ``` The "mytypes.yaml" file is then imported into the main.yaml TOSCA file, which defines both a node template of type "SuperPod" as well as a node template of type "Pod". Nested namespace names are used to identify the "Pod" node type from the Kubernetes profile: ```yaml tosca_definitions_version: tosca_2_0 description: main.yaml imports: - url: mytypes.yaml namespace: my service_template: node_templates: my-node: type: my:MyType pod: type: my:k8s:Pod ``` Within each namespace (including the unnamed root namespace), names must be unique. This means that duplicate local names (i.e., within the same TOSCA file SHALL be considered an error. These include, but are not limited to duplicate names found for the following definitions: - Repositories (`repositories`) - Data Types (`data_types`) - Node Types (`node_types`) - Relationship Types (`relationship_types`) - Capability Types (`capability_types`) - Artifact Types (`artifact_types`) - Interface Types (`interface_types`) - Policy Types (`policy_types`) - Group Types (`group_types`) - Function definitions (`functions`) ## 6.9 Service Template Definition This section defines the service template of a TOSCA file. The main ingredients of the service template are node templates representing components of the application and relationship templates representing links between the components. These elements are defined in the nested `node_templates` section and the nested `relationship_templates` sections, respectively. Furthermore, a service template allows for defining input parameters, output parameters, workflows as well as grouping of node templates and associated policies. ### 6.9.1 Service Template Grammar The following is the list of recognized keynames for a TOSCA service template: |Keyname|Mandatory|Type|Description| | :---- | :------ | :---- | :------ | |`description`|no|str|The optional [description](#description) for the service template.| |`metadata`|no|map of [metadata](#metadata)|Defines a section used to declare additional information about this service template.| |`inputs`|no|map of [parameter definitions](#input-parameters)|An optional map of input parameters (i.e., as parameter definitions) for the service template.| |`outputs`|no|map of [parameter definitions](#output-parameters)|An optional map of output parameters (i.e., as parameter definitions) for the service template.| |`node_templates`|yes|map of [node templates](#node-template)|A mandatory map of node template definitions for the service template.| |`relationship_templates`|no|map of [relationship templates](#relationship-template)|An optional map of relationship templates for the service template.| |`groups`|no|map of [group definitions](#group-definitions)|An optional map of group definitions whose members are node templates defined within this same service template.| |`policies`|no|seq of [policy definitions](#policy-definitions)|An optional list of policy definitions for the service template.| |`substitution_mappings`|no|[substitution_mapping](#substitution-mapping)|An optional declaration that exports the service template as an implementation of a Node type. This also includes the mappings between the external node type's capabilities and requirements to existing implementations of those capabilities and requirements on node templates declared within the service template.| |`workflows`|no|map of [workflow definitions](#workflow-definitions)|An optional map of workflow definitions for the service template.| The overall grammar of the service_template section is shown below. Detailed grammar definitions are provided in subsequent subsections. ```yaml service_template: description: metadata: : : ... inputs: ... outputs: ... node_templates: ... relationship_templates: ... groups: ... policies: - - - ... substitution_mappings: workflows: ... ``` In the above grammar, the placeholders that appear in angle brackets have the following meaning: - ``: represents the optional map of input parameter definitions for the service template. - ``: represents the optional map of output parameter definitions for the service template. - ``: represents the mandatory map of node template definitions for the service template. - ``: represents the optional map of group definitions whose members are node templates that also are defined within this service template. - ``: represents the optional ordered list of policy definitions for the service template. - ``: defines how services created from this template can substitute other nodes. - ``: represents the optional map of imperative workflow definitions for the service template. Note that duplicate template names within a service template SHALL be considered an error. These include, but are not limited to duplicate names found for the following template types: - Inputs (`inputs`) - Outputs (`outputs`) - Node Templates (`node_templates`) - Relationship Templates (`relationship_templates`) - Groups (`groups`) - Policies (`policies`) - Workflows (`workflows`) More detailed explanations for each of the service template grammar's keynames appears in the sections below. ### 6.9.2 Input Parameters The `inputs` section of a service template provides a means to define parameters using TOSCA parameter definitions, their allowed values via validation clauses and default values. Input parameters defined in the inputs section of a service template can be mapped to properties of node templates or relationship templates within the same service template and can thus be used for parameterizing the instantiation of the service template. When deploying a service from the service template, values must be provided for all mandatory input parameters that have no default value defined. If no input is provided, then the default value is used. The grammar of the `inputs` section is as follows: ```yaml inputs: ... ``` The following code snippet shows a simple `inputs` example without any validation clause: ```yaml inputs: foo-name: type: string description: Simple string parameter without a validation clause. default: bar ``` The following is an example of input parameter definitions with a validation clause: ```yaml inputs: site-name: type: string description: String parameter with validation clause. default: My Site validation: { $greater_or_equal: [ $value, 9 ] } ``` ### 6.9.3 Node Templates The `node_templates` section of a service template lists the node templates that describe the components that are used to compose applications. The grammar of the `node_templates` section is a follows: ```yaml node_templates: ... ``` The following code snippet shows an example of a `node_templates` section: ```yaml node_templates: my-webapp: type: WebApplication my-database: type: Database ``` ### 6.9.4 Relationship Templates The `relationship_templates` section of a service template lists the relationship templates that describe the relations between components that are used to compose cloud applications. Note that the explicit definition of relationship templates is optional, since relationships between nodes get implicitly defined by referencing other node templates in the `requirements` sections of node templates. The grammar of the `relationship_templates` section is as follows: ```yaml relationship_templates: ... ``` The following code snippet shows an example of a `relationship_templates` section: ```yaml relationship_templates: my-connects-to: type: ConnectsTo interfaces: configure: inputs: speed: { $get_attribute: [ SELF, SOURCE, connect-speed ] } ``` ### 6.9.5 Output Parameters The `outputs` section of a service template provides a means to define the output parameters that are available from a deployed TOSCA service. It allows for exposing attributes defined in node templates or relationship templates within the containing `service_template` to users of a service. The grammar of the `outputs` section is as follows: ```yaml outputs: ... ``` The following code snippet shows an example of the `outputs` section: ```yaml outputs: server-address: description: The first private IP address for the provisioned server. value: { $get_attribute: [ node5, networks, private, addresses, 0 ] } ``` ### 6.9.6 Workflow Definitions The `workflows` section of a service template allows for declaring imperative workflows that can operate on entities in the service template. The grammar of the `workflows` section is as follows: ```yaml workflows: ... ``` The following example shows the definition of a workflow: ```yaml workflows: scaling-workflow: steps: TO BE PROVIDED ``` ### 6.9.7 Group Definitions The `groups` section of a service template allows for grouping node representations created from one or more node templates within a TOSCA service template. This grouping can then be used to apply policies to the group. The grammar of the `groups` section is as follows: ```yaml groups: ... ``` The following example shows the definition of three "Compute" nodes in the `node_templates` section of a `service_template` as well as the grouping of two of the "Compute" nodes in group "servers": ```yaml node_templates: server1: type: Compute # more details ... server2: type: Compute # more details ... server3: type: Compute # more details ... groups: # server2 and server3 are part of the same group servers: type: MyScaling members: [ server2, server3 ] ``` ### 6.9.8 Policy Definitions The `policies` section of a service template allows for declaring policies that can be applied to entities in the service template. The grammar of the `policies` section is as follows: ```yaml policies: - - - ... ``` The following example shows the definition of a placement policy: ```yaml policies: - my-placement: type: Placement ``` ### 6.9.9 Substitution Mappings The `substitution_mappings`section of a service template declares this service template as a candidate for substituting nodes marked with the "substitute" directive in other service templates. The grammar of a `substitution_mapping` is as follows: ```yaml substitution_mappings: ``` The following code snippet shows an example substitution mapping: ```yaml service_template: inputs: cpus: type: integer validation: { $less_than: [ $value, 5 ] } substitution_mappings: node_type: MyService properties: num-cpus: cpus capabilities: bar: [ some-service, bar ] requirements: foo: [ some-service, foo ] node_templates: some-service: type: MyService properties: rate: 100 capabilities: bar: ... requirements: - foo: ... ``` # 7 Nodes and Relationships The content in this section is normative unless otherwise labeled except: - the examples - references unless labelled as normative. ## 7.1 Node Type A *node type* is a reusable entity that defines the structure of observable properties and attributes of a node, the capabilities and requirements of that node, as well as its supported interfaces and the artifacts it uses. A node type definition is a type of TOSCA type definition and as a result supports the common keynames listed in [the section Common Keynames in Type Definitions](#common-keynames-in-type-definitions). In addition, the node type definition has the following recognized keynames: |Keyname|Mandatory|Type|Description| | :---- | :------ | :---- | :------ | |`properties`|no|map of [property definitions](#property-definition)|An optional map of property definitions for the node type.| |`attributes`|no|map of [attribute definitions](#attribute-definition)|An optional map of attribute definitions for the node type.| |`capabilities`|no|map of [capability definitions](#capability-definition)|An optional map of capability definitions for the node type.| |`requirements`|no|seq of [requirement definitions](#requirement-definition)|An optional list of requirement definitions for the node type.| |`interfaces`|no|map of [interface definitions](#interface-definition)|An optional map of interface definitions supported by the node type.| |`artifacts`|no|map of [artifact definitions](#artifact-definition)|An optional map of artifact definitions for the node type.| These keynames can be used according to the following grammar: ```yaml : derived_from: version: metadata: : : ... description: properties: ... attributes: ... capabilities: ... requirements: - - - ... interfaces: ... artifacts: ... ``` In the above grammar, the placeholders that appear in angle brackets have the following meaning: - ``: represents the mandatory symbolic name of the node type being declared. - ``: represents the name (string) of the node type from which this node type definition derives (i.e. its parent type). Parent node types names can be qualified using a namespace prefix. - ``: represents the optional map of property definitions for the node type. - ``: represents the optional map of attribute definitions for the node type. - ``: represents the optional map of capability definitions for the node type. - ``: represents the optional list of requirement definitions for the node type. Note that requirements are intentionally expressed as a list of TOSCA Requirement definitions that SHOULD be resolved (processed) in sequence by TOSCA processors. Requirement names must be unique within the context of a node type definition. - ``: represents the optional map of interface definitions supported by the node type. - ``: represents the optional map of artifact definitions for the node type During node type derivation, the keynames follow these rules: - `properties`: existing property definitions may be refined; new property definitions may be added. - `attributes`: existing attribute definitions may be refined; new attribute definitions may be added. - `capabilities`: existing capability definitions may be refined; new capability definitions may be added. - `requirements`: existing requirement definitions may be refined; new requirement definitions may be added. - `interfaces`: existing interface definitions may be refined; new interface definitions may be added. - `artifacts`: existing artifact definitions (identified by their symbolic name) may be redefined; new artifact definitions may be added. - note that an artifact is created for a specific purpose and corresponds to a specific file (with e.g. a path name and checksum); if it cannot meet its purpose in a derived type then a new artifact should be defined and used. - thus, if an artifact defined in a parent node type does not correspond anymore with the needs in the child node type, its definition may be completely redefined; thus, an existing artifact definition is not refined, but completely overwritten. The following code snippet shows an example node type definition: ```yaml MyApp: derived_from: SoftwareComponent description: My company's custom application properties: my-app-password: type: string description: Application password validation: $and: - { $greater_or_equal: [ $value, 6 ] } - { $less_or_equal: [ $value, 10 ] } attributes: my-app-port: type: integer description: Application port number requirements: - some-database: capability: EndPoint.Database node: Database relationship: ConnectsTo ``` ## 7.2 Node Template A *node template* specifies the occurrence of one or more instances of a component of a given type in an application or service. A node template defines application-specific values for the properties, relationships, or interfaces defined by its node type. The following is the list of recognized keynames for a TOSCA node template definition: |Keyname|Mandatory|Type|Description| | :---- | :------ | :---- | :------ | |`type`|yes|str|The mandatory name of the [node type](#node-types) on which the node template is based.| |`description`|no|str|An optional [description](#description) for the node template.| |`metadata`|no|map of [metadata](#metadata)|Defines a section used to declare additional information. | |`directives`|no|seq of strs|An optional list of [directive](#node-template-directives) values to provide processing instructions to orchestrators and tooling.| |`properties`|no|map of [property assignments](#property-assignment)|An optional map of property value assignments for the node template.| |`attributes`|no|map of [attribute assignments](#attribute-assignment)|An optional map of attribute value assignments for the node template.| |`requirements`|no|seq of [requirement assignments](#requirement-assignment)|An optional list of requirement assignments for the node template.| |`capabilities`|no|map of [capability assignments](#capabilities-assignment)|An optional map of capability assignments for the node template.| |`interfaces`|no|map of [interface assignments](#interface-assignment)|An optional map of interface assignments for the node template.| |`artifacts`|no|map of [artifact definitions](#artifact-definition)|An optional map of artifact definitions for the node template.| |`count`|no|non-negative integer|An optional keyname that specifies how many [node representations](#specifying-number-of-node-representations) must be created from this node template. If not defined, the assumed count value is 1.| |`node_filter`|no|[node filter](#node-filter-definition)|The optional filter definition that TOSCA orchestrators will use to select an already existing node if this node template is marked with the "select" directive.| |`copy`|no|str|The optional (symbolic) name of another node template from which to copy all keynames and values into this node template.| These keynames can be used according to the following grammar: ```yaml : type: description: directives: [ , , ... ] metadata: : : ... properties: ... attributes: ... requirements: - - - ... capabilities: ... interfaces: ... artifacts: ... count: node_filter: copy: ``` In the above grammar, the placeholders that appear in angle brackets have the following meaning: - ``: represents the mandatory symbolic name of the node template being defined. - ``: represents the name of the node type on which the node template is based. - ``: represents the optional list of processing instruction values (as strings) for use by tooling and orchestrators. Valid directives supported by this version of the standard are "create", "select", and "substitute". If no directives are specified, "create" is used as the default value. - ``: represents the optional map of property assignments for the node template that provide values for properties defined in its declared node type. - ``: represents the optional map of attribute assignments for the node template that provide values for attributes defined in its declared node type. - ``: represents the optional list of requirement assignments for the node template for requirement definitions provided in its declared node type. - ``: represents the optional map of capability assignments for the node template for capability definitions provided in its declared node type. - ``: represents the optional map of interface assignments for the node template interface definitions provided in its declared node type. - ``: represents the optional map of artifact definitions for the node template that augment or replace those provided by its declared node type. - ``: represents the number of node representations that must be created from this node template. If not specified, a default value of 1 is used. - ``: represents the optional node filter TOSCA orchestrators will use for selecting a matching node template. - ``: represents the optional (symbolic) name of another node template from which to copy all keynames and values into this node template. Note that he source node template provided as a value on the `copy` keyname MUST NOT itself use the `copy` keyname (i.e., it must itself be a complete node template description and not copied from another node template). The following code snippet shows an example node template definition: ```yaml node_templates: mysql: type: DBMS.MySQL properties: root-password: { $get_input: my-mysql-rootpw } port: { $get_input: my-mysql-port } requirements: - host: db-server interfaces: standard: operations: configure: scripts/my_own_configure.sh ``` ### 7.2.1 Node Template Directives As described in the section above, a node template supports the following 3 directives used by the TOSCA resolver to populate nodes in the representation graph: - "create" is the default directive, assumed if no directives are defined. The resolver is creating the node based on the node template with the specified properties, attributes, and interface implementations. - "select" is the directive that specifies that a node from a representation graph external to this service should be selected and added into this service representation graph. The node is not duplicated and its properties, attributes, interfaces and outgoing relationships cannot be changed. Nevertheless, this node can become the target of incoming relationships within this representation graph. The symbolic name of the node is an alias by which this node is accessible in this representation graph. - The only keyname that is relevant for the resolver if the "select" directive is used is the `node_filter`, which is used to select a suitable node. All the others (e.g. property assignments, interface implementations, requirements, etc.) are ignored. - As the `node_filter` is only relevant for the "select" directive, it should not be present if the "select" directive is not present. Note that if the `node_filter` is missing then the selection will be based solely on the node type. - A detailed description of the `node_filter` is given in the [Node Filter Definition Section](#node-filter-definition). - "substitute" is the directive that specifies that this node's realization and behavior should be realized by an internal service created from a substitution template. - A node representation for the substituted node will be created and added to the representation graph of the top-level service, and can be accessed in the top-level service via its symbolic name as any other node representation. Within the the top-level service scope none of the substitution service details are visible. - The substituted node properties are defined from the property assignments, its relationships are established from requirements, and the node can be target of other relationships. - A service is created from the substitution template having its own representation graph and associated to the substituted node in the top-level service. - The properties of the substituted node may become inputs to the substitution service if such a substitution mapping is defined. - The attributes of the substituted node will receive the output values of the substitution service if such substitution mapping is defined. Otherwise their value will remain undefined. - As the behavior of the substituted node is deferred to the substitution service, any implementation of the interfaces in the node template are ignored. To connect a behavior to the interface operations and notifications they or must be mapped to workflows in the substitution service (which then provide the "implementation"). - A detailed description of the substitution mechanism is given in the [Substitution Section](#substitution). Note that several directives can be specified in a list. The TOSCA resolver will attempt to use them in the right sequence. If not possible to fulfill the first in the list, it will try with the second, and so on. For example `directives: select, substitute, create` means that first the resolver will try to find a node that matches the `node_filter` within its available scope. If not found, it will try to find a suitable substitution template that matches this node. If not found, it will finally try to create a new node from the node template definition. ## 7.3 Relationship Type A *relationship type* is a reusable entity that defines the structure of observable properties and attributes of a relationship as well as its supported interfaces. A relationship type definition is a type of TOSCA type definition and as a result supports the common keynames listed in [the section Common Keynames in Type Definitions](#common-keynames-in-type-definitions). In addition, the relationship type definition has the following recognized keynames: |Keyname|Mandatory|Definition/Type|Description| | :---- | :------ | :---- | :------ | |`properties`|no|map of [property definition](#property-definition)|An optional map of property definitions for the relationship type.| |`attributes`|no|map of [attribute definitions](#attribute-definition)|An optional map of attribute definitions for the relationship type.| |`interfaces`|no|map of [interface definitions](#interface-definition)|An optional map of interface definitions supported by the relationship type.| |`valid_capability_types`|no|seq of strs|An optional list of one or more names of [capability types](#capability-types) that are valid targets for this relationship. If undefined, all capability types are valid.| |`valid_target_node_types`|no|seq of strs|An optional list of one or more names of [node types](#node_types) that are valid targets for this relationship. If undefined, all node types are valid targets.| |`valid_source_node_types`|no|seq of strs|An optional list of one or more names of [node types](#node_types) that are valid sources for this relationship. If undefined, all node types are valid sources.| These keynames can be used according to the following grammar: ```yaml : derived_from: version: metadata: : : ... description: properties: ... attributes: ... interfaces: ... valid_capability_types: [ , , ... ] valid_target_node_types: [ , , ... ] valid_source_node_types: [ , , ... ] ``` In the above grammar, the placeholders that appear in angle brackets have the following meaning: - ``: represents the mandatory symbolic name of the relationship type being declared as a string. - ``: represents the name (string) of the relationship type from which this relationship type definition derives (i.e., its "parent" type). Parent node type names can be qualified using a namespace prefix. - ``: represents the optional map of property definitions for the relationship type. - ``: represents the optional map of attribute definitions for the relationship type. - ``: represents the optional map of interface definitions supported by the relationship type. - ``: represents the optional list of valid target capability types for the relationship. Target capability type names can be qualified using a namespace prefix. If undefined, the valid target types are not restricted at all (i.e., all capability types are valid). - ``: represents the optional list of valid target node types for the relationship. Target node type names can be qualified using a namespace prefix. If undefined, the valid types are not restricted at all (i.e., all node types are valid). - ``: represents the optional list of valid source node types for the relationship. Source node type names can be qualified using a namespace prefix. If undefined, the valid types are not restricted at all (i.e., all node types are valid). During relationship type derivation the keyname definitions follow these rules: - `properties`: existing property definitions may be refined; new property definitions may be added. - `attributes`: existing attribute definitions may be refined; new attribute definitions may be added. - `interfaces`: existing interface definitions may be refined; new interface definitions may be added. - `valid_capability_types`: A derived type is only allowed to further restrict the list of valid capability types, not to expand it. This means that if `valid_capability_types` is defined in the parent type, each element in the derived type's list of valid capability types must either be in the parent type list or derived from an element in the parent type list; if `valid_target_types` is not defined in the parent type then no derivation restrictions need to be applied. - `valid_target_node_types`: same derivation rules as for `valid_capability_types` - `valid_source_node_types`: same derivation rules as for `valid_capability_types` The following code snippet shows an example relationship type definition: ```yaml AppDependency: derived_from: DependsOn valid_capability_types: [ SomeAppFeature ] ``` ## 7.4 Relationship Template A *relationship template* specifies the occurrence of a relationship of a given type between nodes in an application or service. A relationship template defines application-specific values for the properties, relationships, or interfaces defined by its relationship type. TOSCA allows relationships between nodes to be defined *inline* using requirement assignments within node templates or *out-of-band* using relationship templates as defined in this section. While the use of requirement assignments is more common, the use of relationship templates decouples relationship definitions from specific node templates, allowing reuse of these relationship templates by multiple node templates. Relationship templates are local within a service template and so have a limited scope. Note that relationship template grammar is underspecified currently and needs further work. The following is the list of recognized keynames for a TOSCA relationship template definition: |Keyname|Mandatory|Type|Description| | :---- | :------ | :---- | :------ | |`type`|yes|str|The mandatory name of the [relationship type](#relationship-types) on which the relationship template is based.| |`description`|no|str|An optional [description](#description) for the relationship template.| |`metadata`|no|map of [metadata](#metadata)|Defines a section used to declare additional information. | |`properties`|no|map of [property assignments](#property-definition)|An optional map of property assignments for the relationship template.| |`attributes`|no|map of [attribute assignments](#attribute-definition)|An optional map of attribute assignments for the relationship template.| |`interfaces`|no|map of [interface assignments](#interface-assignment)|An optional map of interface assignments for the relationship template.| |`copy`|no|str|The optional (symbolic) name of another relationship template from which to copy all keynames and values into this relationship template.| These keynames can be used according to the following grammar: ```yaml : type: description: metadata: :