A Orchestration Templates

An orchestration is stored in a file in JSON format.

The following sample JSON file shows the high-level structure of an orchestration. The primary structure is called an object plan (oplan). In a single orchestration, you can include up to 10 oplans. Oplans contain objects and can have dependencies declared through relationships.

Note:

The orchestration templates use placeholder text for object names, labels, and other user-specific values. When you use these templates to build your orchestration, remember to replace placeholder values with values specific to your environment.
In the JSON file, a comma is required between each element of an orchestration.

{
    "description": "someDescriptionHere",
    "name": "/<tenant_name>/public/<orchestration_name>",
    "oplans": [
        {
            "ha_policy": "active",
                "label": "someText",
            "obj_type": "objectType",
            "objects": [
                {
                    definitions of objects specific to this object type
                }
            ]
        },
        {
            "label": "someText",
            "obj_type": "objectType",
            "objects": [
                {
                    definitions of objects specific to this object type
                }
            ]
        },
                                        .
                                        . up to 10 oplans
                                        .
    ]
}

Note:

An object is used with an orchestration to encapsulate the various orchestratable system components. For example, for a launch plan, the obj_type is launchplan. The fields in the objects section vary with the object type.

The following table describes the elements in the orchestration.

Table A-1 Orchestration Elements

Object Identifier	Description	Permitted Elements or Value
`description`	A description of the orchestration	Text that describes the orchestration.
`name`	Name of the orchestration. It consists of three components and begins with `/tenant_name/public/` Example: `/mytenant/public/single_instance`	Text that provides the name of the orchestration.
`oplans`	An object plan is the primary structure of the orchestration for defining objects in an orchestration.	A list of oplans that have elements for defining different objects in an orchestration: `ha_policy`, `label`, `obj_type`, and `objects`.
`label`	User-specified name for an object. Labels are used to specify relationships and appear in error messages at the orchestration level to identify an oplan that is in error.	Text that describes the object.
`relationships`	A container structure to specify the sequence in which the components in an orchestration start. In the relationships section of the orchestration, specify the labels of the oplans and the relationship type.	A JSON structured element that describes the relationship.

The following table describes the elements in the oplans.

Table A-2 Oplan Elements

Object Identifier Description Permitted Values or Elements

Object Identifier	Description	Permitted Values or Elements
`ha_policy`	An optional element to specify a high availability policy for an object type (`obj_type`). If you do not want high availability or monitoring, do not include the `ha_policy` element. Launch plans are monitored by default.	`active`: Only set for object type `launchplan`. `monitor`: Only set for object types launchplan and `storage/volume`. `none`: To disable HA policy or for using with objects that not supported.
`obj_type`	A type of object to be defined.	`launchplan`, `storage/volume`, and `vnetreservation`.
`objects`	A container structure for defining objects for an object type.	`launchplan`: instances, relationships. `storage/ volume`: name, size, properties. `ip/reservation`: vnetreservation.

ha_policy

An optional element to specify a high availability policy for an object type (obj_type).

If you do not want high availability or monitoring, do not include the ha_policy element. Launch plans are monitored by default.

active: Only set for object type launchplan.

monitor: Only set for object types

launchplan

and storage/volume.

none: To disable HA policy or for using with objects that not supported.

obj_type

A type of object to be defined.

launchplan, storage/volume, and vnetreservation.

objects

A container structure for defining objects for an object type.

launchplan: instances, relationships.

storage/ volume: name, size, properties.

ip/reservation: vnetreservation.

Unless they were created beforehand, the network, storage, or other objects referred to in an orchestration are created when the orchestration starts, and they are destroyed when the orchestration stops.

The orchestration structure and the schema for its elements are described in detail in the following sections.

Orchestration Structure

{
"name": <string>,
"description": <string>,
"oplans": [ <oplan>,...]
"relationships": [ <oplan_relationship>,...] (optional)
}

The following table describes the elements of the orchestration.

Fields	Description
`name`	Name of the orchestration plan
`description`	Description of the orchestration plan
`oplans`	List of oplans
`relationships`	A list of relationship specifications to be satisfied on this orchestration

Orchestration Template for Oplans

An object plan, or oplan, is a top-level orchestration attribute. Within an object plan, you can specify various object types and define one or more objects for each object type.

{
"label": <string>
,"obj_type": "launchplan" | "storage/volume",
"objects": [ <objtype_launchplan>,...] | [ <objtype_storagevolume>,...]
"ha_policy": "monitor" | "active", (optional)
}

The following table describes the object plan attributes.

Fields	Description
`ha_policy`	Determines the HA behavior of an oplan. Specifying `active` applies only to launch plans and if an instance terminates unexpectedly, then the instance is automatically restarted. Specifying `monitor` applies to all object types: the state of all the objects is monitored so changes in state are reflected in the orchestration. If `ha_policy` is not specified, then storage volumes are not monitored. Launch plan are monitored by default and omission of this property does not have any effect on objects of type `launchplan`.
`label`	Description of the oplan.
`obj_type`	Type of the object.
`objects`	List of all objects of type `obj_type`.

Oplan Relationship

{
 "oplan": <string>,
 "to_oplan": <string>,
 "type": "depends",
}

The following table describes the attributes of oplan relationship.

Fields	Description
`oplan`	Label of `oplan1`
`to_oplan`	Label of an oplan on which `oplan1` depends
`type`	Type of the relationship. It must be `depends`.

Orchestration Template for Object Type: Launch Plan

Use this object type if you want to define one or more instances. In an orchestration, instance is an attribute of the launchplan object type.

{
 "instances": [ <instance>,...]
 "relationships": [ <instance_relationship>,...] (optional)
}

The following table describes the attributes for launchplan.

Fields	Description
`instances`	List of instances defined by the launch plan.
`relationships`	List of relationships that exist between the instances in the launch plan and the instances that are currently running.

Orchestration Template for Object Type: Storage/Volume

Use this object type to create storage volumes that you want to attach to your instances.

{
"name": <string>,
"properties": [ <string>, ...]
"size": <string>,
"description": <string>, (optional)
"source_storagevolume_name": <string>, (optional)
"imagelist": <string>, (optional)
"imagelist_entry": <number>, (optional)
"tags": [ <string>, ...] (optional)
"quota": <string>, (optional)
}

The following table describes the attributes for storage/volume.

Fields	Description
`name`	Name of the storage volume
`properties`	A list of the storage properties that are associated with this storage volume.
`size`	The size of this storage volume measured in the number of bytes or multiples of bytes
`description`	Description of the storage volume.
`source_storagevolume_name`	Name of existing storage volume to copy from onto this volume when created. Cannot be used when specifying imagelist option.
`imagelist`	Name of the machine image to extract onto this volume when created. Cannot be used when specifying the `source_storagevolume_name` option.
`imagelist_entry`	Specific image list entry version to extract.
`tags`	A list of strings that will tag the storage volume.
`quota`	The quota against which this volume will be created.

Instance Attributes

In an orchestration, instance is an attribute of the launchplan object type. If any of the objects referred to in instance attributes are defined in the same orchestration as the instance, you must specify a relationship between each object and the instance launch plan.

{
"shape": <string>,
"networking": <string>,
"imagelist": <string>,
"label": <string>, (optional but recommended)
"name": <string>, (optional but recommended)
"storage_attachments": [ <storage_attachment>, ...] (optional)
"tags": [ <string>, ...] (optional)
"attributes": <userdata>, (optional)
"nis": <nis>, (optional)
"sshkeys": [ <string>, ...] (optional)
"entry": <number>, (optional)
"quota": <string>, (optional)
}

The following table describes the attributes for instances.

Fields	Description
`shape`	Defines the size or resource requirements (memory/CPUs) for the instance. Must correspond to one of the shapes defined in the site configuration.
`networking`	Mapping of the device name to network specifiers for virtual NICs to be attached to the instance.
`imagelist`	Name of the image list to be launched.
`label`	A label assigned by the user, specifically for defining inter-instance relationships. Optional but recommended. Also used in some error and status messages. If not specified, a label will be automatically assigned.
`name`	Name of the instance generated by the server. It is optional but recommended. Specifying a name prefix makes it easier to find and identify the instances when using CLI commands, such as `list instance`. Users can specify a name prefix and a system generated UUID will be appended to the prefix. Example: `tenant_name/public/instance_name` results in the instance name `tenant_name/public/instance_name/uuid`. If the name is not specified, the name will be `tenant_name/public/uuid`.
`storage_attachments`	List of dictionaries that contain storage attachment information.
`tags`	A list of strings that will tag the instance.
`attributes`	A collection of user-defined key and value pairs that is made available to an instance through the metadata service.
`placement_requirements`	Not applicable.
`nis`	Network Information Service configuration.
`sshkeys`	The SSH key that is installed on the instance.
`entry`	Optional image list entry number. The default will be used if one is not specified.
`quota`	The quota against which this instance will be run.

Relationships Attributes

In an orchestration, relationships is an attribute of the launchplan object type.

{
"instances": [ <string>, ...]
"type": "same_node" | "different_node",
}

The following table describes the attributes for relationships.

Fields	Description
`instances`	List of instance labels. Can also use `instance: running instance name` to create a relationship between an instance in the `launchplan` and an instance that is already running.
`type`	Type of relationship between the specified instances.

nis Attributes

{    
"domain": <string>,    
"servers": [ <nis_server>, ... ] 
}

The following table describes the nis attributes.

Fields	Description
`domain`	The NIS domain name.
`servers`	List of NIS server entries.

nis_server Attributes

{    
"name": <string>,    
"ip": <string>, 
}

The following table describes the attributes for nis_server.

Fields	Description
`name`	The name of the NIS server.
`ip`	The IP address of the NIS server.

userdata Attributes

{    
"userdata": { <string>: <string>, ... } 
}

The following table describes the attributes for userdata.

Fields	Description
`userdata`	A collection of user-defined key and value pairs that will be made available to an instance through the metadata service.

Networking Attributes

{    <string>: <networkblock>,
...
 }

The following table describes the attributes for networking.

Fields	Description
`string`	A unique label for the network described by `networkblock`. A short string is used such as `net0`. Network entries are processed in sorted order using this key and not the order they appear in the document.

storage_attachment Attributes

{    
"volume": <string>,    
"index: <number>, 
}

The following table describes the attributes for storage_attachment.

Fields	Description
`volume`	Name of the storage volume to which the instance will be attached.
`index`	The integer index used when generating the device name, for example, 1 in `/dev/sda1`.

networkblock Attributes

{    
"vnet" | "vnetreservation": <string>,    
"options": <networkblock_options>, (optional) 
}

The following table describes the attributes for networkblock.

Fields	Description
`vnet`	The full vNet name. Only one vNet or vNet reservation can be specified.
`options`	The set of options for the networking configuration of the instance. When more than one network contain options, the first block to specify a particular option is used and the others are ignored.

networkblock_options Attributes

{    
 "dns": <networkblock_dns>, (optional)   
  "hostname": <string>, (optional)    
 "network_route": [ <networkblock_route>,... ] (optional)    
 "default_gateway": <boolean>, (optional)   
 "provider": <boolean>, (optional)    
 "primary": <boolean>, (optional) 
}

The following table describes the attributes for networkblock_options.

Fields	Description
`hostname`	Specifies the host name associated with the instance network IP. When multiple host names are specified on multiple networks, the primary host name must be indicated with boolean `primary` attribute. Otherwise, the host name on the first network (sorted by key) is used as the instance host name.
`network_route`	A list of routing rules.
`default_gateway`	A Boolean flag that indicates that this network's gateway must be used for default routing. The default is false if not set.
`provider`	A Boolean flag that can be used to configure the instance as a provider (full membership) on an underlying service network.
`primary`	A Boolean flag that indicates that the host name specified for this network must be used as the instance host name. The default is false if not specified. If not specified as true for any network, then the first network (sorted by key) will be used as the instance host name.

networkblock_dns Attributes

{    
"search_domains": <string>,    
"servers": <string>, 
}

The following table describes the attributes for networkblock_dns.

Fields	Description
`search_domains`	A single string in comma-separated value format that specifies the set of DNS search domains to configure for the instance.
`servers`	A single string in comma-separated value format that specifies the set of DNS servers to configure for the instance.

networkblock_route Attributes

{    
"type": "rule" | "static" | "policy"    
"name": "SameNICReply" # only if "rule"    
"ip_network": <string>, # only if "static" or "policy"    
"via": <string>,       # only if "static" or "policy" 
}

The following table describes the attributes for networkblock_route.

Fields	Description
`type`	A string that must be `rule`, `static`, or `policy`. All other properties must be specified as documented according to this value.
`name`	Only valid if type is `rule`. A string that specifies the name of the rule to use. Currently only `SameNICReply` is accepted. This rule results in a source-based routing rule created on the instance, designed to route reply packets back through the same network interface on which the packets to the vNet IP were received.
`ip_network`	Only valid if the type is `static` or `policy`. A string that specifies the destination IP address range in the CIDR format.
`via`	Only valid if type is `static` or `policy`. A string that specifies the gateway IP address.