Assembly descriptors

Example of a properties section

properties:
  deploymentLocation: 
 ​   type: string​  
 ​   required: true
​    description: The name of the openstack project (tenant) to install this assembly in. 

  resourceManager:
​    value: '${resourceManager}'

  numOfStreamers: # the name of the property
​    type: string​
    description: the number of streamers that should be created at install time​    
    default: 2
    
  tenant_key_name:
​    type: string​
    required: true
​    description: The SSH key for the current tenant

flavor:
​    value: m1.small

cluster_public_ip_address:
​    type: string​
    description: the public IP address for this cluster​
    read-only: true​
    value: '${balancer.publicIp}'

Properties and required or optional status

Properties are optional unless they are explicitly defined as required by using a required: true attribute. The required status affects a higher-level assembly only and means that a value must be present (that is, not null) for a property.

If a value is required, it's a good idea to include it when you define the property. The inclusion of the value helps designers of other assembly descriptors to ensure that the value is represented in assemblies when the property is mapped or promoted. You can check the value in the value attribute, the default value, or in the value that is passed in from the intent request.

Read-only properties

Properties that are marked as read-only: true are not overridden by values that are mapped in from an enclosing assembly or from the intent request. The read-only attribute is typically used for properties that are calculated from, or returned by, the assembly instance itself.

Property values

You can assign a default value or a specific value to a property. To set a property value to the value of another property in the higher level properties section of the descriptor, use the following syntax:

value: '${<sourceProperty>}'

To set a higher level property value to the value of a property in a low-level properties section, include the name of the object that the low-level property belongs to. For example, if your descriptor contains a component that is called balancer, use the following syntax to set a higher level property to the value of the publicIp property for this component:

value: ‘${balancer.publicIp}’

The orchestration component assigns an internal name and identifier to each resource instance that it creates. It also supplies the index number of a resource in a cluster. These values can be useful when you define properties because they indicate the unique resource instance names. To access these values, you can set property values to references such as ${instance.name}, ${instance.id}, or ${instance.index}. The orchestration component then replaces the references with the appropriate values.

deploymentLocation and resourceManager properties

The deploymentLocation and resourceManager properties appear only in assembly descriptors.

In the deploymentLocation property, you specify the virtual infrastructure location where you want the resources that are created for this assembly instance to be deployed. For example, you might set the value of this property to the name of a Kubernetes namespace or an OpenStack tenant.

In the resourceManager property, you specify the name of the resource manager that manages the resources that are created for this assembly instance. This property must be set to Brent.

This example shows how you can assign scalar types to properties and set default and hard-coded values for each type:

msg:
    type: string
    default: "hello world"
  test_integer:
    description: This is the test integer description from the parent
    type: integer
    value: 100
  test_boolean:
    type: boolean
    default: true
    readOnly: true
  test_float:
    type: float
    value: 3.141592654
  test_timestamp:
    type: timestamp
    value: 2019-09-07T15:50-04:00
    volatile: true

test_list:
  type: list
  entry-schema:
    type: integer
    default: [-2147483648, 0, 2147483647]
test_map:
  type: map
  entry-schema:
    type: float
    description: This the the test map inner description from the parent
  default:
    floatkey1: -3.141592654
    floatkey2: 0.123456789
    floatkey3: 3.141592654
test_data:
  default:
    - { id: 'internal1', name: 'public1', nested-property: {first-level: '11', double-nested: {second-level: '12', deeply-nested: {third-level: '13'}}}}
    - { id: 'internal2', name: 'public2', nested-property: {first-level: '21', double-nested: {second-level: '22', deeply-nested: {third-level: '23'}}}}
    - { id: 'internal3', name: 'public3', nested-property: {first-level: '31', double-nested: {second-level: '32', deeply-nested: {third-level: '33'}}}}
  type: list
  entry_schema:
    type: map
  description: Array of structured data to be passed to the 'D' group

After you define maps and lists that contain data, you can access the data and map it into other descriptor properties. You can map both scalar and structured data.

In this example, string values from the structured list are mapped to component properties by setting the value attribute for each component property to a list value. The list value that each component property is mapped to is indicated by a comment, that is, //.

properties:
  test_map:
    type: map
    default: { id: 'internal1', 
               name: 'public1', 
               list-property: ['entry1', 'entry2', 'entry3'],
               nested-property: 
                 {first-level: '11', 
                 nested-list: ['entry12', 'entry22', 'entry32'],
                 double-nested: {second-level: '12', 
                                 deeply-nested: {third-level: '13'}}}}
​    ...

composition:
      ...
    component1:
        properties:
            data-nested1-value:
                value: ${test_map.nested-property.first-level}  // value = '11'
            data-nested2-value:
                value: ${test_map.nested-property.double-nested.second-level} // value = '12'
            data-nested3-value:
                value: ${test_map.nested-property.double-nested.deeply-nested.third-level} // value = '13'
            data-list-first-value:
                value: ${test_map.list-property[0]} // value = 'entry1'
            data-nested-list-second-value: 
                value: ${test_map.nested-property.nested-list[1]} // will be set to value 'entry22'  

In the operations section, you specify the component operations that you want to make available to higher-level assembly descriptors that include this assembly in relationships.

Operations and relationships

Relationships between assembly components are created and ceased through the calling of operations. Each component can be a resource or another assembly.

Operations are described in resource descriptors. After you describe a resource's operations, you can define relationships that call these operations in the relationships section of the containing assembly descriptor. When you define a relationship that involves a resource, you can specify which of the resource's operations are called when the relationship is created or ceased.

Similarly, when you define a relationship that involves another assembly, you might want the relationship to call operations for that other assembly. In this case, you must first ensure that these operations are exposed in that other assembly’s descriptor by including them in its operations section. This process is known as publishing operations.

Publishing operations

In an assembly descriptor, you publish operations so that they can be called from higher-level descriptors that contain the assembly and use it in relationships.

When you publish an operation by including it in the operations section, use the following format:

​    <assembly_operation_name>:
​        source-operation: <component_name>.<component_operation_name>

• <assembly_operation_name> is the name that you want to use to publish this operation in this assembly. This name must be used by higher-level descriptors that call this operation.
• <component_name> is the name of the component that contains the operation that you want to publish.
• <component_operation_name> is the defined name of the operation in the component’s descriptor.

Examples

In this example, three components are shown with their properties omitted. The quantity of the streamer component is inherited from the numOfStreamers property, which is an assembly-wide property that is defined in the higher level properties section of the descriptor.

The upgrade-dependencies attribute specifies that, if a planned Reconfigure or Upgrade lifecycle transition is to be run on the net_video component, the transition must be run on the streamer component first.

composition:
  streamer: # The component name
​    type: resource::c_streamer::1.0
​    quantity: ${numOfStreamers}
​    properties:
​      ...

  balancer:
​    type: resource::c_balancer::1.0
​    quantity: 1
​    properties:
​      ...

  net_video:
​    type: resource::net_video::1.0
​    quantity: 1
​    properties:
​      ...
    upgrade-dependencies:
      - streamer

This example shows one component with seven properties. The values for some of the properties, such as deploymentLocation and resourceManager, are inherited from assembly-wide properties that are defined in the higher level properties section.

composition:
  streamer:
​    type: resource::c_streamer::1.0
​    cluster:
​      ...
​    properties:
​      deploymentLocation:
​        value: '${deploymentLocation}'
​      resourceManager:
​        value: '${resourceManager}'
​      flavor:
​        value: m1.small
​      server_name:
​        value: ${instance.name}
​      referenced-video-network:
​        value: ${net_video.network-id}
​      availability_zone:
​        value: DMZ
​      mgmtIp:
​        type: string
​        description: MGMT IpAddress of server
​        read-only: true

This example shows how a cluster of instances can be defined for a component. This cluster can contain a minimum of one instance and a maximum of four, and only one instance can be added or removed through scaling. The initial number of instances that are created when an intent request is submitted is inherited from the assembly-wide numOfServers property.

composition:
  streamer:
​    type: resource::c_streamer::1.0
​    cluster:
​      initial-quantity: ${numOfServers}   
​      minimum-nodes: 1                    
​      maximum-nodes: 4                    
​      scaling-increment: 1                

​    properties:
​      data:
​        value: ${data}
​      ip_address:
​        read-only: true

Defining component instance groups by using lists

This example shows how the streamer component is defined from a list of three items, which is called streamers and is defined as a higher level assembly property.

properties:
  streamers:
    type: list
    entry_schema:
      type: string
      default: ['192.0.2.1', '192.0.2.2', '192.0.2.3']
...
composition:
  streamer:
​    type: resource::c_streamer::1.0
​    items: ${streamers}
​    properties:
​      data:
​        value: ${item}

When an intent request is submitted, an instance of the c_streamer resource is created for each item in the list. In each instance, the value of the data property is set to the value of the list item. For example, in the first component instance, the value of the data property is set to 192.0.2.1.

Component instances that are created from a list are named based on their index in the list. In the case of the previous example, the component instances are named as follows:

{Assembly Name}__streamer__1
{Assembly Name}__streamer__2
{Assembly Name}__streamer__3

This naming strategy applies to fixed-size and cluster component groups.

Tip: The sequencing of component list items can affect how topology differences are calculated after subsequent intent requests are submitted. If the list is reordered, or if elements are removed, the topology might appear differently, because the list index forms part of the component instance name. Other unexpected changes might also occur. If items in a list of components might be reordered or removed, consider using a map to define the component group instead.

Defining component instance groups by using maps

This example shows how the streamer component is defined from a map that is called streamers, which is defined as a higher level assembly property. This map contains three maps, each of which contains an ip_addr key-value pair.

properties:
  streamers:
    type: map
    entry_schema:
      type: map
      default:
        - {first: {ip-addr: '192.0.2.1'}}
        - {second: {ip-addr: '192.0.2.2'}}
        - {third: {ip-addr: '192.0.2.3'}}
...
composition:
  streamer:
​    type: resource::c_streamer::1.0
​    items: ${streamers}
​    properties:
​      data:
​        value: ${item.ip_addr}

When an intent request is submitted, an instance of the c_streamer resource is created for each item in the map. Each instance is named based on the assembly name, the component name, and the key of the map item. As a result, the instances have the following names:

{Assembly Name}__streamer__first
{Assembly Name}__streamer__second
{Assembly Name}__streamer__third

In each instance, the value of the data property is set to the value of the ip_addr key in each map item. For example, in the {Assembly Name}__streamer__first instance, the value of the data property is set to 192.0.2.1.

Resolving descriptor versions dynamically

You can also resolve the version of a descriptor based on the available descriptors in the system. To resolve the descriptor version, use a resolveVersion filter in the dynamic type expression.

In this example, if the value of the component instance's serverType property is Dell, the resolveVersion filter determines that any version of the t_simple descriptor from 1.0 onwards can be used.

composition:
  A:
    type: resource::not_found::1.0
    dynamicType: >-
      {% if serverType == 'Dell' %}
        {{ 'resource::t_simple::[1.0,)'|resolveVersion }}
      {% elif serverType == 'Supermicro' %}
        {{ 'resource::t_simple_indexed::1.0' }}
      {% else %}
        {{ 'resource::t_simple::1.0' }}
      {% endif %}
    items: ${data}

To determine the version, the resolveVersion filter is run on the text in quotes that precedes the pipe symbol (|) , that is, 'resource::t_simple::[1.0,)'. The filter resolves the version range, that is, [1.0,). This range indicates that the earliest version that can be used is 1.0, and any later version can be used. The filter then queries the Apollo descriptor catalog to identify the descriptor to use.

The version range must be specified by using the Maven version range syntax. You must provide at least a minimum version or a maximum version. For more information about acceptable Maven version ranges, see Version Range References in the Oracle documentation.

Restriction: The dynamicType expression is evaluated when an intent request is submitted. If a new descriptor version that matches the expression is added since the last update for an assembly, the descriptor version that is used for the component might change. This change might cause resources to be reconfigured or reinstalled.

Examples

In this example, two referenced instances are described. For the storage instance, the following information is provided to help the orchestration component to uniquely identify the instance:

• The type, name, and version of the instance's assembly descriptor. The exact version is not specified, but semantic versioning is used to restrict the range to versions between 1.0 and 1.9.
• Three property values, that is, deploymentLocation, resourceManager, and storage-name, that are defined in the higher level properties section of this assembly.

For the ucd_network instance, the following information is provided:

• The type, name, and version number of the referenced instance's resource descriptor.
• Three higher level assembly properties, that is, deploymentLocation, resourceManager, and management-network-name.

references:

  storage: # reference to an existing assembly instance
​    type: assembly::storage_cluster::^1.0
​    properties:
​      deploymentLocation:
​        value: '${deploymentLocation}'
​      resourceManager:
​        value: '${resourceManager}'
​      name:
​        value: '${storage-name}'

  management-network: # reference to a neutron network that was not created by the orchestration component 
​    type: resource::ucd_network::1.0
​    properties:
​      deploymentLocation:
​        value: '${deploymentLocation}'     
​      resourceManager:
​        value: '${resourceManager}' 
​      name: 
​        value: ${management-network-name}  

After the orchestration component identifies these instances, their properties can be accessed by using this syntax: ${<referenced-item-name>.<property-name>}

For example, when you describe a component that is called balancer, you might specify these attributes to access the id property from a referenced instance that is called management-network:

composition:
  balancer:
​    type: 'resource::c_balancer::1.0'
​    quantity: '1'
​    properties:
​      …
​      referenced-management-network:
​        value: '${management-network.id}'

Example

This example shows how you might configure a relationship between two components.

• The source component, that is, storage, provides the NFSMountpoint capability. The target component, that is, streamer, requires the RemoteNFSMountPoint capability.
• The relationship is created after the storage component reaches the Active state and before the streamer component reaches the Inactive state.
• When the relationship is created, the MountStorage operation, which is defined in the descriptor that the storage component is based on, is called.
• The relationship contains several properties, including remote_nfs_server_ip, which inherits the value of the privateIp property that is defined for the storage component. These properties can be used by the MountStorage and UnmountStorage operations.
• The relationship is ceased before the storage component leaves the Active state and before the streamer component leaves the Inactive state.
• When the relationship is ceased, the UnmountStorage operation, which is defined in the descriptor that the storage component is based on, is called.

relationships: 

  nfs_mount:
​    source-capabilities: 
​    - storage.NFSMountpoint

​    target-requirements: 
​    - streamer.RemoteNFSMountPoint

​    source-state: Active
​    target-state: Inactive

​    properties:
​      remote_nfs_port:
​        value: '2049'
​      remote_nfs_server_ip:
​        value: '${source.privateIp}'
​      remote_mount_point:
​        value: '/'
​      local_mount_point:
​        value: '/mnt'    

​    lifecycle:
​      Create:
​      - source.MountStorage
​      Cease:
​      - source.UnmountStorage

This example defines a customized data type, tag, which has one property, that is, name. In the server component properties, in the tags list, the entry-schema property is used to specify tag as the data type of each value in the list.

server:
  properties:
    tags:
      type: list
      entry-schema:
        type: tag

tag:
  properties:
    name:
      type: string

"server": [
   "tags": [
            {
              "name": "clustered"
            }
            {
              "name": "non-clustered"
            }
          ]

properties:
  sap:
    type: map
    entry-schema: sap-type
    default:
      id: "ident1"
      address-segment: "segment"
      cpd-or-virtual-link: 
      ...
  ...
data-types:
  base-type:
    properties:
      source:
        type: string
        description: details about the source of an object

  vnf-cpd:
    properties:
      vnfd-id:
        type: string
      ext-cpd-id:
        type: string
  
  ns-cpd:
    properties:
      ns-id:
        type: string
      ext-cpd-id:
        type: string   
        
  pnf-cpd:
    properties:
      pnf-id:
        type: string
      ext-cpd-id:
        type: string 

  virtual-link-desc:
    properties:
      virtual-link-desc:
        type: string

  associated-cpd-id:
    properties:
      vnf:
        type: vnf-cpd
      pnf:
        type: pnf-cpd
      ns:
        type: ns-cpd

  cpd-or-vl:
    properties:
      virtual-link-desc:
        type: virtual-link-desc
      associated-cpd-id:
        type: associated-cpd-id

  sap-type:
    derived-from: base-type
    properties:
      id: 
        type string
      address-assignment:
        type: string
      cpd-or-virtual-link:
        type: cpd-or-vl