6 Managing Resources Using Orchestrations v1
Topics
About Orchestrations v1
Topics
What Is an Orchestration?
An orchestration defines the attributes and interdependencies of a collection of compute, networking, and storage resources in Compute Classic. 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 terminating 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 Compute Classic, 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 Each An orchestration can contain up to 10 object plans, and each |
object type (obj_type)
|
An object type refers to the Compute Classic resource that you want to create. For example, if you want to create a storage volume, the |
object (objects)
|
The The fields in the For example, if you want to create a storage volume, the |
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 |
|---|---|
|
|
Creates a container in the specified Oracle Cloud Infrastructure Object Storage Classic account. |
|
|
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 |
|
|
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 |
|
|
Creates an access control list (ACL) that can be applied to interfaces that are part of your IP networks. |
|
|
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. |
|
|
Associates a public IP address reservation with an interface on an instance that is attached to an IP network. |
|
|
Creates an IP network. You can specify an IP network in the networking attributes while creating an instance. |
|
|
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. |
|
|
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. |
|
|
Creates a route to a specified destination using the specified vNICset. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
Starts a set of orchestrations. See About Nested Orchestrations. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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 |
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 terminate 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 Compute Classic, 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 terminate and restart each nested orchestration individually as required. When you terminate 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:
-
activeYou 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 theReadystate and the instance was running without an error. If an instance is in an error state, it isn’t re-created automatically. -
monitorYou can specify this policy only for instances, storage volumes, and orchestrations, that is, for objects of type
launchplan,storage/volume, andorchestration.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 theErrorstate. 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 CLI or 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.
Orchestrations v1 Templates
The following sample JSON file illustrates the high-level structure of an orchestration. For templates for individual object types, see Orchestration Templates for Each Object Type.
The orchestration templates provided here might not illustrate the use of all the attributes of each object. For a complete list of attributes and their description, see Attributes in Orchestrations v1. To get started with building an orchestration, see Building Your First Orchestration v1.
{
"description": "someDescriptionHere",
"name": "/Compute-identity_domain/user/name",
"relationships: [see Relationships Between Object Plans],
"oplans": [
{
"label": "someText",
"obj_type": "objectType", (see Object Types in an Orchestration)
"ha_policy: "policy", (see About High-Availability Policies in an Orchestration)
"objects": [
{
attributes (see Attributes in Orchestrations v1)
}
]
},
{
"label": "someText",
"obj_type": "objectType", (see Object Types in an Orchestration)
"objects": [
{
attributes (see Attributes in Orchestrations v1)
}
]
},
.
. up to 10 oplans
.
]
}
Template for Top-Level Attributes of an Orchestration
Top-level attributes contain the name and description of an orchestration, along with other information such as the relationship between objects defined in the orchestration, start and stop times for the orchestration, and the list of objects in the orchestration.
{
"name": "/Compute-acme/joe.jonathan@example.com/myOrchestration",
"description": "sample orchestration",
"relationships": [],
"schedule": {"start_time": "2015-06-21T12:00:00Z"},
"oplans": [
{
<Define your oplans here. See Orchestration Template for oplans.>
}
]
}
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 object for each object type.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "My orchestration",
"obj_type": "orchestration",
"objects": [
<Define your objects here. See Orchestration Templates for Each Object Type.>
]
}
]
}
Orchestration Templates for Each Object Type
- Orchestration Template for integrations/osscontainer
- Orchestration Template for ip/reservation
- Orchestration Template for launchplan
- Orchestration Template for network/v1/acl
- Orchestration Template for network/v1/ipaddressprefixset
- Orchestration Template for network/v1/ipassociation
- Orchestration Template for network/v1/ipnetwork
- Orchestration Template for network/v1/ipnetworkexchange
- Orchestration Template for network/v1/ipreservation
- Orchestration Template for network/v1/route
- Orchestration Template for network/v1/secprotocol
- Orchestration Template for network/v1/secrule
- Orchestration Template for network/v1/vnicset
- Orchestration Template for orchestration
- Orchestration Template for secapplication
- Orchestration Template for seciplist
- Orchestration Template for seclist
- Orchestration Template for secrule
- Orchestration Template for storage/volume
Orchestration Template for integrations/osscontainer
Use this object type if you want to create a container in your associated Oracle Cloud Infrastructure Object Storage Classic account.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "My-OSS-Container",
"obj_type": "integrations/osscontainer",
"objects": [
{
"account": "/Compute-acme/cloud_storage",
"container": "Container_1",
"delete_remote": false
}
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for ip/reservation
Use this object type if you want to reserve permanent IP addresses in the shared network to attach with your instances. For more information, see About Public IP Addresses.
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.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "My IP reservations",
"obj_type": "ip/reservation",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/ipres1",
"parentpool": "/oracle/public/ippool",
"permanent": true
},
{
"name": "/Compute-acme/joe.jonathan@example.com/ipres2",
"parentpool": "/oracle/public/ippool",
"permanent": true
}
<Define other IP reservations here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for launchplan
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.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "My instances",
"obj_type": "launchplan",
"objects": [
{
"instances": [
{
<Define your instance here. See Orchestration Template for Instances.>
}
<Define other instances here.>
]
}
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for Instances
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 such object and the instance launch plan. For more information, see Relationships Between Object Plans.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "My instances",
"obj_type": "launchplan",
"objects": [
{
"instances": [
{
"shape": "oc3",
"boot_order": [1],
"label": "vm-1",
"networking": {
"eth0": {
"seclists": ["/Compute-acme/joe.jonathan@example.com/wlsadmin_seclist"],
"nat": "ipreservation:/Compute-acme/joe.jonathan@example.com/ipres1"
},
"eth1" : {
"ipnetwork" : "/Compute-acme/joe.jonathan@example.com/ipnet-1",
"ip": "192.168.4.2",
"vnic": "/Compute-acme/joe.jonathan@example.com/eth1-ipnet1"
}
},
"sshkeys": ["/Compute-acme/joe.jonathan@example.com/key1"],
"storage_attachments": [
{
"index": 1,
"volume": "/Compute-acme/joe.jonathan@example.com/boot"
}
]
}
<Define other instances here.>
]
}
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for network/v1/acl
Use this object type if you want to create an access control list (ACL). For more information about using ACLs in IP networks, see Configuring IP Networks.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "ACL1-for-vnicset1",
"obj_type": "network/v1/acl",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/acl_1",
"enabledFlag": true
}
<Define other ACLs here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for network/v1/ipaddressprefixset
Use this object type if you want to create IP address prefix set to use as a source or destination in a security rule. For more information about using IP address prefix sets in IP networks, see Configuring IP Networks.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "IPaddress-prefix-set-1",
"obj_type": "network/v1/ipaddressprefixset",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/ext_ip_addresses",
"ipAddressPrefixes": ["203.0.113.0/30", "192.51.100.1/24"]
}
<Define other IP address prefix sets here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for network/v1/ipassociation
Use this object type if you want to create an IP association between an IP reservation and a vNIC in an IP network. For more information about IP associations in IP networks, see Configuring IP Networks.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "IP-Association-for-vnic1-on-instance1",
"obj_type": "network/v1/ipassociation",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/IP-association-vnic1",
"ipAddressReservation": "/Compute-acme/joe.jonathan@example.com/IPres-for-instance1-vnic1",
"vnic": "/Compute-acme/joe.jonathan@example.com/instance1-vnic1"
}
<Define other IP associations here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for network/v1/ipnetwork
Use this object type if you want to create IP networks. For more information about setting up and using IP networks, see Configuring IP Networks.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "ipnet1",
"obj_type": "network/v1/ipnetwork",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/ipnet1",
"ipAddressPrefix": "192.168.3.0/24",
"ipNetworkExchange": "/Compute-acme/joe.jonathan@example.com/ipnetworkexchange1",
"description": "IP network with IP network exchange"
}
<Define other IP networks here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for network/v1/ipnetworkexchange
Use this object type if you want to create IP network exchanges. For more information about setting up and using IP networks and IP network exchanges, see Configuring IP Networks.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "ipnetworkexchange",
"obj_type": "network/v1/ipnetworkexchange",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/ipnetworkexchange1"
}
<Define other IP network exchanges here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for network/v1/ipreservation
Use this object type if you want to create an IP reservation for IP networks. For more information about IP networks, see Configuring IP Networks.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "IP-Reservation-for-IP-network",
"obj_type": "network/v1/ipreservation",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/IPres-for-instance1-vnic1",
"ipAddressPool": "/oracle/public/public-ippool"
}
<Define other IP reservations for IP networks here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for network/v1/route
Use this object type if you want to create routes to direct traffic across your IP networks. See Configuring IP Networks.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "route",
"obj_type": "network/v1/route",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/route1",
"nextHopVnicSet": "/Compute-acme/joe.jonathan@example.com/vnicset1",
"ipAddressPrefix": "203.0.113.0/24",
"adminDistance": "0"
}
<Define other routes here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for network/v1/secprotocol
Use this object type if you want to create a security protocol for IP networks. For more information about IP networks, see Configuring IP Networks.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "Security-protocol-for-IP-networks",
"obj_type": "network/v1/secprotocol",
"objects": [
{
"description": "Security Protocol 1",
"dstPortSet": ["20", "155-1100"],
"ipProtocol": "tcp",
"name": "/Compute-acme/joe.jonathan@example.com/secprotocol_1",
"srcPortSet": ["10", "55-100"]
}
<Define other security protocols for IP networks here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for network/v1/secrule
Use this object type if you want to create a security rule for IP networks. For more information about IP networks, see Configuring IP Networks.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "IP-network-secrule-1",
"obj_type": "network/v1/secrule",
"objects": [
{
"acl": "/Compute-acme/joe.jonathan@example.com/acl_1",
"description": "Sec Rule 1",
"flowDirection": "egress",
"name": "/Compute-acme/joe.jonathan@example.com/ipnetSecrule1",
"secProtocols": ["/Compute-acme/joe.jonathan@example.com/secprotocol_1"],
"srcIpAddressPrefixSets": ["/Compute-acme/joe.jonathan@example.com/ext_ip_address_list_1"]
}
<Define other security rules for IP networks here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for network/v1/vnicset
Use this object type if you want to create vNICsets in IP networks. For information about using vNICsets in IP networks, see Configuring IP Networks.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "vnicset",
"obj_type": "network/v1/vnicset",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/vnicset1",
"vnics": ["/Compute-acme/joe.jonathan@example.com/vnic1",
"/Compute-acme/joe.jonathan@example.com/vnic2"]
}
<Define other vnicsets here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for orchestration
Use this object type if you want to use an orchestration to start or stop multiple nested orchestrations. For more information, see About Nested Orchestrations.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "My orchestration",
"obj_type": "orchestration",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/myInstances"
},
{
"name": "/Compute-acme/joe.jonathan@example.com/myStorageVolumes"
}
<Add names of other nested orchestrations here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for secapplication
Use this object type to define security applications to use in security rules in the shared network. For more information, see About Security Applications.
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.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "My security applications",
"obj_type": "secapplication",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/wlsadmin_ssl",
"dport": 7002,
"protocol": "tcp"
}
<Define other security applications here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for seciplist
Use this object type to define a set of IP addresses that you want to use as a source in a security rule in the shared network. For more information, see About Security IP Lists.
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.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "admin-ip-list",
"obj_type": "seciplist",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/admin_ips",
"secipentries": ["203.0.113.0/30"]
}
<Define other security IP lists here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for seclist
Use this object type to define security lists to group your instances in the shared network. For more information, see About Security Lists.
To use this security list in a security rule that’s defined in the same orchestration, you must specify a relationship between these objects.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "admin-seclists",
"obj_type": "seclist",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/sysadmin_seclist"
},
{
"name": "/Compute-acme/joe.jonathan@example.com/wlsadmin_seclist"
}
<Define other security lists here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for secrule
Use this object type to define security rules that control access to your instances in the shared network. For more information, see About Security Rules.
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.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "My security rules",
"obj_type": "secrule",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/admin_ssh_to_sysadmin_rule",
"application": "/oracle/public/ssh",
"src_list": "seciplist:/Compute-acme/joe.jonathan@example.com/admin_ips",
"dst_list": "seclist:/Compute-acme/joe.jonathan@example.com/sysadmin_seclist",
"action": "PERMIT"
},
{
"name": "/Compute-acme/joe.jonathan@example.com/dbadmin_ssh_to_db_rule",
"application": "/oracle/public/ssh",
"src_list": "seclist:/Compute-acme/joe.jonathan@example.com/dbadmin_seclist",
"dst_list": "seclist:/Compute-acme/joe.jonathan@example.com/db_seclist",
"action": "PERMIT"
}
<Define other security rules here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Orchestration Template for storage/volume
Use this object type to create storage volumes that you want to attach to your instances. For more information, see About Storage Volumes.
Note:
Don’t define storage volumes and instances in the same orchestration. By keeping storage volumes and instances in separate orchestrations, you can shut down and start the instances when required and yet preserve the attached storage volumes. Note that the recommendation here is to define the storage volumes outside the instance orchestration. To ensure that the storage volumes remain attached after an instance is re-created, you must define the storage attachments within the instance orchestration.
{
<Define the top-level attributes of your orchestration here. See Template for Top-Level Attributes of an Orchestration.>
"oplans": [
{
"label": "My storage volumes",
"obj_type": "storage/volume",
"objects": [
{
"name": "/Compute-acme/joe.jonathan@example.com/boot",
"bootable": true,
"imagelist": "/oracle/public/OL_6.7_UEKR4_x86_64",
"properties": ["/oracle/public/storage/default"],
"size": "22548578304"
},
{
"name": "/Compute-acme/joe.jonathan@example.com/data",
"properties": ["/oracle/public/storage/latency"],
"size": "32212254720"
}
<Define other storage volumes here.>
]
}
<Define other objects here. See Orchestration Templates for Each Object Type.>
]
<Define other oplans here. See Orchestration Template for oplans.>
}
Workflow for Creating Instances Using Orchestrations v1
An orchestration defines the attributes and interdependencies of a collection of compute, networking, and storage resources in Compute Classic. You can use orchestrations to automate the provisioning and lifecycle operations of an entire virtual compute topology.
Building Your First Orchestration v1
Topics
Before You Begin
Before building your orchestration JSON file, do the following:
-
Create the security, storage, and networking resources that you plan to reference in your orchestration.
These tasks require the
Compute_Operationsrole. If this role isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.-
If you want to create a Linux instance with SSH access enabled, upload your SSH public keys to Compute Classic. See Adding an SSH Public Key.
Note:
You don’t need to do this if you’re creating a Windows instance, because you can’t log in to a Windows instance using SSH.
-
If you want your instances to boot from a persistent storage disk, create bootable storage volumes. See Creating a Bootable Storage Volume.
-
Create storage volumes for the data and applications that you plan to deploy on your instances. See Creating a Storage Volume. When you create the storage volumes, don’t attach them to any existing instance. You’ll specify the storage volumes later in the orchestration.
-
If you want your instances to have fixed public IP addresses, then create the required IP reservation. See Reserving a Public IP Address.
-
Create the required security lists. See Creating a Security List.
-
Sample Orchestration for Creating a Single Instance
You can use the following sample orchestration as a starting point for building your first orchestration.
{
"description": "Simple oplan with an ssh key and a security list",
"name": "/Compute-acme/joe.jonathan@example.com/simple_orchestration",
"oplans": [
{
"label": "simple_oplan",
"obj_type": "launchplan",
"objects": [
{
"instances": [
{
"imagelist": "/oracle/public/OL_6.7_UEKR4_x86_64",
"label": "OL_6.7",
"networking": {
"eth0": {
"seclists": [
"/Compute-acme/joe.jonathan@example.com/my_instances"
],
"nat": "ipreservation:/Compute-acme/joe.jonathan@example.com/ip1"
}
},
"shape": "oc3",
"storage_attachments": [
{
"index": 1,
"volume": "/Compute-acme/joe.jonathan@example.com/OL66_boot"
},
{
"index": 2,
"volume": "/Compute-acme/joe.jonathan@example.com/data1"
}
],
"boot_order": [1],
"sshkeys": [
"/Compute-acme/joe.jonathan@example.com/ssh-key1"
]
}
]
}
]
}
]
}-
Defines an instance with the label
OL_6.7, theoc3shape, and using the/oracle/public/OL_6.7_UEKR4_x86_64image. -
Adds the instance to the security list
/Compute-acme/joe.jonathan@example.com/my_instances. -
Associates the IP reservation
/Compute-acme/joe.jonathan@example.com/ip1with the instance. -
Attaches the bootable storage volume
/Compute-acme/joe.jonathan@example.com/OL66_bootto the instance. -
Attaches the data storage volume
/Compute-acme/joe.jonathan@example.com/data1to the instance. -
Associates the SSH public key
/Compute-acme/joe.jonathan@example.com/ssh-key1with the instance.
Note:
To learn about the structure of an orchestration, see Orchestrations v1 Templates. For information about all the attributes that you can define in an orchestration, see Attributes in Orchestrations v1.
Steps for Building Your First Orchestration
Your orchestration file is now ready.
To create instances by using this orchestration, you must upload it to Compute Classic. See Uploading an Orchestration v1.
Attributes in Orchestrations v1
You specify attributes in orchestrations at several levels. At the highest level, you specify certain attributes for the orchestration as a whole. Then, you specify attributes for each object plan defined in the orchestration. Finally, there are attributes that are specific to each object type.
-
Top-level attributes
Top-level attributes contain the name and description of an orchestration, along with other information such as the relationship between objects defined in the orchestration, start and stop times for the orchestration, and the list of objects in the orchestration. See Top-Level Attributes in Orchestrations v1. For a template of top-level orchestration attributes, see Template for Top-Level Attributes of an Orchestration.
-
Object plan attributes
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 object for each object type. Object plan attributes define the characteristics of each oplan, including its label, object type and list of objects, and the HA policy, if applicable. See Object Plan Attributes. For an oplan template, see Orchestration Template for oplans. -
Attributes specific to each object type
These are the characteristics specific to each object type. See Orchestration v1 Attributes Specific to Each Object Type. The attributes that you can specify for each object type in an orchestration are the same as the parameters that you can specify with the
POSTmethod for that resource using the API.
For orchestration templates that you can use to create individual objects, see Orchestration Templates for Each Object Type.
Top-Level Attributes in Orchestrations v1
Top-level attributes contain the name and description of an orchestration, along with other information such as the relationship between objects defined in the orchestration, start and stop times for the orchestration, and the list of objects in the orchestration.
Attributes for objects defined in an orchestration vary according to the object type. For a list of objects and object-specific attributes in orchestrations v1, see Orchestration v1 Attributes Specific to Each Object Type.
The following sample JSON shows the required top-level orchestration attributes, name and oplans. A description of each of the required and optional top-level attributes is provided in the table below.
{
"name": "/Compute-acme/joe/myOrchestration",
"oplans": [
{
...
}
]
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the orchestration ( |
|
|
required |
The list of object plans ( An |
|
|
optional |
Text string describing the orchestration. |
|
|
optional |
The relationship between the objects that are created by this orchestration. The only supported relationship type for orchestrations is |
|
|
optional |
The start and stop dates and times, in ISO 8601 format. You must specify the time zone as UTC.
|
Object Plan Attributes
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 object for each object type. You must provide a label for each oplan. You can also specify a High Availability policy, if applicable.
The following sample JSON shows the required attributes of an object plan. A description of each of the required and optional attributes is provided in the table below.
{
"name": "/Compute-amce/joe/myOrchestration",
"oplans": [
{
"label": "My orchestration",
"obj_type": "orchestration",
"objects": [
...
]
}
]
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
Text string describing the object plan. Maximum length: 256 characters. |
|
|
required |
The type of object that you want to create. Specify one of the following object types.
For a brief description of each object type, see Object Types in an Orchestration. Each object type has a specific set of attributes. See Orchestration v1 Attributes Specific to Each Object Type. |
|
|
required |
The list of objects, depending on the type of object that you’re creating, as defined in the See Orchestration v1 Attributes Specific to Each Object Type |
|
|
optional |
The high availability policy: You can specify either |
Orchestration v1 Attributes Specific to Each Object Type
You can specify various object types in an orchestration, including launch plans, networking objects such as security lists and security rules, storage volumes, and even other orchestrations. The attributes for each object vary depending on the object type.
The following sections describe the attributes for each object type that you can create using an orchestration. Each set of attributes corresponds to an object under the specified obj_type in the orchestration file.
- Orchestration v1 Attributes for integrations/osscontainer
- Orchestration v1 Attributes for ip/reservation
- Orchestration v1 Attributes for launchplan
- Orchestration v1 Attributes for instances
- Orchestration v1 Attributes for network/v1/acl
- Orchestration v1 Attributes for network/v1/ipaddressprefixset
- Orchestration v1 Attributes for network/v1/ipassociation
- Orchestration v1 Attributes for network/v1/ipnetwork
- Orchestration v1 Attributes for network/v1/ipnetworkexchange
- Orchestration v1 Attributes for network/v1/ipreservation
- Orchestration v1 Attributes for network/v1/route
- Orchestration v1 Attributes for network/v1/secprotocol
- Orchestration v1 Attributes for network/v1/secrule
- Orchestration v1 Attributes for network/v1/vnicset
- Orchestration v1 Attributes for orchestration
- Orchestration v1 Attributes for secapplication
- Orchestration v1 Attributes for seciplist
- Orchestration v1 Attributes for seclist
- Orchestration v1 Attributes for secrule
- Orchestration v1 Attributes for storage/volume
All objects in an orchestration are contained within an object plan. For information about object plan attributes, see Object Plan Attributes. For information about defining the name and other characteristics of an orchestration, see Top-Level Attributes in Orchestrations v1.
Orchestration v1 Attributes for integrations/osscontainer
The following sample JSON shows the key attributes of the integrations/osscontainer object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"account": "/Compute-acme/cloud_storage",
"container": "Container_1",
"delete_remote": false
}
| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The two-part name of the account ( |
|
|
required |
The name of the container that you want to create. Container names must:
Ensure that a container of the same name doesn’t already exist. |
|
|
required |
When set to When set to |
|
|
optional |
The three-part name of the If you don’t specify a name for this object, then the name is generated automatically. Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
Orchestration v1 Attributes for ip/reservation
The following sample JSON shows the key attributes of the ip/reservation object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/ipres1",
"parentpool": "/oracle/public/ippool",
"permanent": true
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
Specify |
|
|
required |
Set to |
|
|
optional |
Specify |
|
|
optional |
The three-part name of the object ( If you don’t specify a name for this object, then the name is generated automatically. Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
Orchestration v1 Attributes for launchplan
Launch plan objects are used to define instances. The following sample JSON shows the required attributes of the launchplan object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"instances":
[
{
...
}
]
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
A list of instances. For instance attributes, see Orchestration v1 Attributes for instances. |
|
|
optional |
The relationships between instances. Valid values:
|
After defining a launchplan object, to define an instance, see Orchestration v1 Attributes for instances.
Orchestration v1 Attributes for instances
Note:
An instance is not in itself an object type. It is an attribute of the launchplan object type.
Topics:
Instance Attributes
Instances are an attribute of the launchplan object type. Instances have a number of required and optional attributes. The following sample JSON shows some of the key instance attributes. A description of each of the required and optional instance attributes is provided in the table below.
{
"instances": [
{
"shape": "oc3",
"boot_order": [
1
],
"label": "vm-1",
"networking": {
"eth0": {
"seclists": [
"/Compute-acme/joe/wlsadmin_seclist"
],
"nat": "ipreservation:/Compute-acme/joe/ipres1"
},
"eth1": {
"ipnetwork": "/Compute-acme/joe/ipnet1",
"ip": "192.168.4.2",
"vnic": "/Compute-acme/joe/eth1-ipnet1"
}
},
"sshkeys": [
"/Compute-acme/joe/key1"
],
"storage_attachments": [
{
"index": 1,
"volume": "/Compute-acme/joe/boot"
}
]
}
]
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The name of the shape that defines the number of OCPUs and the RAM that you require for the instance. For general purpose and high-memory shapes, you can select the block storage disk size, but for high I/O shapes, the size of the SSD storage is determined by the shape. |
|
|
optional |
The three-part name of the instance ( If you specify this parameter, then the full name of the instance would be in the format, If you don’t specify this parameter, then the full name would be in the format, In either case, id is an autogenerated ID. Examples of Instance Names:
Although this is an optional parameter, specifying a meaningful name makes it easier for you to identify your instances. |
|
|
optional |
A text string to identify the instance. This label is used when defining relationships in an orchestration. A label can contain only alphanumeric characters, hyphens, and underscores. It can’t contain unicode characters and spaces. Maximum length is 256 characters. |
|
|
optional |
A JSON array or list of strings used to tag the instance. By assigning a human-friendly tag to an instance, you can identify the instance easily when you perform an instance listing. These tags aren’t available from within the instance. |
|
|
optional |
A JSON object or dictionary of user-defined attributes to be made available to the instance. If you’re creating a Windows instance, you must specify the following required attributes:
For more information about specifying user-defined attributes that can be used to automate instance configuration, see Automating Instance Initialization Using opc-init. Note: Solaris machine images don’t include the opc-init scripts. So you can’t use opc-init to automate instance configuration of Solaris instances. The attributes that you specify can be accessed from within the instance at |
|
|
optional |
The three-part name ( You must use this attribute if you don’t specify a bootable storage volume by using the |
|
|
optional |
If you specify the
|
|
|
optional |
The index number of the bootable storage volume that should be used to boot the instance. The only valid value is If you set this attribute, you must also specify a bootable storage volume with index number When you specify |
|
|
optional |
The host name assigned to the instance. On an Oracle Linux instance, this host name is displayed in response to the Only relative DNS is supported. The domain name is suffixed to the host name that you specify. The host name must not end with a period. If you don’t specify a host name, then a name is generated automatically. The DNS name of an instance depends on its host name, as follows:
Note: If an instance has network interfaces defined only for IP networks and doesn’t have any interface on the shared network, then when |
|
|
optional |
If set to If set to |
|
|
optional |
Note: For each interface, you can specify parameters for either the shared network, or for an IP network. You can’t specify parameters for both networks for the same Only one interface on an instance can be added to the shared network. To add an interface to the shared network, you can specify the following subparameters:
For more information about each of these subparameters, see Subparameters for a Network Interface on the Shared Network. |
|
|
optional |
Note: For each interface, you can specify parameters for either the shared network, or for an IP network. You can’t specify parameters for both networks for the same To add this instance to an IP network, specify the following subparameters:
For more information about each of these subparameters, see Subparameters for a Network Interface on an IP Network. |
|
|
optional |
A list of the SSH public keys that you want to associate with the instance. Note: You don’t need to provide any SSH public keys if you’re creating a Windows instance, because you can’t access a Windows instance using SSH. To access a Windows instance, see Accessing a Windows Instance Using RDP. For each key, specify the three-part name in the You can associate the same key with multiple instances. The keys that you specify are stored as metadata on the instance. This metadata can be accessed from within the instance at
http://192.0.0.192/{version}/meta-data/public-keys/{index}/openssh-key.
|
Networking Attributes for Instances
There are several subparameters that you can specify under the ethn parameter in the networking section of instance attributes. The list of subparameters varies depending on whether you’re defining a network interface on a shared network or an IP network.
Only one interface can be added to the shared network. If no subparameters are specified for the ethn parameter, the interface is implicitly added to the default security list in the shared network. You can’t explicitly or implicitly define two interfaces to be added to the shared network.
Subparameters for a Network Interface on the Shared Network
-
seclists:(Optional) The security lists that you want to add the instance to.For each security list, specify the three-part name in the
/Compute-identity_domain/user/object_nameformat. You can attach an instance to a maximum of five security lists. If you launch an instance without specifying any security list, the instance is assigned to the/Compute-identity_domain/default/defaultsecurity list. -
nat:(Optional) Indicates whether a temporary or permanent public IP address should be assigned to the instance.-
To associate a temporary IP address with the instance for use during the lifetime of the instance, specify
ippool:/oracle/public/ippool. -
To associate a persistent IP address, specify
ipreservation:ipreservation_name, whereipreservation_nameis the three-part name of an existing IP reservation in the/Compute-identity_domain/user/object_nameformat.
If
natis not specified, then no public IP address is associated with your instance when it is created. If required, you can associate an IP address with the instance after the instance has been created. -
-
dns:(Optional) A list of the DNS A record names for the instance. The name is relative to the internal DNS domain. -
model:(Optional) The type of network interface card (NIC). The only allowed value ise1000. -
name_servers:(Optional) Enter the name servers that are sent through DHCP as option 6. You can specify a maximum of eight name server IP addresses per interface. Ifname_serversare set in both the IP network settings as well as the shared network settings, the name servers in the shared network will be used. To ensure that the name servers specified in the IP network are used, specify the same values for name servers on each interface. -
search_domains:(Optional) Enter the search domains that should be sent through DHCP as option 119. You can enter a maximum of eight search domain zones per interface. Ifsearch_domainsare set in both the IP network settings as well as the shared network settings, the search domains in the shared network will be used. To ensure that the search domains specified in the IP network are used, specify the same values for search domains on each interface.
Subparameters for a Network Interface on an IP Network
-
ipnetwork:The name of the IP network that you want to add the instance to.If no name is specified, the interface isn’t added to any IP network. Instead, it is implicitly added to the shared network. However, only one instance interface can be added to the shared network. If another interface is either implicitly or explicitly added to the shared network, the instance won’t be created and will display an error.
Specify the three-part name of the IP network, in the
/Compute-identity_domain/user/object_nameformat.If an IP network belongs to an IP network exchange and if you have specified a host name, then that host name is resolvable by all IP networks connected to the IP network exchange.
-
ip:(Optional) The static private IP address of the instance. This is a persistent private IP address, which is reserved for use with this instance. The private IP address must be unused and it must belong to the subnet of the selectedIP network. Remember, too, that certain IP addresses in a subnet are reserved. For example, the first unicast IP address of any IP network is reserved for the default gateway, the DHCP server, and the DNS server of that IP network.If you don’t specify an IP address, an IP address is assigned dynamically from the available IP addresses of the specified
ipnetwork. However in this case, if you delete and re-create the instance, its IP address might change.Note:
Dynamically allocated IP addresses are assigned from the top of the subnet range. It is recommended that you specify static IP addresses starting from the end of the subnet range to avoid conflicts.
-
address:(Optional) The MAC address of the interface, in hexadecimal format, where each digit is separated by colon. For example, you can enter01:02:03:04:ab:cdas the MAC address but not01-02-03-04-ab-cd. Ensure that the MAC addresses that you specify are unique within each IP network exchange and each IP network. If you specify a duplicate MAC address, each vNIC with that MAC address is disabled. -
nat:(Optional) A list of IP reservations that you want to associate with this interface. Specifynetwork/v1/ipreservation:ipreservation_name, whereipreservation_nameis the three-part name of an existing IP reservation in the/Compute-identity_domain/user/object_nameformat.When you create an IP reservation, you specify the IP pool from which you want to reserve the IP address. You can associate a maximum of two IP reservations with each vNIC, one from each IP pool.
Example:
"networking": { "eth0": { "ipnetwork": "/test-customer/ipnet-1", "ip": "192.168.2.14", "nat": ["network/v1/ipreservation:/Compute-acme/joe/public-ipres-1"] } } -
vnic:(Optional) The three-part name of the vNIC in the/Compute-identity_domain/user/object_nameformat.If you don’t specify a name for this object, then the name is generated automatically.
When the vNIC name is generated automatically, the autogenerated instance id in included as part of the object_name. So if you delete and re-create an instance, the vNIC name will change. However, if you specify a vNIC name, the name won’t change if you delete and re-create the instance.
Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive.
-
vnicsets:(Optional) A list of the three-part names of the vNICsets that you want to add this vnic to. Specifying vNICsets ensures that this vNIC is added to the required vNICsets whenever the instance is created and removed from the vNICset whenever the instance is deleted.While creating an instance, you can add a vNIC to up to 4 vNICsets. To add a vNIC to more than 4 vNICsets, update the required vNICsets after the instance is created.
The vNICsets that you specify here must already exist when you create or re-create an instance.
If no vNICset is specified, then the vNIC is added to the default vNICset,
/Compute-identity_domain/default.If an empty list (
"vnicsets": []) is specified, this vNIC isn't added to any vNICset, including the default vNICset. -
is_default_gateway:(Optional) If you want to specify the interface to be used as the default gateway for all traffic, set this totrue. The default isfalse. Only one interface on an instance can be specified as the default gateway. If the instance has an interface on the shared network, that interface is always used as the default gateway. You can specify an interface on an IP network as the default gateway only when the instance doesn’t have an interface on the shared network. -
dns:(Optional) A list of the DNS A record names for the instance.Each IP network has its own DNS server listening on the first IP address of the subnet. You can specify up to eight DNS A record names for each instance on an IP network. These names can be queried by instances on any IP network in the same IP network exchange.
If no static IP address is specified for the instance on the IP network, an IP address on the specified IP network is assigned automatically. After the instance is launched, the defined names are associated with the IP address that was automatically allocated to the instance.
The same DNS A record name can be specified for multiple instances.
Example:
"networking": { "eth1": { "ipnetwork": "/Compute-acme/joe/ipnet1", "dns": [ "dns1.example.com", "dns2.bar.com" ] } } -
name_servers:(Optional) A list of the name servers that are sent through DHCP as option 6. You can specify a maximum of eight name server IP addresses per interface. Ifname_serversare set in both the IP network as well as the shared network, the name servers in the shared network will be used. To ensure that the name servers specified in the IP network are used, specify the same values for name servers on each interface.Example:
"networking": { "eth1": { "ipnetwork": "/Compute-acme/joe/ipnet1", "dns": ["dns1.example.com", "dns2.bar.com"], "name_servers": ["192.168.12.1", "192.168.12.2"] } }In this example, the name servers
192.168.12.1and192.168.12.2will be pushed to the instance through DHCP. -
search_domains:(Optional) A list of the search domains that should be sent through DHCP as option 119. You can enter a maximum of eight search domain zones per interface. Ifsearch_domainsare set in both the IP network as well as the shared network, the search domains in the shared network will be used. To ensure that the search domains specified in the IP network are used, specify the same values for search domains on each interface.Example:
"networking": { "eth1": { "ipnetwork": "/Compute-acme/joe/ipnet1", "dns": ["dns1.example.com", "dns2.bar.com"], "name_servers": ["192.168.12.1", "192.168.12.2"], "search_domains": ["example.com", "us.example1.com"] } }In this example, the search domain zones
example.comandus.example1.comwill be pushed to the instance through DHCP.
Orchestration v1 Attributes for network/v1/acl
The following sample JSON shows the key attributes of the network/v1/acl object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/acl_1",
"enabledFlag": true
}
| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
optional |
Allows the ACL to be enabled or disabled. This parameter is set to |
|
|
optional |
Description of the ACL. |
|
|
optional |
Strings that you can use to tag the ACL. |
Orchestration v1 Attributes for network/v1/ipaddressprefixset
The following sample JSON shows the key attributes of the network/v1/ipaddressprefixset object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/ext_ip_address_list_1",
"ipAddressPrefixes": ["203.0.113.0/30", "192.51.100.1/24"]
}
| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
optional |
Set of IPv4 addresses in CIDR address prefix format. |
|
|
optional |
Description of the IP address prefix set. |
|
|
optional |
Strings that you can use to tag the IP address prefix set. |
Orchestration v1 Attributes for network/v1/ipassociation
The following sample JSON shows the key attributes of the network/v1/ipassociation object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/IP-association-vnic1",
"ipAddressReservation": "/Compute-acme/joe/IPres-for-instance1-vnic1",
"vnic": "/Compute-acme/joe/instance1-vnic1"
}
| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
optional |
The name of the IP reservation that you want to associate with an instance. |
|
|
optional |
The name of the vNIC that you want to associate the IP reservation with. |
|
|
optional |
Description of the IP association. |
|
|
optional |
Strings that you can use to tag the IP association. |
Orchestration v1 Attributes for network/v1/ipnetwork
The following sample JSON shows the attributes of the network/v1/ipnetwork object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/ipnet1",
"ipAddressPrefix": "192.168.3.0/24",
"ipNetworkExchange": "/Compute-acme/joe/ipnetworkexchange1"
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
required |
The set of IP addresses allocated to your IP network, specified in the CIDR format. When you create instances, you can associate a vNIC on the instance with an IP network. That vNIC on the instance is then allocated an IP address from the specified IP network. Select the IP address prefix for your IP networks carefully. Consider the number of instances that you might want to add to the network. This will help determine the size of the subnet required. If you create multiple IP networks and you might want to add these IP networks to the same IP network exchange, then ensure that you don’t allocate overlapping address ranges to these IP networks. Similarly, if you plan to connect to your IP networks using VPN, then ensure that the addresses you specify for your IP networks don’t overlap with each other, or with the IP addresses used in your on-premises network. |
|
|
optional |
The IP network exchange that you want to add this IP network to. An IP network can belong to only one IP network exchange. Before you specify an IP network exchange for an IP network, ensure that the IP addresses in this IP network don’t overlap the IP addresses in any other network in the same IP network exchange. Note: You should ensure that the IP network exchange you reference currently exists. If the IP network exchange hasn’t been created or has been deleted, then when you add an instance interface to this IP network while creating the instance, the instance will go into an error state and won’t be created. If you want to connect IP networks by using an IP network exchange, it is recommended that you do this before creating instances with an interface on those IP networks. This ensures that routes are appropriately configured on instances by the DHCP client during instance initialization. |
|
|
optional |
Description of the IP network. |
|
|
optional |
Strings that you can use to tag the IP network. |
Orchestration v1 Attributes for network/v1/ipnetworkexchange
The following sample JSON shows the required attribute of the network/v1/ipnetworkexchange object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/ipnetworkexchange1"
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
optional |
Description of the IP network exchange. |
|
|
optional |
Strings that you can use to tag the IP network exchange. |
Orchestration v1 Attributes for network/v1/ipreservation
The following sample JSON shows the key attributes of the network/v1/ipreservation object type for IP networks. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/IPres-for-instance1-vnic1",
"ipAddressPool": "/oracle/public/public-ippool"
}
| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
required |
The IP address pool from which you want to reserve an IP address. Enter one of the following:
|
|
|
optional |
Description of the IP reservation. |
|
|
optional |
Strings that you can use to tag the IP reservation. |
Orchestration v1 Attributes for network/v1/route
The following sample JSON shows the required attributes of the network/v1/route object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/route1",
"nextHopVnicSet": "/Compute-acme/joe/vnicset1",
"ipAddressPrefix": "192.168.0.0/16"
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
required |
The IP address prefix, in CIDR format, of the destination network that you want to specify the route to. |
|
|
required |
The vNICset that you want to use to route packets to the destination network. When a vNICset containing multiple vNICs is used in a route, Equal Cost Multipath (ECMP) anycast routing is implemented. Traffic routed by that route is load balanced across all the vNICs in the vNICset. Using vNICsets with multiple vNICs also ensures high availability for traffic across the specified vNICs. |
|
|
optional |
The route’s administrative distance. Specify 0 (the default), 1, or 2. The administrative distance indicates the priority of a route. The highest priority is 0. The route with the highest priority is used. If multiple routes have the highest priority, all those routes are used. |
|
|
optional |
Description of the route. |
|
|
optional |
Strings that you can use to tag the route. |
Orchestration v1 Attributes for network/v1/secprotocol
The following sample JSON shows the key attributes of the network/v1/secprotocol object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"description": "Sec Protocol 1",
"dstPortSet": ["20", "155-1100"],
"ipProtocol": "tcp",
"name": "/Compute-acme/joe/secprotocol_1",
"srcPortSet": ["10", "55-100"]
}
| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
optional |
The protocol used in the data portion of the IP datagram. The value that you specify can be either a text representation of a protocol or any unsigned 8-bit assigned protocol number in the range 0–254. See Assigned Internet Protocol Numbers ( The following text representations are allowed:
If no protocol is specified, all protocols are allowed. |
|
|
optional |
List of port numbers or port range strings to match the packet's source port.
If no source ports are specified, all source ports or ICMP types are allowed. |
|
|
optional |
List of port numbers or port range strings to match the packet's destination port. For If no destination ports are specified, all destination ports or ICMP codes are allowed. |
|
|
optional |
Description of the security protocol. |
|
|
optional |
Strings that you can use to tag the security protocol. |
Orchestration v1 Attributes for network/v1/secrule
The following sample JSON shows the key attributes of the network/v1/secrule object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"acl": "/Compute-acme/joe/acl_1",
"description": "Sec Rule 1",
"flowDirection": "egress",
"name": "/Compute-acme/joe/ipnetSecrule1",
"secProtocols": ["/Compute-acme/joe/secprotocol_1"],
"srcIpAddressPrefixSets": ["/Compute-acme/joe/ext_ip_address_list_1"]
}
| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
required |
The direction of flow of traffic that this rule applies to. Allowed values are |
|
|
optional |
The vNICset from which you want to permit traffic. Only packets from vNICs in the specified vNICset are permitted. When no source vNICset is specified, traffic from any vNIC is permitted. |
|
|
optional |
The vNICset to which you want to permit traffic. Only packets to vNICs in the specified vNICset are permitted. When no destination vNICset is specified, traffic to any vNIC is permitted. |
|
|
optional |
A list of IP address prefix sets from which you want to permit traffic. Only packets from IP addresses in the specified IP address prefix sets are permitted. When no source IP address prefix sets are specified, traffic from any IP address is permitted. |
|
|
optional |
A list of IP address prefix sets to which you want to permit traffic. Only packets to IP addresses in the specified IP address prefix sets are permitted. When no destination IP address prefix sets are specified, traffic to any IP address is permitted. |
|
|
optional |
A list of security protocols for which you want to permit traffic. Only packets that match the specified protocols and ports are permitted. When no security protocols are specified, traffic using any protocol over any port is permitted. |
|
|
optional |
Allows the security rule to be enabled or disabled. This parameter is set to |
|
|
optional |
The name of the access control list (ACL) that contains this security rule. |
|
|
optional |
Description of the security rule. |
|
|
optional |
Strings that you can use to tag the security rule. |
Orchestration v1 Attributes for network/v1/vnicset
The following sample JSON shows the key attributes of the network/v1/vnicsets object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/vnicset1",
"appliedAcls": ["/Compute-acme/joe/acl_1", "/Compute-acme/joe/acl_2"]
}
| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
optional |
The list of vNICs associated with this vNICset. |
|
|
optional |
The names of the ACLs applied to the vNICs in the vNICset. A vNICset can have multiple ACLs applied to it and an ACL can be applied to multiple vNIC sets. |
|
|
optional |
Description of the route. |
|
|
optional |
Strings that you can use to tag the IP network exchange. |
Orchestration v1 Attributes for orchestration
The orchestration object type is used in nested orchestrations, when you want to launch one or more orchestrations from within an orchestration. See About Nested Orchestrations. The orchestration object type has only a single attribute, name. The following sample JSON shows this attribute and the table below provides a description of this attribute.
{
"name": "/Compute-acme/joe/myInstances"
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
Orchestration v1 Attributes for secapplication
The following sample JSON shows the key attributes of the secapplication object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/wlsadmin_ssl",
"dport": 7002,
"protocol": "tcp"
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
required |
The protocol to use. The value that you specify can be either a text representation of a protocol or any unsigned 8-bit assigned protocol number in the range 0–254. See Assigned Internet Protocol Numbers ( For example, you can specify either The following text representations are allowed: To specify all protocols, set this to |
|
|
optional |
The TCP or UDP destination port number. You can also specify a port range, such as 5900-5999 for TCP. If you specify This parameter isn’t used by the ICMP protocol or the GRE protocol. Note: This request fails if the range-end is lower than the range-start. For example, if you specify the port range as 5000–4000. |
|
|
optional |
The ICMP type. This parameter is relevant only if you specify
If you specify |
|
|
optional |
The ICMP code. This parameter is relevant only if you specify
If you specify |
|
|
optional |
A description of the security application. |
Orchestration v1 Attributes for seciplist
The following sample JSON shows the required attributes of the seciplist object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/admin_ips",
"secipentries": ["203.0.113.0/30"]
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
required |
A comma-separated list of the subnets (in CIDR format) or IPv4 addresses for which you want to create this security IP list. For example, to create a security IP list containing the IP addresses 203.0.113.1 and 203.0.113.2, enter one of the following:
|
|
|
optional |
A description of the security IP list. |
Orchestration v1 Attributes for seclist
The following sample JSON shows the required attribute of the seclist object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/sysadmin_seclist"
}| Parameters | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
optional |
The policy for inbound traffic to the security list. You can specify one of the following values:
|
|
|
optional |
The policy for outbound traffic from the security list. You can specify one of the following values:
|
|
|
optional |
A description of the security list. |
Orchestration v1 Attributes for secrule
The following sample JSON shows the required attributes of the secrule object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/admin_ssh_to_sysadmin_rule",
"application": "/oracle/public/ssh",
"src_list": "seciplist:/Compute-acme/joe/admin_ips",
"dst_list": "seclist:/Compute-acme/joe/sysadmin_seclist",
"action": "PERMIT"
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. When you specify the object name, ensure that an object of the same type and with the same name doesn’t already exist. If such an object already exists, another object of the same type and with the same name won’t be created and the existing object won’t be updated. |
|
|
required |
The three-part name ( You must use the prefix |
|
|
required |
The three-part name ( You must use the prefix Note: You can specify a security IP list as the destination in a secrule, provided |
|
|
required |
The three-part name of the security application: ( |
|
|
required |
Set this parameter to |
|
|
optional |
A description of the security rule. |
|
|
optional |
Indicates whether the security rule is enabled (set to True) or disabled (False). The default setting is False.
|
Orchestration v1 Attributes for storage/volume
The following sample JSON shows the key attributes of the storage/volume object type. A description of each of the required and optional attributes of this object type is provided in the table that follows the JSON sample.
{
"name": "/Compute-acme/joe/boot",
"bootable": true,
"imagelist": "/oracle/public/oel_6.6_20GB_x11_RD",
"properties": ["/oracle/public/storage/default"],
"size": "22548578304"
}| Parameter | Required or Optional | Description |
|---|---|---|
|
|
required |
The three-part name of the object ( Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive. |
|
|
required |
The size of this storage volume. Use one of the following abbreviations for the unit of measurement:
For example, to create a volume of size 10 gigabytes, you can specify The allowed range is from 1 GB to 2 TB, in increments of 1 GB. |
|
|
required |
Based on your latency and IOPS requirements, select one of the following storage properties:
|
|
|
optional |
The description of the storage volume. |
|
|
optional |
Indicates whether the storage volume can be used as the boot disk for an instance. The default value is If you set the value to
|
|
|
optional |
Strings that you can use to tag the storage volume. |
Uploading an Orchestration v1
To use an orchestration to control the provisioning and life cycle of resources in Compute Classic, you must define the orchestration in a JSON-format file and then upload the orchestration to Compute Classic.
Prerequisites
-
To complete this task, you must have the
Compute_Operationsrole. If this role isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud. -
You must have already created the orchestration file that you want to upload. See Building Your First Orchestration v1.
You should also validate your JSON file. You can do this by using a third-party tool, such as JSONLint, or any other validation tool of your choice. If your JSON isn’t valid, then an error occurs when you upload the orchestration. Oracle doesn’t support or endorse any third-party JSON-validation tool.
Procedure
To upload an orchestration using the CLI, use the opc compute orchestration add command. For help with that command, run the command with the -h option. For the instructions to install the CLI client, see Preparing to Use the Compute Classic CLI in CLI Reference for Oracle Cloud Infrastructure Compute Classic.
To upload an orchestration using the API, use the POST /orchestration/ method. For more information, see REST API for Oracle Cloud Infrastructure Compute Classic.
Orchestrations v1 Life Cycle
When you start an orchestration, the objects defined in it are created and the orchestration moves to the ready state. When you terminate an orchestration, the objects defined in it are deleted and the orchestration moves to the stopped state.
The following figure shows the states that an orchestration can be in.
- starting
-
The orchestration is starting.
- scheduled
-
A future
start_timehas been specified for the orchestration.-
When the current time is equal to or past the
start_timevalue, then the state of the orchestration changes tostarting. -
To cancel a current schedule, terminate the orchestration. The state of the orchestration then changes to
stopping.
-
- ready
-
The orchestration is running.
-
Note that, for any object where the HA policy isn’t specified or is set to
none, you can still update or delete the object using the web console or the API. In this case, the orchestration continues to be in thereadystate, even though some or all of the objects created using that orchestration may have been deleted. -
For instances where the HA policy is set to
active, if the orchestration is in thereadystate, you can update the instance using the web console or the API, but you can’t delete the instance, because it is re-created automatically. To delete such instances, you must terminate the orchestration.
-
- updating
-
The orchestration is being updated.
-
When an orchestration is in the
readyorerrorstate, you can update it by using thePUT /orchestration/nameAPI call. This causes the state of the orchestration to change toupdating. -
When an orchestration is in the
updatingstate, no further updates can be made. Attempts to update such an orchestration are rejected with a validation error. -
If an orchestration in the
updatingstate encounters an error, its state changeserror. If no errors are encountered, then the orchestration completes the updates and returns to thereadystate. -
When you terminate an orchestration that’s in the
updatingstate, it transitions to thestoppingstate.
-
- error
-
One or more instances in the orchestration have encountered an error.
-
The orchestration remains in the
errorstate until all the instances defined in it are running. -
Wait to see if all the instances start running and the state of the orchestration changes automatically to
ready. If that doesn’t happen, then terminate the orchestration, identify and fix the error, and start the orchestration again.
-
- stopping
-
The orchestration is stopping.
If any of the objects defined in an orchestration are used or referenced by another object, the orchestration won’t be able to delete the referenced objects, and it can get stuck in the Stopping state. See My orchestration is stuck in the stopping state.
- stopped
-
The orchestration has stopped. All the objects defined in the orchestration have been deleted.
Starting an Orchestration v1
When you start an orchestration, the objects defined in it are created, and when you stop an orchestration, those objects are deleted.
Plan your orchestrations carefully, so that you can control the creation and deletion of objects that consume resource quotas. For example, if you’re about to start an orchestration that creates a large number of storage volumes, consider whether you really need all those resources. If not, redefine your orchestration to create only the resources that you need.
Prerequisites
-
To complete this task, you must have the
Compute_Operationsrole. If this role isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud. -
You must have uploaded the orchestration to Compute Classic. See Uploading an Orchestration v1.
-
You must have already created all the objects or nested orchestrations that this orchestration depends on.
-
If you created an instance using the Create Instance wizard, the appropriate master, instance, and storage orchestrations would have been created automatically. Next, if you stopped the master orchestration, the instance and storage orchestrations would have stopped. If you want to start those orchestrations again, ensure that all of the objects referenced by those orchestrations exist and are available before starting the master orchestration.
Note:
If any of the objects defined in an orchestration already exist, another object of the same type with the same name won’t be created and the existing object won’t be modified. The orchestration will continue starting, without reporting an error. To ensure that an orchestration creates each object that is defined in it, ensure that each object defined in an orchestration has a unique name, so that objects of the same type with the same name don’t already exist.
Procedure
- Go to the orchestration that you want to start. From the
menu, select Start.
When you start an orchestration, its status changes to Starting and the objects defined in the orchestration are provisioned. When all the objects have been created, the status of the orchestration changes to Ready.
If the orchestration can’t create an object, its status changes to Error. An orchestration might transition from the Error to the Ready state when it completes creating all the specified objects.
If the status of your orchestration continues to show Error, then stop the orchestration, identify and fix the issue in the orchestration JSON file, and the start the orchestration again.
To start an orchestration using the CLI, use the opc compute orchestration update ––action START command. For help with that command, run the command with the -h option. For the instructions to install the CLI client, see Preparing to Use the Compute Classic CLI in CLI Reference for Oracle Cloud Infrastructure Compute Classic.
To start an orchestration using the API, use the PUT /orchestration/name method with the query argument action=START. For more information, see REST API for Oracle Cloud Infrastructure Compute Classic.
After starting an orchestration, you can view its status on the Orchestrations page. If you no longer require any of the objects created by an orchestration, then to delete the objects, stop the orchestration. See Terminating an Orchestration v1.
Monitoring Orchestrations v1
The Orchestrations page shows you a list of your orchestrations and the status of each orchestration.
To complete this task, you must have the Compute_Monitor or Compute_Operations role. If this role isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.
- Go to the orchestration that you want to view and, from the menu, select View.
The orchestration details page shows you the details of the current state of the orchestration, including return parameters, in JSON format. For information about the return parameters of an instance, see Return Parameters Displayed in Orchestrations v1.
To get a list of your orchestrations using the CLI, use the opc compute orchestration list command and to view the details of an orchestration, use the opc compute orchestration get command. For help with these commands, run each command with the -h option. For the instructions to install the CLI client, see Preparing to Use the Compute Classic CLI in CLI Reference for Oracle Cloud Infrastructure Compute Classic.
To get a list of your orchestrations using the API, use the GET /orchestration/container method and to view the details of an orchestration, use the GET /orchestration/name method. For more information, see REST API for Oracle Cloud Infrastructure Compute Classic.
For information about the status of an orchestration, see Orchestrations v1 Life Cycle.
To start an orchestration, see Starting an Orchestration v1 and to stop an orchestration, see Terminating an Orchestration v1.
Return Parameters Displayed in Orchestrations v1
When you view an orchestration using the web console, you’ll see that the orchestration contains additional information about your instances, such as its status and the most recent start or stop time. This information contains return parameters that tell you about the current state of your instance. These return parameters are not part of the input that you provided in the JSON file that you uploaded.
You’ll also see that the orchestration includes certain optional parameters that you might not have specified in the JSON that you uploaded. These optional parameters are displayed either empty, or with a default value. For a description of optional input parameters, see Attributes in Orchestrations v1.
You might also notice that the sequence of objects is different from the sequence of objects in the JSON file that you uploaded. This happens because Compute Classic rearranges the objects according to a certain internal sequence. However, this has no impact on the values you provided or the way your orchestration works.
The following table shows the return parameters displayed for your instance when you view an orchestration using the web console.
| Return Parameters | Description |
|---|---|
| Top-level Parameters | |
status |
Shows the current status of the orchestration. |
account |
Shows the default account for your identity domain. |
uri |
Shows the complete URI of the orchestration. |
info |
The nested parameter |
status_timestamp |
This information is generally displayed at the end of the orchestration JSON. It indicates the time that the current view of the orchestration was generated. This information shows only when the orchestration is running. |
| Oplan Parameters | |
status |
Shows the current status of the |
info |
If the orchestration has encountered an error, the nested parameter |
status_timestamp |
This information is generally displayed towards the end of the orchestration JSON. It indicates the time that the current view of the orchestration was generated. This information shows only when the orchestration is running. |
| Instance Parameters | |
placement_requirements |
Empty. This parameter is not used. |
ip |
If the instance is running, this parameter shows its private IP address. This information doesn’t show when an instance is not running. |
state |
If the orchestration is running, this parameter shows the current state of the instance. This information doesn’t show when an orchestration is stopped or if the instance couldn’t be created due to an error. |
start_time |
If the orchestration is running, this parameter shows the time the instance was created. This information doesn’t show when an orchestration is stopped or if the instance couldn’t be created due to an error. |
error_reason |
If the instance goes into an error state, this parameter shows the reason for the error. This information doesn’t show when an instance is not in an error state. |
Terminating an Orchestration v1
When you terminate or stop an orchestration, all the instances and other resources that were provisioned by that orchestration are deleted.
Note:
When you terminate an orchestration, only the resources that are created by the orchestration are deleted. For example, if you use an orchestration to create storage volumes and attach them to your instances, then such storage volumes are deleted when you terminate the orchestration, and you lose the data stored on those storage volumes. However, if an orchestration specifies only attachments to storage volumes that are created outside the orchestration, then when you terminate the orchestration, the storage volumes aren’t deleted.
If you use the Create Instance wizard to create an instance and the required storage volumes, then separate orchestrations are automatically created for the instance and the storage volumes. When you delete an instance, if you want to retain the data on the attached storage volumes, ensure that you terminate only the instance orchestration, not the master orchestration. If you terminate the master orchestration, both the instance and the storage volumes that were created while creating the instance will be deleted. When you start the master orchestration again later on to re-create the instance, the storage volumes will be re-created; however, the data you had written to those storage volumes will be lost.
To complete this task, you must have the Compute_Operations role. If this role isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.
- Identify the orchestration that you want to terminate. From the menu, select Terminate.The status of the orchestration changes to Stopping.
Note:
If any of the objects defined in an orchestration are used or referenced by another object, the orchestration won’t be able to delete the referenced objects, and it can get stuck in the Stopping state. See My orchestration is stuck in the stopping state.
After all objects have been deleted, the status of the orchestration changes to Stopped. You can view the orchestration, download it, or start it again.
To terminate an orchestration using the CLI, use the opc compute orchestration update ––action STOP command. For help with that command, run the command with the -h option. For the instructions to install the CLI client, see Preparing to Use the Compute Classic CLI in CLI Reference for Oracle Cloud Infrastructure Compute Classic.
To terminate an orchestration using the API, use the PUT /orchestration/name method with the query argument action=STOP. For more information, see REST API for Oracle Cloud Infrastructure Compute Classic.
When you no longer need an orchestration, you can delete it. See Deleting an Orchestration v1.
Downloading an Orchestration v1
You can download the orchestration file to your local host, edit it, and upload a modified orchestration file as a new orchestration.
To complete this task, you must have the Compute_Operations role. If this role isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.
- Sign in to the Compute Classic console. If your domain spans multiple sites, select the appropriate site. To change the site, click the Site menu near the top of the page.
- Click the Orchestrations tab.
- Identify the orchestration that you want to download. From the menu, select Download, and save the orchestration file on your local host.
You can edit the downloaded orchestration file on your local host, as required, by using any text editor, and then upload the edited orchestration file as a new orchestration. Remember to change the name attribute in the JSON file.
For the procedure to upload an orchestration to Compute Classic, see Uploading an Orchestration v1.
To download an orchestration using the CLI, use the opc compute orchestration get command. For help with that command, run the command with the -h option. For the instructions to install the CLI client, see Preparing to Use the Compute Classic CLI in CLI Reference for Oracle Cloud Infrastructure Compute Classic.
To download an orchestration using the API, use the GET /orchestration/name method. For more information, see REST API for Oracle Cloud Infrastructure Compute Classic.
Updating an Orchestration v1
You can update an orchestration in either of the following ways:
-
Directly in the web console, by selecting the Update option.
This option is enabled only when the orchestration is in the Stopped state.
-
By downloading the orchestration file to your local host and updating it using a text editor.
You’ll have to stop and delete the existing orchestration before you can upload the modified orchestration and start it.
Caution:
You must stop an orchestration to update it. When you stop an orchestration, all the resources that were provisioned by that orchestration are deleted.
To complete this task, you must have the Compute_Operations role. If this role isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.
- Sign in to the Compute Classic console. If your domain spans multiple sites, select the appropriate site. To change the site, click the Site menu near the top of the page.
- Click the Orchestrations tab.
- You can update an orchestration either directly in the web console, or by downloading it to your local host.
- To update an orchestration directly in the web console:
-
Identify the orchestration that you want to update. If the orchestration is in the Ready state, to stop the orchestration, from the
menu, select Stop.
Caution:
When you stop an orchestration, all the resources that were provisioned by that orchestration are deleted.
-
When the orchestration is in the Stopped state, from the
menu, select Update.
-
Modify the orchestration as required. Ensure that your modifications contain valid JSON and that you don’t update any return parameters or read-only information. When you’re done, click Update.
-
- To download an orchestration and edit it on your local host:
-
Identify the orchestration that you want to update. From the
menu, select Download, and save the orchestration file on your local host.
-
Modify the downloaded orchestration file on your local host, as required, by using any text editor. You should also validate your JSON file. You can do this by using a third-party tool, such as JSONLint, or any other validation tool of your choice. If your JSON isn’t valid, then an error occurs when you upload the orchestration. Oracle doesn’t support or endorse any third-party JSON-validation tool.
-
Stop the existing orchestration. Go to the orchestration that you want to update and, from the
menu, select Stop.
Caution:
When you stop an orchestration, all the resources that were provisioned by that orchestration are deleted.
-
Delete the existing orchestration. Go to the orchestration that you want to update and, from the
menu, select Delete.
-
Upload the edited orchestration file. Click Upload Orchestration and select the updated orchestration file, then click Upload.
-
- To update an orchestration directly in the web console:
- To start the updated orchestration, from the menu, select Start.
To download an orchestration using the CLI, use the opc compute orchestration get command. After editing an orchestration, to upload it using the CLI, use the opc compute orchestration update command. For help with these commands, run each command with the -h option. For the instructions to install the CLI client, see Preparing to Use the Compute Classic CLI in CLI Reference for Oracle Cloud Infrastructure Compute Classic.
To download an orchestration using the API, use the GET /orchestration/name method. After editing an orchestration, to upload it using the API, use the PUT /orchestration/name method. For more information, see REST API for Oracle Cloud Infrastructure Compute Classic.
Deleting an Orchestration v1
After you’ve stopped an orchestration, if you don’t need it any more, you can delete the orchestration. When you delete an orchestration, it’s no longer listed on the Orchestrations page, and you can’t perform any action on it.
Note:
Deleting an orchestration doesn’t delete the objects created by the orchestration. To delete the objects created by an orchestration, you must stop the orchestration.
Prerequisites
-
To complete this task, you must have the
Compute_Operationsrole. If this role isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud. -
You must have stopped the orchestration that you want to delete. See Terminating an Orchestration v1.
Procedure
- Identify the orchestration that you want to delete. From the menu, select Delete.
To delete an orchestration using the CLI, use the opc compute orchestration delete command. For help with that command, run the command with the -h option. For the instructions to install the CLI client, see Preparing to Use the Compute Classic CLI in CLI Reference for Oracle Cloud Infrastructure Compute Classic.
To delete an orchestration using the API, use the DELETE /orchestration/name method. For more information, see REST API for Oracle Cloud Infrastructure Compute Classic.