Variability4TOSCA Specification 1.0 Release Candidate¶

This document specifies Variability4TOSCA which extends TOSCA Simple Profile in YAML Version 1.3 with conditional elements to model deployment variability. This includes conditional node templates, relationship templates, properties, artifacts, groups, policies, types, inputs, and imports. In the following, we discuss the differences and the processes to resolve the variability. The specification is under active development and is not backwards compatible with any previous versions.

Terminology¶

We quickly introduce some terminologies.

• A condition holds if the condition evaluates to true.
• An element is present if all assigned conditions hold.
• An element is absent if not all assigned conditions hold.
• A variability resolver is a TOSCA processor that resolves the variability of a variable service template, thus, derives a variability-resolved service template

Service Template¶

A service template must have the TOSCA definitions version tosca_variability_1_0. Such a service template is also called variable service template.

Topology Template¶

A topology template additionally contains a variability definition. Such a topology template is also called variable topology template.

Variability Definition¶

A variability definition defines variability inputs, variability presets, variability expressions, and variability options.

The following non-normative and incomplete example contains a variability definition which declares the variability input mode and two variability presets dev and prod are defined which either assigns mode the value dev or prod. Furthermore, two variability conditions is_dev and is_prod which evaluate if mode equals dev or prod, respectively.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

variability:
    inputs:
        mode:
            type: string

    presets:
        dev:
            name: Development
            description: Deploy the application on a private cloud
            inputs:
                mode: dev
        prod:
            name: Production
            description: Deploy the application on a public cloud
            inputs:
                mode: prod

    expressions:
        is_dev: { equal: [ { variability_input: mode }, dev ] }
        is_prod: { equal: [ { variability_input: mode }, prod ] }

Variability Input¶

A variability input is an input parameter which additionally has the following keywords.

For example, the following variability input has a value expression as default value assigned.

1
2
3
4

inputs:
    mode:
        type: string
        default_expression: <ValueExpression>

Variability Options¶

There are the following variability options. More specific options override wider set options. For example, the following options the mode strict is configured. This mode disables all default conditions and pruning. However, pruning of nodes is explicitly set by node_pruning, thus, nodes are pruned regardless of the set mode.

1
2
3

options: 
    mode: manual
    node_pruning: true

General Options¶

The following options are general options.

Default Condition Options¶

The following options are used to configure the default conditions of elements.

Pruning Options¶

The following options are used to configure the pruning of elements.

Checks Options¶

The following options are used to configure checks.

Solver Options¶

The following options are used to configure the solver.

Constraints Options¶

This is an experimental feature.

The following options are used to configure constraints.

Pruning Modes¶

There are several predefined pruning modes which provide different useful combinations of default conditions and the pruning of elements that can be directly used.

• manual: no default or pruning conditions are enabled at all
• consistent-strict: all default consistency conditions are enabled
• consitent-loose: consistency pruning is enabled
• default: all default conditions are enabled (consistency and semantic)
• semantic-strict: consistency pruning is enabled and semantic defaults
• semantic-loose: pruning is enabled everywhere (consistency and semantic)

v2¶

tosca_variability_1_0_rc_2 has the following default values.

1
2
3
4
5
6
7
8
9

mode: semantic-loose
node_default_condition_mode: incomingnaive-artifact-host
optimization_topology: min
optimization_topology_unique: true
optimization_technologies: max
optimization_technologies_mode: weight
technology_constraint: true
hosting_stack_constraint: true
relation_default_implied: true

Default Conditions¶

There are element-generic default conditions and type-specific default conditions. Element-generic default conditions are generic default conditions defined per element. However, type-specific default conditions are defined per type, e.g., node type, and, thus, override element-generic default conditions.

Element-Generic Default Conditions¶

The following element-generic default conditions can be assigned to elements.

Thereby, we define a consistency condition a condition which targets the consistency of the metamodel, thus, ensuring that the metamodel can be correctly parsed, e.g., a property must have a container. In contrast, a semantic condition targets semantic aspect of elements or the type system, e.g., a node without incoming relations is not used and can be removed.

Depending on the context, other default conditions are more applicable. The following default conditions can be chosen instead of the ones introduced above.

Type-Specific Default Conditions¶

Conditional types conflict with this feature!

Type-specific default conditions can be defined to override element-generic default conditions for specific type. A type-specific default condition is defined as follows and is supported for nodes, relations, properties, artifact, groups, and policies.

For example, the node type scenario.monitor defines a type-specific semantic default condition checking for the presence of its host.

1
2
3
4
5

type_specific_conditions:
    node_types:
        scenario.monitor:
            conditions: {host_presence: SELF}
            semantic: true

Technology Assignment Rules¶

Conditional types conflict with this feature!

Technology assignment rules can be defined to automatically select a deployment technology for a component. A technology assignment rule is defined as follows.

For example, the node type application can be deployed using the deployment technology terraform if the host is of type terraform_host.

1
2
3
4

technology_assignment_rules:
    terraform:
        - component: application
          host: terraform_host

Variability Preset¶

A variability preset predefines values for variability inputs that might be used when resolving variability.

For example, the following variability preset dev set the values of the two variability inputs mode and another_input but not of another_another_input.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

variability:
    inputs:
        mode:
            type: string

        another_input: 
           type: string

        another_another_input:
            type: string

    presets:
        dev:
            name: Development
            description: Deploy the application on a private cloud
            inputs:
                mode: dev
                another_input: another_value

Variability Expression¶

A variability expression is an expression which consists of operators and functions which are listed below. For example, the following expression returns the total amount of costs. This result might be used inside a variability condition to ensure that the deployment costs are within a specific budget.

1
2
3
4

topology_template:
   variability: 
       expressions:
           my_expression: {add: [{variability_input: costs_offering_a}, {variability_input: costs_offering_b}]}

There are different kinds of variability expressions, as displayed in Figure 1. Value expressions return any kind of value and logic expressions return Booleans.

Variability Condition¶

A variability condition is a logic expression targeting the presence of an element, as displayed in Figure 1. Allowed operators and functions are listed below. For example, the following variability condition is_prod evaluates to true if the variability input mode equals prod.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

topology_template: 
    variability:
        inputs: 
            mode: 
                type: string

        expressions:
            is_prod: {equal: [{variability_input: mode}, prod]}

    node_template:
        my_prod_node:
            type: my.prod.node
            conditions: {logic_expression: is_prod}

Node Template¶

A node template is a conditional element, thus, variability conditions and other options can be assigned. These conditions must hold otherwise the respective node template is not present. A node template can also hold conditional types, artifact, and properties.

For example, the following node template has a variability condition assigned.

1
2
3

prod_database:
    type: my.prod.db
    conditions: {logic_expression: is_prod}

Technology Template¶

A technology template is a conditional elements, thus, variability conditions and other options can be assigned. These conditions must hold otherwise the respective technology template is not present.

Type Assignment¶

A type is a conditional element, thus, variability conditions and further options can be assigned to a type assignment. These conditions must hold otherwise the respective relationship is not present.

For example, the following node template database has a conditional type switching between a development and production database.

1
2
3
4
5
6

database:
    type:
       - my.dev.db:
            conditions: <VariabilityCondition>
       - my.prod.db:
            conditions: <VariabilityCondition>

Requirement Assignment¶

A requirement assignment is a conditional element, thus, variability conditions and other options can be assigned. These conditions must hold otherwise the respective relationship is not present.

For example, the following requirement assignment host has a variability condition assigned.

1
2
3
4

requirements:
    - host:
          node: dev_runtime
          conditions: {logic_expression: is_dev}

Relationship Templates¶

A relationship template can contain conditional properties. Note, the presence of a relationship template is bound to the presence of the requirement assignment in which it is used. A relationship template can also hold conditional properties.

For example, the following relationship templates contains conditional properties.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

relationship_templates:
    my_relationship:
        type: my.relationship
        properties:
            -   property_one:
                    value: value_one
                    conditions: <VariabilityCondition>
            -   property_two:
                    value: value_two
                    conditions: <VariabilityCondition>

Property Assignment¶

A property is a conditional element, thus, variability conditions and other options can be assigned. These conditions must hold otherwise the respective relationship is not present. However, this only applies if the property assignment is wrapped as the following object and if it is used in a list.

These keywords are used to detect if a property assignment is wrapped. Thus, if any of these keywords must be used as value for property, then this property must be wrapped. For example, the property key_one has the value {value: the_value} and, thus, must be wrapped.

1
2
3
4
5
6
7

properties:
- key_one:
      value: {value: the_value}

- conditional_property:
      value: conditional_value
      conditions: <VariabilityCondition>

Group Template¶

A group is conditional element, thus, variability conditions and other options can be assigned. Depending on the group type the conditions are either assigned to the group itself or to the group members. A group can also hold conditional types and properties.

In general, the conditions are assigned to the group itself. These conditions must hold otherwise the respective group is not present. We refer to such a group also as conditional group.

However, if the group is derived from variability.groups.ConditionalMembers then the conditions are assigned to the group members. These conditions must hold otherwise the respective group members are not present in the variability-resolved service template. Furthermore, group elements can be node templates and requirement assignments. We refer to such a group also as variability group. A variability group is always absent and, thus, always removed when resolving variability.

For example, the following group example_group is a conditional group which is only present if assigned conditions hold.

1
2
3
4

conditional_group:
    type: tosca.groups.Root
    members: [prod_database, [application, prod_connects_to]]
    conditions: {logic_expression: is_prod}

However, the following group example_group assigns its assigned conditions to its members, i.e., the node template prod_database and the requirement assignment prod_connects_to of the node template application. In contrast to the previous example this group is not derived from variability.groups.ConditionalMembers. Thus, the presence of the node template prod_database depends on condition is_prod.

1
2
3
4

variability_group:
    type: variability.groups.ConditionalMembers
    members: [prod_database, [application, prod_connects_to]]
    conditions: {logic_expression: is_prod}

Policy Template¶

A policy template is a conditional element, thus, variability conditions and other options can be assigned. These conditions must hold otherwise the respective policy is not present. A policy can also hold conditional types and properties.

For example, the following policy template anticollocation has the variability condition is_prod assigned. Depending on the presence of this policy, the node templates wordpress and mysql must not be hosted on the same server, e.g., during production. For more information about this example, take a look in the TOSCA Simple Profile in YAML Version 1.3.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

node_templates:
    wordpress:
        type: tosca.nodes.WebServer
        requirements:
            - host:
                  node_filter:
                      capabilities:
                          - os:
                                properties:
                                    - architecture: x86_64
                                    - type: linux

    mysql:
        type: tosca.nodes.DBMS.MySQL
        requirements:
            - host:
                  node: tosca.nodes.Compute
                  node_filter:
                      capabilities:
                          - os:
                                properties:
                                    - architecture: x86_64
                                    - type: linux

policies:
    - anticollocation:
          type: tosca.policies.AntiCollocation
          targets: [wordpress_server, mysql]
          conditions: {logic_expression: is_prod}

Artifact Template¶

A (deployment) artifact is a conditional element, thus, variability conditions and other options can be assigned. These conditions must hold otherwise the respective artifact is not present. An artifact can also hold conditional properties.

For example, the following node template my_node has two artifacts artifact_a and artifact_b assigned which are both conditional.

1
2
3
4
5
6
7

my_node:
    type: my.node
    artifacts:
        - artifact_a:
              conditions: <VariabilityCondition>
        - artifact_b:
              conditions: <VariabilityCondition>

Topology Template Input¶

A topology template input is a conditional element, thus, variability conditions and other options can be assigned. These conditions must hold otherwise the respective input is not present.

For example, the topology template input has a variability condition assigned.

1
2
3
4

inputs:
   ssh_key_file:
       type: string
       conditions: <VariabilityCondition>

Import Definition¶

An import definition is a conditional element, thus, variability conditions and other options can be assigned. These conditions must hold otherwise the respective import is not present.

For example, the following import has a variability condition assigned.

1
2
3

import:
   - file: some_file
     conditions: <VariabilityCondition>

Normative Group Types¶

There are two normative group types variability.groups.Root and variability.groups.ConditionalMembers. The first group type is the root group every other variability-related group, such as variability.groups.ConditionalMembers should derive from.

1
2

variability.groups.Root:
    derived_from: tosca.groups.Root

The second group type should be used for variability groups.

1
2
3

variability.groups.ConditionalMembers:
    derived_from: variability.groups.Root
    conditions: VariabilityCondition | List(VariabilityCondition)    

Normative Interface Types¶

The following normative interfaces define a management interface for nodes and relationships. Currently, no management operations are defined. The definition is intended to be extended in other specifications, e.g., for building deployment artifacts after resolving variability.

Variability Management Interface for Nodes¶

The following interface manages the variability-related operations of nodes.

1
2

tosca.interfaces.node.management.Variability:
    derived_from: tosca.interfaces.Root

Variability Management Interface for Relationships¶

The following interface manages the variability-related operations of relationships.

1
2

tosca.interfaces.relationship.management.Variability:
    derived_from: tosca.interfaces.Root

Intrinsic Functions¶

The following intrinsic functions can be used inside a variability expression.

Logical Operators¶

The following logical operators can be used inside a logic expression.

Arithmetic Operators¶

The following arithmetic operators can be used inside a variability expression.

Presence Operators¶

The following presence operators can be used inside a logic expression.

String Operators¶

The following string operators can be used inside a variability expression.

Constraint Operators¶

The following constraint operators can be used inside a variability expression.

Analytical Operators¶

The following analytical operators can be used inside a variability expression.

Date Operators¶

The following date operators can be used inside a variability expression.

Plugin Definition¶

The following plugins can be defined.

Technology Plugin¶

A technology plugin must export the following interface.

1
2
3

export type TechnologyPluginBuilder = {
    build(graph: Graph): TechnologyPlugin
}

1
2
3

export type TechnologyPlugin = {
    assign: (node: Node) => {[technology: string]: TechnologyTemplate}[]
}

Processing¶

We describe on a high-level the steps to derive a variability-resolved service template from a variable service template.

Resolve Variability¶

To resolve the variability in a variable service template, conduct the following steps:

1. Ensure that TOSCA definitions version is tosca_variability_1_0.
2. Retrieve variability inputs assignments.
3. Check the presence of all elements.
4. Remove all elements, e.g., node templates or artifacts, which are not present.
5. Remove all group members which are not present from group template.
6. Remove all policy targets which are not present from policy template.
7. Remove all variability groups.
8. Remove all non-standard elements, e.g., variability definition, variability groups, or conditions at node templates.
9. Transform all lists introduced in this document, such as property lists, to maps as defined in TOSCA.
10. Set the TOSCA definitions version to tosca_simple_yaml_1_3.

Retrieve Variability Inputs Assignments¶

Variability inputs can be assigned either directly or indirectly using (possibly multiple) variability presets. Therefore, conduct the following steps:

1. Merge all variability presets following the order in which they have been collected.
2. Merge directly assigned variability inputs.

Thereby, inputs which are merged at a later step, override existing inputs. Thus, directly assigned variability inputs have the highest priority. For example, given the following variability definition.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

variability:
    inputs:
        mode:
            type: string
        another_input: 
            type: string
        another_another_input:
            type: string

    presets:
        dev:
            name: Development
            description: Deploy the application on a private cloud
            inputs:
                mode: dev
                another_input: dev
                another_another_input: dev
        prod:
            name: Production
            description: Deploy the application on a public cloud
            inputs:
                mode: prod
                another_input: prod

When the presets dev and prod are applied and the variability input mode is directly assigned to override, then the following variability inputs are retrieved.

1
2
3

mode: override
another_input: prod
another_another_input: dev

Check Element Presence¶

To check if an element is present, check that all assigned conditions hold:

1. Collect all conditions which are assigned to the element via conditions.
2. Collect all conditions which are assigned to variability groups via conditions which the element is member of.
3. (Optional) Assign default conditions if no conditions have been collected yet.
4. (Optional) Assign pruning conditions.
5. Evaluate assigned conditions.

The element is present if all conditions hold.

Conduct Checks¶

To conduct the consistency and semantic checks, conduct the following steps:

1. Ensure that each relation source of a present relation is present.
2. Ensure that each relation target of a present relation is present.
3. Ensure that every present node has at maximum one present hosting relation.
4. Ensure that the node of each present artifact is present.
5. Ensure that present artifacts have unique names within their node.
6. Ensure that the node of each present property is present.
7. Ensure that present properties have unique names within their node.
8. Ensure that the container of each present type is present.
9. Ensure that each present type container has exactly one present type.
10. Ensure that every present node has a present hosting relation if the node had at least one conditional relation in the variable
11. Ensure that every present node has a present incoming relation if the node had at least one incoming relation in the variable service template.
12. Ensure that every present node has a present deployment artifact if the node had at least one deployment artifact in the variable service template.

Since the derived variability-resolved service template might be further processed, e.g. by topology completion, some or all of these checks might be omitted.

Pruning Elements¶

To further support modeling, elements can be pruned by additionally evaluating the respective default condition before evaluating assigned conditions. For example, when evaluating if a property of a node template is present, then evaluate first if respective node template is present and then assigned conditions. Such pruning propagates through the whole topology. For example, the properties of a relationship template used in a requirement assignment of a node template which is not present are also not present.

There are element-generic default conditions and type-specific default conditions. Element-generic default conditions are generic default conditions defined per element. However, type-specific default conditions are defined per type, e.g., node type, and, thus, override element-generic default conditions.

Optimization¶

The variability-resolved service template can be optimized regarding the weight of node templates. The default weight of a node template is 1. Per default, the variability-resolved service template is optimized regarding the minimal weight/ number of node templates. The primary intention is to minimize the deployment complexity, but optimization could be also used, e.g., to minimize overall costs. The weight of a node template can be configured in its definition. Moreover, technology selection can be optimized.

Element System¶

When introducing conditional elements, we follow typically the approach of using a list whose entries are maps that contain a single element. Thus, elements can just be defined as usual but in a list (instead of a map) and can even share the same names. This has some implication on managing elements which we are discussing in the following.

Element Collections¶

As an overview, the following table shows the collections that are used in TOSCA and the ones which are used in Variability4TOSCA.

Element Uniqueness¶

As an overview, the following table shows the uniqueness of elements in TOSCA and in Variability4TOSCA in terms of identifiers, such as the key in a map. This is directly related to the used collections.

Element Identifier System¶

Each element has an identifier that is unique per (variable) service template. This identifier system is required since some conditional elements, such as artifacts, can have non-unique names. The identifier of an element is constructed as follows.

1

<Element Type>.<Element Name>[@<Element Index>][.<Element Container ID>]

Available element types are node, relation, property, group, policy, artifact, input, type, and import.

For example, consider the given variable service template.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

node_templates:
    my_node:
        type: my.node
        properties:
           - my_property:
                value: first
                conditions: <VariabilityCondition>
           - my_property:
                value: second
                conditions: <VariabilityCondition>
        artifacts:
           - my_artifact:
                file: path/to/my_artifact_first
                conditions: <VariabilityCondition>
           - my_artifact:
                file: path/to/my_artifact_second
                conditions: <VariabilityCondition>

Next, the following identifiers, among others, exist.

• node.my_node for the node template my_node.
• property.my_property@0.node.my_node for the first property my_property of the node template my_node.
• artifact.my_artifact@1.node.my_node for the second artifact my_artifact of the node template my_node.

Element Display System¶

Each element has a display representation that is unique per (variable) service template. This display system is required since some conditional elements, such as artifacts, can have non-unique names. The display representation of an element is constructed as follows.

1

<Element Type> "<Element Name>[@<Element Index>]"[ of <Element Container Display>]

Available element types are Node, Relation, Property, Group, Policy, Artifact, Input, Type, and Import.

For example, consider the given variable service template.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

node_templates:
    my_node:
        type: my.node
        properties:
           - my_property:
                value: first
                conditions: <VariabilityCondition>
           - my_property:
                value: second
                conditions: <VariabilityCondition>
        artifacts:
           - my_artifact:
                file: path/to/my_artifact_first
                conditions: <VariabilityCondition>
           - my_artifact:
                file: path/to/my_artifact_second
                conditions: <VariabilityCondition>

Next, the following display representations, among others, exist.

• Node "my_node" for the node template my_node.
• Property "my_property@0" of Node "my_node" for the first property my_property of the node template my_node.
• Artifact "my_artifact@1" of Node "my_node" for the second artifact my_artifact of the node template my_node.

Reference Implementation¶

We provide a reference implementation for this specification as part of OpenTOSCA Vintner. OpenTOSCA Vintner is a TOSCA preprocessing and management layer. The project is open-source, licensed under Apache-2.0, and publicly available at GitHub.

Acknowledgments¶

This specification is developed for the purpose of research by the Institute of Software Engineering (ISTE) and the Institute of Architecture of Application Systems (IAAS) of the University of Stuttgart, Germany. The development is partially funded by the German Federal Ministry for Economic Affairs and Climate Action (BMWK) as part of the Software-Defined Car (SofDCar) project (19S21002).

Correspondence¶

Please address all correspondence concerning this specification to Miles Stötzner <miles.stoetzner@iste.uni-stuttgart.de, https://miles.stoetzner.de>.

Disclaimer of Warranty¶

Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.