About Orchestrations v1

What Is an Orchestration?

An orchestration defines the attributes and interdependencies of a collection of compute, networking, and storage resources in Oracle Compute Cloud Service. You can use orchestrations to automate the provisioning and lifecycle operations of an entire virtual compute topology.

For example, you can use orchestrations to create and manage a collection of instances hosting a multitiered application stack with all the necessary networking, storage, and security settings.

A newer version of orchestrations, Orchestrations v2, offers a similar method of creating and managing resources. To understand the differences between the two versions and for an overview of the benefits of Orchestrations v2, see Comparing Orchestrations v1 and Orchestrations v2.

At any time, you can delete and re-create all the instances in an orchestration just by stopping and restarting the orchestration. Storage attachments, security lists, and so on are re-associated automatically. When the HA policy in an orchestration is set to active, if an instance in such an orchestration goes down, the instance is re-created automatically.

Note that networking and storage objects needn’t be defined in the same orchestrations that you use to create instances. You can define the networking and storage objects in separate orchestrations, and then refer to them in the orchestrations that define the instances. With this approach, you can remove and re-create instances independent of the associated resources.

To create instances using orchestrations, you build an orchestration in a JSON-formatted file, upload it to Oracle Compute Cloud Service, and then start the orchestration. For a simple example of an orchestration file that you can use to learn how to build your first orchestration, see Building Your First Orchestration v1. But before that, do read the remainder of this topic and become familiar with the features, terminology, and concepts of orchestrations.

Orchestration Terminology

Term Description
object plan (oplan)

An object plan, or oplan, is the primary building block of an orchestration.

Each oplan contains all the attributes for the object type defined in that oplan.

An orchestration can contain up to 10 object plans, and each oplan can include up to 10 objects.

object type (obj_type)

An object type refers to the Oracle Compute Cloud Service resource that you want to create.

For example, if you want to create a storage volume, the obj_type would be storage/volume. If you want to create an instance, the obj_type would be launchplan.

See Object Types in an Orchestration.

object (objects)

The objects attribute defines the properties or characteristics of the the Oracle Compute Cloud Service resource that you want to create, as specified by the obj_type attribute.

The fields in the objects section vary depending on the specified obj_type.

For example, if you want to create a storage volume, the obj_type would be storage/volume, and the objects would include size and bootable. If you want to create an instance, the obj_type would be launchplan, and the objects would include instances, along with instance-specific attributes, such as imagelist and shape.

For information about the attributes of each object type, see Attributes in Orchestrations v1.

Object Types in an Orchestration

In an orchestration, you can define any of the following object types:

Object Type Description

integrations/osscontainer

Creates a container in the specified Oracle Storage Cloud Service account.

ip/reservation

Reserves an IP address.

To associate an IP reservation with an instance that’s defined in the same orchestration, you must specify a relationship between the ip/reservation and the launchplan object plans.

launchplan

Creates an instance.

To add an instance to a security list that’s defined in the same orchestration, you must specify a relationship between the launchplan and the seclist object plans.

network/v1/acl

Creates an access control list (ACL) that can be applied to interfaces that are part of your IP networks.

network/v1/ipaddressprefixset

Creates an IP address prefix set. This can be used as a source or destination in security rules that determine access to or from the virtual interfaces of instances that are attached to IP networks.

network/v1/ipassociation

Associates a public IP address reservation with an interface on an instance that is attached to an IP network.

network/v1/ipnetwork

Creates an IP network. You can specify an IP network in the networking attributes while creating an instance.

network/v1/ipnetworkexchange

Creates an IP network exchange. You can add IP networks to an IP network exchange either while creating the IP network, or later, by updating the IP network.

network/v1/ipreservation

Reserves a public IP address from a specified IP pool. This IP address can be associated with the virtual interface of an instance that is attached to an IP network.

network/v1/route

Creates a route to a specified destination using the specified vNICset.

network/v1/secprotocol

Specifies a permitted transport protocol and ports. Security protocols are used in security rules which determine the permitted flow of traffic across your IP networks.

network/v1/secrule

Creates a security rule which can be added to an ACL. Security rules are applied through an ACL to control the permitted flow of traffic across your IP networks.

network/v1/vnicset

Creates a vNICset of one or more virtual network interfaces (vNICs). A vNICset is used to specify the next hop in a route. While creating an instance, you can specify if you want a vNIC to be added to either the shared network or an IP network.

orchestration

Starts a set of orchestrations. See About Nested Orchestrations.

secapplication

Creates a security application.

To use this security application in a security rule that’s defined in the same orchestration, you must specify a relationship between these objects.

seciplist

Creates a security IP list.

To use this security IP list in a security rule that’s defined in the same orchestration, you must specify a relationship between these objects.

seclist

Creates a security list.

To use this security list in a security rule that’s defined in the same orchestration, you must specify a relationship between these objects.

secrule

Creates a security rule.

If this security rule uses security applications, security lists, or security IP lists that are defined in the same orchestration, then you must specify a relationship between these objects.

storage/volume

Creates a storage volume.

To attach this storage volume to an instance that’s defined in the same orchestration, you must specify a relationship between the storage/volume and the launchplan object plans.

An orchestration can contain up to 10 object plans, and each oplan can contain up to 10 objects.

An orchestration can also contain up to three levels of nested orchestrations. So you can use a single orchestration to manage many individual components. See About Nested Orchestrations.

Relationships Between Object Plans

You can use the relationships attribute in an orchestration to specify the sequence in which the objects in the orchestration must be created.

The relationships attribute specifies the two objects that have a relationship, identified by their oplan labels. It also specifies the relationship type, which is set to depends.

For example, if you define a storage volume in an orchestration and you also define an instance that the storage volume is attached to, then in the relationships section of the orchestration, you can specify that the launchplan object plan depends on the storage/volume object plan. This ensures that the storage volume is created before the instance is created.

So if you define a storage volume in an orchestration with the oplan label storagevolume1, and a launch plan with the oplan label boot-from-storagevolume1, then define the relationship between these objects as follows:

 "relationships": [
        {
            "oplan": "boot-from-storagevolume1",
            "to_oplan": "storagevolume1",
            "type": "depends"
        }
    ]

For more complex scenarios, you can define multiple relationships.

For example, to create a security list (seclist1), a security application (secapplication1), and a security rule (secrule1) in a single orchestration, define the following relationships to ensure that both the security application and the security list are created before the security rule:

"relationships": [
        {
            "oplan": "secrule1",
            "to_oplan": "seclist1",
            "type": "depends"
        },
        {
            "oplan": "secrule1",
            "to_oplan": "secapplication1",
            "type": "depends"
        }
    ]

Relationships Between Objects Within a Launch Plan Object

You can also specify relationships within launchplan objects (that is, instances).

For example, if you define two instances with the labels instanceA and instanceB in an orchestration and you want those instances to be created on separate nodes, then in the launchplan object plan, define the relationship between the instances as follows:

"relationships": [
                        {
                            "instances": [
                                "instanceA",
                                "instanceB"
                            ],
                            "type": "different_node"
                        }
                    ]

The type attribute under relationships in a launch plan can have one of the following values:

  • same_node: The specified instances are created on the same physical server. This is useful if you want to ensure low latency across instances.

  • different_node: The specified instances aren’t created on the same physical server. This is useful if you want to isolate instances for security or redundancy.

About Nested Orchestrations

You can specify orchestration as an object type within an orchestration. You can use such an orchestration to start and stop multiple other orchestrations.

For example, if you’ve defined the following orchestrations:

  • /Compute-acme/joe.jonathan@example.com/instances_orch: An orchestration that defines multiple instances.

  • /Compute-acme/joe.jonathan@example.com/networking_orch: An orchestration that defines networking objects such as security lists and security rules.

  • /Compute-acme/joe.jonathan@example.com/storage_orch: An orchestration that defines storage volumes.

You can synchronize the management of all the resources defined in these orchestrations, through the following master orchestration:

{
   "name": "/Compute-acme/joe.jonathan@example.com/master_orch",
   "oplans": [
          {
          "label" : "master-orchestration",
          "obj_type" : "orchestration",
          "objects": [
          {
              "name": "/Compute-acme/joe.jonathan@example.com/instances_orch"
          },
          {
              "name": "/Compute-acme/joe.jonathan@example.com/networking_orch"
          },
          {
              "name": "/Compute-acme/joe.jonathan@example.com/storage_orch"
          }
           
        ]
        }
   ]
}

When you start the master orchestration, all of the nested orchestrations are started. Note that when you add a master orchestration to Oracle Compute Cloud Service, the nested orchestrations are not added automatically. You must add each of the nested and master orchestrations separately.

Depending on the nature of the orchestrations, you might also need to define relationships between the different orchestration object plans in the master orchestration, to ensure that the objects defined in the various orchestrations are created in the appropriate sequence.

For example, to ensure that your network and storage resources are created before the orchestration that defines the instances is started, you can create a master orchestration with relationships defined as follows:

{
    "name": "/Compute-acme/joe.jonathan@example.com/master_orch",
    "oplans": [
        {
            "label": "instances-orchestration",
            "obj_type": "orchestration",
            "objects": [
                {
                    "name": "/Compute-acme/joe.jonathan@example.com/instances_orch"
                }
            ]
        },
        {
            "label": "network-orchestration",
            "obj_type": "orchestration",
            "objects": [
                {
                    "name": "/Compute-acme/joe.jonathan@example.com/networking_orch"
                }
            ]
        },
        {
            "label": "storage-orchestration",
            "obj_type": "orchestration",
            "objects": [
                {
                    "name": "/Compute-acme/joe.jonathan@example.com/storage_orch"
                }
            ]
        }
    ],
        "relationships": [
        {
            "oplan": "instances-orchestration",
            "to_oplan": "network-orchestration",
            "type": "depends"
        },
        {
            "oplan": "instances-orchestration",
            "to_oplan": "storage-orchestration",
            "type": "depends"
        }
    ]

}

You can stop and restart each nested orchestration individually as required. When you stop the master orchestration, all the nested orchestrations are stopped, and the objects created by those orchestrations are deleted.

If you delete the master orchestration, the nested orchestrations aren’t automatically deleted. However, if you use the web console to delete a master orchestration, you can select the option to delete all nested orchestrations as well. See Deleting an Orchestration v1.

An orchestration can contain up to three levels of nested objects.

About High-Availability Policies in an Orchestration

You can specify a high availability (HA) policy in the ha_policy attribute of an orchestration, to specify the behavior when an object stops unexpectedly.

You can specify one of following HA policies:

  • active

    You can specify this policy only for instances, that is, only for objects of type launchplan.

    When the HA policy for an instance is set to active, if the instance stops unexpectedly, it is re-created automatically. Note, however, that the instance is re-created automatically only if the orchestration was in the Ready state and the instance was running without an error. If an instance is in an error state, it isn’t re-created automatically.

  • monitor

    You can specify this policy only for instances, storage volumes, and orchestrations, that is, for objects of type launchplan, storage/volume, and orchestration.

    When the HA policy for an object is set to monitor, if the object goes to an error state or stops unexpectedly, the orchestration changes to the Error state. However, the object isn’t re-created automatically.

You can’t specify an HA policy for any objects other than instances, storage volumes, and orchestrations. Attempting to do so results in an error. Also, if you don’t specify an HA policy for instances, storage volumes, or orchestrations explicitly, then no HA policy is applied. That is, the policy is set to none by default.

Note:

You should always use your orchestrations to manage resources that you’ve created using orchestrations. Don’t, for example, use the web console or the REST API to delete an object that you created using an orchestration. This could cause your orchestration to either attempt to re-create the object and associated resources, or to go into an error state.