Instance Model for TOSCA Version 1.0

Instance Model for TOSCA Version 1.0

Working Draft 01

18 October 2017

Technical Committee:

OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA) TC

Chairs:

Paul Lipton (), CA Technologies

John Crandall (), Brocade Communications Systems

Editor:

Derek Palma (), Vnomic

Additional artifacts:

This prose specification is one component of a Work Product that also includes:

·  XML schemas: (list file names or directory name)

·  Other parts (list titles and/or file names)

Related work:

This specification is related to:

·  Topology and Orchestration Specification for Cloud Applications Version 1.0. Edited by Derek Palma and Thomas Spatzier. 25 November 2013. OASIS Standard. http://docs.oasis-open.org/tosca/TOSCA/v1.0/os/TOSCA-v1.0-os.html.

Abstract:

This specification defines the information model, behavioral semantics, and access methods for a dynamic object model representation of TOSCA Service Template deployments required to enable on-going automated management of TOSCA topologies. The Instance Model represents the current state of a deployment including all inputs, concrete node fulfillments, property settings, cardinalities, relationships, applied policies, and correlation with external resources and entities. Service template deployments can be queried, navigated, reasoned over and updated with imperative workflows, policy actions, and their evolution observed over time. The instance model is extensible allowing integration of information from other domains, across deployments and orchestrators.

Status:

This Working Draft (WD) has been produced by one or more TC Members; it has not yet been voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Draft.

Any machine-readable content (Computer Language Definitions) declared Normative for this Work Product must also be provided in separate plain text files. In the event of a discrepancy between 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.

URI patterns:

Initial publication URI:
http://docs.oasis-open.org/tosca/TOSCA-Instance-Model/v1.0/csd01/TOSCA-Instance-Model-v1.0-csd01.docx

Permanent “Latest version” URI:
http://docs.oasis-open.org/tosca/TOSCA-Instance-Model/v1.0/TOSCA-Instance-Model-v1.0.docx

(Managed by OASIS TC Administration; please don’t modify.)

Copyright © OASIS Open 2017. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Table of Contents

1 Introduction 6

1.1 Terminology 6

1.2 Normative References 6

1.3 Non-Normative References 6

1.4 Glossary 7

2 Summary of key TOSCA concepts 9

3 TOSCA Instance Model Conceptual Overview 10

3.1 What is an instance model? 10

3.2 What problems does it address? 10

4 Design Considerations 11

4.1 State-based Orchestration Paradigm 11

4.2 Instance Model Consumers 11

4.2.1 Declarative Orchestration 11

4.2.2 Workflow Execution 11

4.2.3 External Clients 11

4.3 Orchestrator States vs. Real-world States 12

4.4 Reflecting Node Status in the Instance Model 12

4.5 Tracking State Changes 12

4.6 Visibility of Nodes and Node Attributes 12

4.7 Orchestration Execution Status 13

5 Model Structure 14

5.1 Meta Levels 14

5.2 Deriving the Instance Model 15

5.3 Sample Service Template 15

5.4 Deriving the Instance Model Graph 16

5.5 Instance Model Schema 17

5.5.1 Schema Modeling Language 17

5.5.2 Instance Model Schema 17

5.5.2.1 InstanceClass Definition 18

5.5.2.1.1 Data Types 18

5.5.2.1.2 References 18

5.5.2.1.2.1 InstanceReference 18

5.5.2.1.2.2 ExternalTosca<DocumentElement>Reference 18

5.5.2.1.2.3 Reference scope and Semantics 18

5.5.3 InstanceObject Definition 19

5.6 Instance Model Definition 19

5.6.1 InstanceNode Definition 19

5.6.2 InstanceProperty Definition 20

5.6.3 InstanceAttribute Definition 21

5.6.4 InstanceCapability Definition 21

5.6.5 InstanceRequirement Definition 21

5.6.6 InstanceGroup Definition 22

5.6.7 InstanceMetadata Definition 23

5.6.8 InstanceInput Definition 23

5.6.9 InstancePolicy Definition 23

5.6.10 InstanceOutput Definition 24

5.7 Complete Derivation to YAML syntax (textual) 24

5.8 Specific derivations 25

5.8.1 Entities (Graph vertices) 25

5.8.1.1 Template (from node type) 25

5.8.1.2 Instance (from template) 25

5.8.1.3 Instance (from type) 25

5.8.2 Relationships (graph edges) 25

5.8.2.1 Relation from between a pair of nodes 25

5.8.2.2 Mapping M to N (by intension) 25

5.8.2.3 Explicit M to N (by extension) 25

5.9 Encoding of information 25

5.10 Serialization Issues 25

5.11 Relationships between Node Instances 26

5.12 Recovering the Service Template 26

6 Tracking State Changes 27

6.1 Reflecting Node Status in the Instance Model 27

6.2 Visibility of Nodes and Node Attributes 27

6.3 Orchestration Execution Status 27

6.4 Update Concurrency 27

7 Query and Navigation 28

7.1 Imperative Workflow Use Case 28

7.2 Imperative interaction with the Instance Model 28

7.3 State tracking/synchronization 28

7.4 Query 28

7.5 Navigation 28

8 Extensibility 29

8.1 Resource Metadata 29

8.2 Event Triggered Updates 29

9 Instance Model Access 30

9.1 YAML Dump 30

9.2 Instance Model Access via API 30

10 Security Considerations 31

10.1 Access Control 31

10.2 Authorization 31

10.3 Obfuscation of Sensitive Information 31

11 Conformance 32

11.1 Conformance Clause 1: Deployment Orchestration Only 32

11.2 Conformance Clause 2: Post Orchestration Instance Model Snapshots 32

11.3 Conformance Clause 3: Dynamic and Extensible Instance Model Updates 32

11.4 Conformance Clause 4: Programmatic Read-Only Access 32

11.5 Conformance Clause 5: Programmatic Updates 32

Appendix A. Acknowledgments 33

Appendix B. Example Title 34

B.1 Subsidiary section 34

B.1.1 Sub-subsidiary section 34

B.1.1.1 Sub-sub-subsidiary section 34

B.1.1.1.1 Sub-sub-sub-subsidiary section 34

12 Schema Modeling Language 35

12.1 Collections 36

12.2 TOSCA DSL Entity References 36

12.2.1 ToscaDslRef Definition 36

12.3 Cross Instance Model Linking 37

12.3.1 URIs and Entity Identity 37

12.3.2 Local Model Linking 37

12.3.3 Foreign Model Linking 37

Appendix C. Example Title 38

C.1 Subsidiary section 38

C.1.1 Sub-subsidiary section 38

C.1.1.1 Sub-sub-subsidiary section 38

C.1.1.1.1 Sub-sub-sub-subsidiary section 38

Appendix D. Revision History 39

TOSCA-Instance-Model-v1.0-wd01 Working Draft 01 20 October 2017

Standards Track Draft Copyright © OASIS Open 2017. All Rights Reserved. Page 1 of 39

1  Introduction

The TOSCA Domain Specific Language (DSL), expresses a topology of entities (service template), their lifecycles, management operations and constraints. Instantiation of a TOSCA service template involves an orchestrator processing a service template, fulfilling the requirements of each node template, and orchestrating a sequence of lifecycle operations across the entities of the topology to reach an end-state prescribed by the service template.

The TOSCA Instance Model expresses the complete structure and state of an instantiated service template. The existence of an instance model has been implied in other TOSCA specifications when describing the behavior semantics of a TOSCA orchestrator as it executes a service template deployment. A complete and concise specification of the Instance Model permits the continued automated management of an instantiated service template and is motivated via the following use cases:

1.  Expressing the end-state reached of a TOSCA deployment by an orchestrator;

2.  Expressing intermediate states as the deployment is changed by declarative or imperative orchestration;

3.  Comparing a pair of TOSCA deployments, possibly by different orchestrators, for similarities or differences;

4.  Enabling imperative workflows to examine and synchronize its knowledge of the state of the deployment;

5.  Enabling imperative workflows to execute side-effects on the deployment;

6.  Enabling declarative actions to be triggered as the deployment changes;

7.  Expressing the state of the deployment over time, as entities in the topology change state due to their innate behaviors and external influences;

8.  Correlating entities in the deployment to entities in the physical world.

A set of Instance Model operations are defined and specified to support the creation and dynamic evolution:

1. Derivation the Instance Model from a service template
2. Accessing the Instance Model
3. Updating the Instance Model
4. Correlation of the Instance Model entities with external entities
5. Synchronizing the Instance Model with external state

1.1 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

1.2 Normative References

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt.

[Reference] [Full reference citation]

1.3 Non-Normative References

[Reference] [Full reference citation]

(Remove Non-Normative References section if there are none. Remove this note and text below before submitting for publication.)

For all References – Normative and Non-Normative:

Recommended approach: Set up [Reference] label elements as "Bookmarks", then create hyperlinks to them within the document. (Here’s how: Insert hyperlinkàPlace in this documentàscroll down to Bookmarks, select appropriate one.)

Use the "Ref" paragraph style to format references.

The proper format for citation of technical work produced by an OASIS TC (whether Standards Track or Non-Standards Track) is:

[Citation Label] Work Product title (italicized). Edited by Albert Alston, Bob Ballston, and Calvin Carlson. Approval date (DD Month YYYY). OASIS Stage Identifier and Revision Number (e.g., OASIS Committee Specification Draft 01). Principal URI (version-specific URI, e.g., with stage component: somespec-v1.0-csd01.html). Latest version: (latest version URI, without stage identifiers).

For example:

[OpenDoc-1.2] Open Document Format for Office Applications (OpenDocument) Version 1.2. Edited by Patrick Durusau and Michael Brauer. 19 January 2011. OASIS Committee Specification Draft 07. http://docs.oasis-open.org/office/v1.2/csd07/OpenDocument-v1.2-csd07.html. Latest version: http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html.

Reference sources:

For references to IETF RFCs, use the approved citation formats at:
http://docs.oasis-open.org/templates/ietf-rfc-list/ietf-rfc-list.html.

For references to W3C Recommendations, use the approved citation formats at:
http://docs.oasis-open.org/templates/w3c-recommendations-list/w3c-recommendations-list.html.

1.4 Glossary

The following terms are used throughout this specification and have the following definitions when used in context of this document.

Term / Definition
Instance Model / A deployed service is a running instance of a Service Template. More precisely, the instance is derived by instantiating the Topology Template of its Service Template, most often by running a special plan defined for the Service Template, often referred to as build plan.
Node Template / A Node Template specifies the occurrence of a software component node as part of a Topology Template. Each Node Template refers to a Node Type that defines the semantics of the node (e.g., properties, attributes, requirements, capabilities, interfaces). Node Types are defined separately for reuse purposes.
Relationship Template / A Relationship Template specifies the occurrence of a relationship between nodes in a Topology Template. Each Relationship Template refers to a Relationship Type that defines the semantics relationship (e.g., properties, attributes, interfaces). Relationship Types are defined separately for reuse purposes.
Service Template / A Service Template is typically used to specify the “topology” (or structure) and “orchestration” (or invocation of management behavior) of IT services so that they can be provisioned and managed in accordance with constraints and policies.
Specifically, TOSCA Service Templates optionally allow definitions of a TOSCA Topology Template, TOSCA types (e.g., Node, Relationship, Capability, Artifact), groupings, policies and constraints along with any input or output declarations.
Topology Model / The term Topology Model is often used synonymously with the term Topology Template with the use of “model” being prevalent when considering a Service Template’s topology definition as an abstract representation of an application or service to facilitate understanding of its functional components and by eliminating unnecessary details.
Topology Template / A Topology Template defines the structure of a service in the context of a Service Template. A Topology Template consists of a set of Node Template and Relationship Template definitions that together define the topology model of a service as a (not necessarily connected) directed graph.
The term Topology Template is often used synonymously with the term Topology Model. The distinction is that a topology template can be used to instantiate and orchestrate the model as a reusable pattern and includes all details necessary to accomplish it.
Abstract Node Template / An abstract node template is a node that doesn’t define an implementation artifact for the create operation of the TOSCA lifecycle.
The create operation can be delegated to the TOSCA Orchestrator.
Being delegated an abstract node may not be able to execute user provided implementation artifacts for operations post create (configure, start etc.).
No-Op Node Template / A No-Op node template is a specific abstract node template that does not specify any implementation for any operation.

2  Summary of key TOSCA concepts

The TOSCA metamodel uses the concept of service templates to describe cloud workloads as a topology template, which is a graph of node templates modeling the components a workload is made up of and as relationship templates modeling the relations between those components. TOSCA further provides a type system of node types to describe the possible building blocks for constructing a service template, as well as relationship type to describe possible kinds of relations. Both node and relationship types may define lifecycle operations to implement the behavior an orchestration engine can invoke when instantiating a service template. For example, a node type for some software product might provide a ‘create’ operation to handle the creation of an instance of a component at runtime, or a ‘start’ or ‘stop’ operation to handle a start or stop event triggered by an orchestration engine. Those lifecycle operations are backed by implementation artifacts such as scripts or Chef recipes that implement the actual behavior.