Requirement mapping rules

[lauwers]

Substitution Mapping

Requirement Mapping Syntax

Requirement mapping differs from other mappings in the following two
ways:

1. It is possible for a substituted node to have multiple requirements
   with the same name, each of which may need to be mapped
   separately.
2. It is possible for the same requirement in a substituted node to be
   mapped multiple times.

To accommodate this use case, requirement mappings are defined using
YAML lists rather than maps.

Mapping Multiple Requirements with the Same Name

The following example shows a Client node type that defines a
service requirement with a count_range of [2, 2], which means
that client nodes need exactly two relationships to nodes of type
Server.

tosca_definitions_version: tosca_2_0

capability_types:
  Service:
    description: >-
      Ability to provide service.
        
relationship_types:
  ServedBy:
    description: >-
      Connection to a service.
      
node_types:
  Client:
    requirements:
      - service:
          capability: Service
          relationship: ServedBy
          node: Server
          count_range: [ 2, 2]
  Server:
    capabilities:
      service:
        type: Service

This following figure shows a service that consists of one such client
node connected to two server nodes.

graph LR;
    subgraph T [Simple Service]
      client --> |service| server1 
      client --> |service| server2
    end

Loading

This service can be implemented using the following TOSCA service
template:

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml
  
service_template:
  node_templates:
    server1:
      type: Server
    server2:
      type: Server
    client:
      type: Client
      directives: [ substitute ]
      requirements:
        - service: server1
        - service: server2

In this template, the client nodes is annotated with the
substitute directive, which means that a substituting template must
be found to instantiate this node. The following figure shows one
possible substitution.

graph BT
    S --> |substitutes| client

    subgraph T [Top-Level Topology]
        client --> |service| server1 
        client --> |service| server2
    end
    
    subgraph S [Substituting Topology]
        direction BT
        software1 --> |host| compute
        software2 --> |host| compute
        software1 -.-> |service| server1
        software2 -.-> |service| server2
   end

Loading

The substituting template decomposes the client node into two
different software nodes, each with exactly one service
requirement. The requirement mapping syntax distributes the two
service requirements from the substituted client node between the
two software nodes. The following code snippet shows the substituting
template:

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml

capability_types:
  Host:
    description: >-
      Ability to host software.
        
relationship_types:
  HostedOn:
    description: >-
      Relationship to a host.
      
node_types:
  ClientSoftware:
    requirements:
      - host:
          capability: Host
          relationship: HostedOn
      - service:
          capability: Service
          relationship: ServedBy
          count_range: [ 1, 1 ]
  Compute:
    capabilities:
      host:
        type: Host

service_template:
  substitution_mappings:
    node_type: Client
    requirements:
      - service: [ software1, service ]
      - service: [ software2, service ]
  node_templates:
    software1:
      type: ClientSoftware
      requirements:
        - host: compute1
    software2:
      type: ClientSoftware
      requirements:
        - host: compute2
    compute1:
      type: Compute
    compute2:
      type: Compute

The following template shows an alternative substitution. In this
example, both service requirements of the substituted client node
are mapped to corresponding requirements of a single software node:

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml

capability_types:
  Host:
    description: >-
      Ability to host software.
        
relationship_types:
  HostedOn:
    description: >-
      Relationship to a host.
      
node_types:
  ClientSoftware:
    requirements:
      - host:
          capability: Host
          relationship: HostedOn
      - service:
          capability: Service
          relationship: ServedBy
          count_range: [ 2, 2 ]
  Compute:
    capabilities:
      host:
        type: Host

service_template:
  substitution_mappings:
    node_type: Client
    requirements:
      - service: [ software, service ]
      - service: [ software, service ]
  node_templates:
    software:
      type: ClientSoftware
      requirements:
        - host: compute
    compute:
      type: Compute

This example shows two identical mappings for the two service
requirements. As a convience feature, it is possible to group
identical mapping statements using the syntax in the following
example. This syntax states that two service requirements of the
substituted node are mapped to two corresponding service
requirements of the software node in the substituting template.

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml

capability_types:
  Host:
    description: >-
      Ability to host software.
        
relationship_types:
  HostedOn:
    description: >-
      Relationship to a host.
      
node_types:
  ClientSoftware:
    requirements:
      - host:
          capability: Host
          relationship: HostedOn
      - service:
          capability: Service
          relationship: ServedBy
          count_range: [ 2, 2 ]
  Compute:
    capabilities:
      host:
        type: Host

service_template:
  substitution_mappings:
    node_type: Client
    requirements:
      - [service, 2 ]: [ software, service ]
  node_templates:
    software:
      type: ClientSoftware
      requirements:
        - host: compute
    compute:
      type: Compute

Mapping Requirements Multiple Times

Imagine a scenario wher nodes of type Client need to be hosted on
nodes of type Compute as shown by the following type definitions:

tosca_definitions_version: tosca_2_0

capability_types:
  Host:
    description: >-
      Ability to host software.
        
relationship_types:
  HostedOn:
    description: >-
      Relationship to a host.
      
node_types:
  Client:
    requirements:
      - host:
          capability: Host
          relationship: HostedOn
          node: Compute
          count_range: [1, 1]
  Compute:
    capabilities:
      host:
        type: Host

The following template shows such nodes and their relationships:

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml
  
service_template:
  node_templates:
    compute:
      type: Compute
    client:
      type: Client
      directives: [ substitute ]
      requirements:
        - host: compute

The following shows a substituting template that decomposes the node
of type Client into two software components, each of which needs to
be hosted on the compute node defined in the top-level template that
defines the client node. This can be accomplished by mapping the
host requirement of the client node twice, once to the host
requirement of the software1 node and once to the host requirement
of the software2 node.

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml

node_types:
  ClientSoftware:
    requirements:
      - host:
          capability: Host
          relationship: HostedOn
          count_range: [ 1, 1 ]

service_template:
  substitution_mappings:
    node_type: Client
    requirements:
      - host:
          - [ software1, host ]
          - [ software2, host ]
  node_templates:
    software1:
      type: ClientSoftware
    software2:
      type: ClientSoftware

Using this syntax, the target of the requirement mapping is a list
of target requirements rather than a single requirement.

Requirement Mapping Rules

This section documents the rules for requirement mapping. The types
defined in the following code snippet are used to illustrate the
rules:

tosca_definitions_version: tosca_2_0

capability_types:
  Service:
    description: >-
      Ability to provide service.
        
relationship_types:
  ServedBy:
    description: >-
      Connection to a service.
      
node_types:
  Client:
    requirements:
      - service:
          capability: Service
          relationship: ServedBy
          node: Server
          count_range: [ 1, 4 ]
  Server:
    capabilities:
      service:
        type: Service

In this example, the Client node type defines a service
requirement with a count_range of [1, 4]. This means that a client
can have up to four service connections to a Server node, but only
one of those is mandatory.

Requirement Assignments

Any service template that uses the Client node type must specify the
correct number of requirement assignments, i.e, the number of
mandatory requirements must be greater than or equal to the lower
bound of the count_range and he total number of requirement
assignments (optional as well as mandatory) must be less than or equal
to the upper bound of the count range.

The following shows a valid service template that uses Client and
Server nodes.

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml
  
service_template:
  node_templates:
    server1:
      type: Server
    server2:
      type: Server
    server3:
      type: Server
    client:
      type: Client
      directives: [ substitute ]
      requirements:
        - service: server1
        - service: server2
        - service: server3

In this example, the requirement assignments specify the target nodes
directly, but it is also valid to leave requirements dangling as
follows:

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml
  
service_template:
  node_templates:
    server1:
      type: Server
    server2:
      type: Server
    server3:
      type: Server
    client:
      type: Client
      directives: [ substitute ]
      requirements:
        - service: server1
        - service:
            optional: True
        - service:
            optional: True

In this example, only the first service assignment is mandatory. The
next two are optional. However, after the orchestrator fulfills the
dangling requirement, the resulting service topology for this second
example will likely be identical to the service topology in the first
example, since the orchestrator is able to fulfill both of the
optional requirements using server nodes in this topology.

Note that after requirements have been fulfilled, it no longer matters
whether the requirement were mandatory or optional. All that matters
is that if the service topology is valid, the number of established
relationships is guaranteed to fall within the count_range specified
in the corresponding requirement definition.

Mapping Requirements

This section introduces the rules for requirement mappings:

1. As in earlier versions of the spec, requirements from a
   substituted node can only be mapped onto dangling requirements
   in the substituting template.
2. The total number of requirements mapped onto mandatory
   requirements in the substituting template must not exceed the lower
   bound of the count_range in the corresponding requirement
   definition in the substituted node's type.
3. The total number of requirement mappings must not exceed the upper
   bound of the count_range in the corresponding requirement
   definition in the substituted node's type. Note that this is a
   convenience rule only, since according to rule 2, any excess
   mappings would have to map onto optional requirements, and as a
   result can safely be ignored.

Note that there are no constraints on the minimum number of
requirement mappings. More specifically, the total number of
requirement mappings is allowed to be smaller than the lower bound of
the count_range in the corresponding requirement definition.

The following code snippet shows a valid substituting template for the
client node in the template shown above:

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml

capability_types:
  Host:
    description: >-
      Ability to host software.
        
relationship_types:
  HostedOn:
    description: >-
      Relationship to a host.
      
node_types:
  ClientSoftware:
    requirements:
      - host:
          capability: Host
          relationship: HostedOn
      - service:
          capability: Service
          relationship: ServedBy
          count_range: [ 1, 1 ]
  Compute:
    capabilities:
      host:
        type: Host

service_template:
  substitution_mappings:
    node_type: Client
    requirements:
      - service: [ software, service ]
  node_templates:
    software:
      type: ClientSoftware
      requirements:
        - host: compute
    compute:
      type: Compute

While the substituted client node in the template above has three
requirement assigments with target nodes, only one of those
requirements is mapped to a requirement in the substituting template.

The next code snippet shows a slightly different substituting template
for the client node in the template shown above. This template
decomposes the client node into three different software nodes,
each with a single service requirement to its own server. The
substitution mapping defines three requirement mappings for the
service requirement of the client node, one to each of the
service requirements of the software nodes in the substituting
template.

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml

capability_types:
  Host:
    description: >-
      Ability to host software.
        
relationship_types:
  HostedOn:
    description: >-
      Relationship to a host.
      
node_types:
  ClientSoftware:
    requirements:
      - host:
          capability: Host
          relationship: HostedOn
      - service:
          capability: Service
          relationship: ServedBy
          count_range: [ 1, 1 ]
  Compute:
    capabilities:
      host:
        type: Host

service_template:
  substitution_mappings:
    node_type: Client
    requirements:
      - service: [ software1, service ]
      - service: [ software2, service ]
      - service: [ software3, service ]
  node_templates:
    software1:
      type: ClientSoftware
      requirements:
        - host: compute1
    software2:
      type: ClientSoftware
      requirements:
        - host: compute2
    software3:
      type: ClientSoftware
      requirements:
        - host: compute3
    compute1:
      type: Compute
    compute2:
      type: Compute
    compute3:
      type: Compute

Unfortunately, this substituting template is invalid. Since the
service requirement of each software node is mandatory, this
template needs three different service requirements in any node of
type Client for which it is a substitution. This cannot be
guaranteed, since the service requirement definition in the Client
node type specifies a count_range with a lower bound of one, which
means that only such requirement is guaranteed to exist.

The following shows a corrected version of this substituting template:

tosca_definitions_version: tosca_2_0

imports:
  - types.yaml

capability_types:
  Host:
    description: >-
      Ability to host software.
        
relationship_types:
  HostedOn:
    description: >-
      Relationship to a host.
      
node_types:
  ClientSoftware:
    requirements:
      - host:
          capability: Host
          relationship: HostedOn
      - service:
          capability: Service
          relationship: ServedBy
          count_range: [ 0, 1 ]
  Compute:
    capabilities:
      host:
        type: Host

service_template:
  substitution_mappings:
    node_type: Client
    requirements:
      - service: [ software1, service ]
      - service: [ software2, service ]
      - service: [ software3, service ]
  node_templates:
    software1:
      type: ClientSoftware
      requirements:
        - host: compute1
        - service:
            optional: False
    software2:
      type: ClientSoftware
      requirements:
        - host: compute2
    software3:
      type: ClientSoftware
      requirements:
        - host: compute3
    compute1:
      type: Compute
    compute2:
      type: Compute
    compute3:
      type: Compute

In this template, the service requirement of the ClientSoftware
node type is defined with a count_range of [0, 1], which means the
requirement is no longer mandatory. Only the software1 node template
annotates its service requirement as mandatory (using the optional: False statement). The other two software nodes leave their service
requirement optional. As a result, this is now a valid substituting
template for nodes of type Client that define a service
requirement with count_range equal to [1, 4].

Requirement mapping must take one more rule into account: if the
number of requirement mappings is greater than the lower bound of the
count_range, the orchestrator must first perform those mappings that
map requirements onto mandatory requirements in the substituting
template, and then it will perform the remaining mappings (which
presumably will map onto optional requirements in the substituting
template). This is done independent of the order in which the
requirement mappings are specified.

Handling UNBOUNDED Count Ranges

To be provided