Managing Resources Using Orchestrations v2

7 Managing Resources Using Orchestrations v2

Topics

About Orchestrations v2

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 an orchestration to create and manage a collection of instances hosting a multitiered application stack with all the necessary networking, storage, and security resources.

At any time, you can delete and re-create all the objects in an orchestration by terminating and activating the orchestration. Storage attachments, security lists, and so on are re-created and re-associated automatically. If you want to delete and re-create specific objects, you can suspend and activate the orchestration. When orchestrations v2 are suspended, only non-persistent objects are deleted. See Object Persistence in Orchestrations v2.

In orchestrations v2, you can add, remove, or update objects without terminating the entire orchestration.

For an overview of the benefits of using orchestrations v2 and to understand how orchestrations v2 differ from orchestrations v1, see Comparing Orchestrations v1 and Orchestrations v2.

To create instances using orchestrations v2, you build an orchestration in a JSON-formatted file and upload it to Compute Classic. If the orchestration has the desired state specified as active, it starts automatically. For an example of a simple orchestration file that you can use to learn how to build your first orchestration, see Building Your First Orchestration v2. But before that, do read the remainder of this topic and become familiar with the features, terminology, and concepts of orchestrations v2.

Orchestrations v2 Terminology

Term Description

Term	Description
`objects`	An object is the primary building block of an orchestration. Each object contains all the attributes for the compute, networking, or storage resource that you want to create. An orchestration can contain up to 100 objects.
`type`	The `type` attribute defines the type of the object that you want to create. For example, if you want to create a storage volume, the `type` would be `StorageVolume`. If you want to create an instance, the `type` would be `Instance`. See Attributes in Orchestrations v2.
`template`	The `template` attribute defines the properties or characteristics of the Compute Classic resource that you want to create, as specified by the `type` attribute. The fields in the `template` section vary depending on the specified `type`. For example, if you want to create a storage volume, the `type` would be `StorageVolume`, and the `template` would include `size` and `bootable`. If you want to create an instance, the `type` would be `Instance,` and the `template` would include instance-specific attributes, such as `imagelist` and `shape.`

objects

An object is the primary building block of an orchestration.

Each object contains all the attributes for the compute, networking, or storage resource that you want to create.

An orchestration can contain up to 100 objects.

type

The type attribute defines the type of the object that you want to create.

For example, if you want to create a storage volume, the type would be StorageVolume. If you want to create an instance, the type would be Instance.

See Attributes in Orchestrations v2.

template

The template attribute defines the properties or characteristics of the Compute Classic resource that you want to create, as specified by the type attribute.

The fields in the template section vary depending on the specified type.

For example, if you want to create a storage volume, the type would be StorageVolume, and the template would include size and bootable. If you want to create an instance, the type would be Instance, and the template would include instance-specific attributes, such as imagelist and shape.

Object Types in Orchestrations v2

An orchestration can contain up to 100 objects. You can define the type of an object by setting the type parameter. You can define any of the following object types:

Type	Description
`Acl`	Creates an access control list (ACL) that can be applied to interfaces that are part of your IP networks.
`Backup`	Creates a back up of a storage volume using a specified backup configuration.
`BackupConfiguration`	Specifies the storage volume to back up, along with the backup schedule, retention count, and the name of the snapshot to be created.
`Instance`	Creates an instance.
`IpAddressAssociation`	Associates a public IP address reservation with an interface on an instance that is attached to an IP network.
`IpAddressPrefixSet`	Creates an IP address prefix set. This can be used as a source or destination in security rules that determine access to or from the virtual interfaces of instances that are attached to IP networks.
`IpAddressReservation`	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.
`IpNetwork`	Creates an IP network. You can specify an IP network in the networking attributes while creating an instance.
`IpNetworkExchange`	Creates an IP network exchange. You can add IP networks to an IP network exchange either while creating the IP network, or later, by updating the IP network.
`IPReservation`	Reserves a public IP address that can be used in the shared network.
`OSSContainer`	Creates a container in the specified Oracle Cloud Infrastructure Object Storage Classic account.
`Restore`	Restores a storage volume from the specified backup.
`Route`	Creates a route to a specified destination using the specified vNICset.
`SecApplication`	Creates a security application that can be used in a security rule created for the shared network.
`SecIPList`	Creates a security IP list.
`SecList`	Creates a security list.
`SecRule`	Creates a security rule.
`SecurityProtocol`	Creates a security protocol that can be used in a security rule created for IP networks.
`SecurityRule`	Creates a security rule which can be added to an access control list (ACL). ACLs are used to control the flow of traffic across your IP networks.
`SSHKey`	Adds an SSH key.
`StorageAttachment`	Attaches a storage volume to an instance.
`StorageSnapshot`	Creates a snapshot of a storage volume.
`StorageVolume`	Creates a storage volume.
`VirtualNicSet`	Creates a vNICset, which contains one or more virtual network interfaces (vNICs). While creating an instance, you can specify the vNICsets that you want to add each vNIC to.

Recovering Failed Objects in Orchestrations v2

All the objects defined in orchestrations v2 recover automatically from failure. Orchestrations v2 use object references to recover interdependent objects to a healthy state. See Object References and Relationships.

For example, consider an orchestration for an instance. The instance object may reference several other objects, such as storage volumes and IP reservations. For each storage volume to be attached to the instance, a storage attachment object in the orchestration references the instance and the appropriate storage volume. If the instance fails, these storage attachments are re-created automatically.

During the recovery of an object, all the other objects that reference the failed object are considered.

Note that when recovering from a failure, orchestrations don’t consider object relationships, which define the sequence in which the objects in an orchestration must be created.

For information on the life cycle of orchestrations v2, see Orchestration v2 Life Cycle.

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 update, delete, or change the attributes of 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.

Comparing Orchestrations v1 and Orchestrations v2

In earlier releases of Compute Classic, you could use orchestrations v1 to create and manage resources. From release 17.1.6 onwards, you can also create and manage resources using orchestrations v2. With orchestrations v2 you can take advantage of several key enhancements that allow you greater flexibility in referencing and managing resources.

Note:

You shouldn’t try to use or manage resources created using orchestrations v1 by referencing them in orchestrations v2, or vice versa.

There are some similarities and some key differences between orchestrations v1 and orchestrations v2.

Task	Orchestrations v1	Orchestrations v2
Creating an orchestration	Create your orchestration in a JSON file. Your orchestration can contain all the objects you want to create, or can reference nested orchestrations or objects created by other means. See Building Your First Orchestration v1.	Create your orchestration in a JSON file. It is recommended that you create orchestrations that are entirely self-contained. Each orchestration should contain all the objects that you want to create, along with any objects referenced by those objects. The only external objects that an orchestration should reference are shared objects such as security lists that have been created earlier, or Oracle-provided resources such as images or shapes. See Building Your First Orchestration v2.
Creating objects in an orchestration	See Object Types in an Orchestration for a list of objects that you can create using an orchestration.	In addition to the objects that you can create using orchestrations v1, using orchestrations v2 you can also create storage snapshots and scheduled storage volume backups, restore storage volumes from scheduled backups, and add SSH keys. See Object Types in Orchestrations v2 for a list of objects that you can create using orchestrations v2.
Updating objects in a running orchestration	You can add or remove oplans when an orchestration is running. However, you must stop an orchestration if you want to update objects. See Updating an Orchestration v1.	You can add or delete objects in an orchestration when the orchestration is running. You can also update objects to modify certain attributes. See Updating an Orchestration v2.
Managing orchestrated objects individually	You can use master orchestrations to reference multiple individual orchestrations within a single orchestration. This enables you to synchronize starting and stopping multiple orchestrations. However, when required, you can manage each of the nested orchestrations separately. This way you can, for example, delete instances defined in one orchestration, while retaining storage volumes defined in another orchestration. See About Nested Orchestrations.	You can use object persistence to specify objects that should not be deleted when the orchestration is suspended. For example, you can specify persistence for some instances and all storage volumes in an orchestration. Suspending the orchestration deletes nonpersistent objects, while persistent objects are preserved. To delete all objects, terminate the orchestration. See Object Persistence in Orchestrations v2.
Defining dependencies between objects	Relationships determine the sequence in which objects are created. You can define a one-on-one relationships either between different object plans, or between different instances. You can use relationships in a master orchestration to control the sequence in which a series of nested orchestrations is started. See Relationships Between Object Plans.	You define associations between objects using object referencing. Unlike in orchestrations v1, in orchestrations v2 all the objects associated with a given object must be created in the same orchestration. This allows the orchestration to track the status of all referenced objects. You can use relationships to determine the sequence in which objects are created. However, relationships shouldn’t be used to create dependencies, they should be used only to establish the sequence in which resources must be created. For dependencies, use references. See Object References and Relationships.
Re-creating an object when it stops unexpectedly	When you specify the high availability policy for an instance as `active`, if the instance stops unexpectedly, it is re-created automatically. See About High-Availability Policies in an Orchestration.	Failure recovery is implemented automatically for all objects. If any object fails unexpectedly, it is re-created automatically along with any objects that reference the failed object. See Recovering Failed Objects in Orchestrations v2.
Uploading and starting an orchestration	You must upload your orchestration to Compute Classic and then start your orchestration to create the objects defined in the orchestration.	When an orchestration has the desired state specified as `active` in its top-level attributes, then the orchestration starts automatically when it is successfully uploaded to Compute Classic.
Stopping an orchestration	When you stop an orchestration, all objects created by that orchestration are deleted.	You can either suspend or terminate an orchestration. When you suspend an orchestration, persistent objects aren’t deleted. When you terminate an orchestration, all objects are deleted.
Deleting an orchestration	An orchestration must be stopped before it can be deleted. Stopping an orchestration causes objects to be deleted, but deleting an orchestration has no impact on objects that are defined in the orchestration.	You can delete an orchestration when it is in the Ready, Suspended, Stopped or Error state. Any objects created by the orchestration are deleted when the orchestration is deleted.

Object References and Relationships

Object References

When you define an object in an orchestration, you can create dependencies with other objects by using references. With references, you can link an object to another using just the label of the target object. For example, you can reference the name of a storage volume from a storage attachment object using the format {{volume_label:name}}.

When recovering an object from a failure, Compute Classic recovers all the referenced objects automatically.

In the following example, the StorageAttachment object references the name attribute of an instance and the name attribute of a storage volume that’s to be attached to the instance.

{
	"description": "a storage attachment object with references",
	"label": "attachment_object",
	"type": "StorageAttachment",
	"template": {
		"index": 1,
		"instance_name": "{{myInstance1:name}}",
		"storage_volume_name": "{{myVolume1:name}}"
	}
}

myInstance1 is the label of the instance object.
myVolume1 is the label of the storage volume object.

Object Relationships

You can use the relationships attribute of an object to specify other related objects that must be created first.

Ensure that you don’t create a relationship between a persistent and a nonpersistent object. A persistent object can be in a relationship only with another persistent object.

For example, if you define two instances – instance1 and instance2 – in an orchestration and you want instance1 to be created first, then in the relationships attribute of instance2, specify that it depends on instance1.

"relationships": [
  {
    "type": "depends",
    "targets": ["instance1"]
  }
]

Note:

When recovering from a failure, orchestrations don’t consider object relationships. So in the preceding example, if instance2 fails, then the orchestration re-creates it, but it doesn’t ensure first that instance1 is available. To ensure that dependent objects are re-created, use object referencing.

For more complex scenarios, you can define multiple relationships.

For example, to ensure that instance4 starts after instance1, instance2, and instance3 are started, specify the following in the relationships attribute of instance4.

"relationships": [
  {
    "type": "depends",
    "targets": ["instance1","instance2","instance3"]
  }
]

If all the related instances fail, then the orchestration will re-create them. But when re-creating instance4, the orchestration does not check whether the other instances exist.

Object Persistence in Orchestrations v2

Orchestrations v2 enable you to provision an entire stack of cloud resources and manage them individually. Unlike orchestrations v1, you don’t need to have separate orchestrations for different sets of objects such as storage, networking, or instances to ensure that they persist.

In some situations, you might want to stop certain objects while retaining others defined in the same orchestration. Using object persistence, you can ensure that when an orchestration is suspended, certain objects are not deleted.

To make an object persistent, set the persistent attribute to true. When an object is set to persist, it is not deleted when the orchestration is suspended. If the orchestration is terminated, then all the objects are deleted. For information about suspending and terminating orchestrations v2, see Managing Orchestrations v2 Using the REST API.

If you set the persistent attribute of an object to true, then you must set the persistent attribute of all the dependent objects as well to true. For example, if a persistent instance references a bootable storage volume, the storage volume must also be persistent.

The following sample JSON illustrates a persistent storage volume.

{
  "objects": 
  {
    {
      "type": "StorageVolume",
      "description": "a persistent storage volume",
      "label": "myVolume1",
      "persistent": true,
      "template": {
        "name": "/Compute-acme/jack.jones@example.com/volume1",
        "properties": [
          "/oracle/public/storage/default"
         ],
        "size": "2G"
      }
    }
  }
}

Object Types in Orchestrations v2

You can define any of the following types of objects using orchestrations v2. The attributes for each object vary depending on the object type.

For the attributes used to define each of these object types, see Orchestration v2 Attributes Specific to Each Object Type.

Type	Description
`Acl`	Creates an access control list (ACL) that can be applied to interfaces that are part of your IP networks.
`Backup`	Creates a back up of a storage volume using a specified backup configuration.
`BackupConfiguration`	Specifies the storage volume to back up, along with the backup schedule, retention count, and the name of the snapshot to be created.
`Instance`	Creates an instance.
`IpAddressAssociation`	Associates a public IP address reservation with an interface on an instance that is attached to an IP network.
`IpAddressPrefixSet`	Creates an IP address prefix set. This can be used as a source or destination in security rules that determine access to or from the virtual interfaces of instances that are attached to IP networks.
`IpAddressReservation`	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.
`IpNetwork`	Creates an IP network. You can specify an IP network in the networking attributes while creating an instance.
`IpNetworkExchange`	Creates an IP network exchange. You can add IP networks to an IP network exchange either while creating the IP network, or later, by updating the IP network.
`IPReservation`	Reserves a public IP address that can be used in the shared network.
`OSSContainer`	Creates a container in the specified Oracle Cloud Infrastructure Object Storage Classic account.
`Restore`	Restores a storage volume from the specified backup.
`Route`	Creates a route to a specified destination using the specified vNICset.
`SecApplication`	Creates a security application that can be used in a security rule created for the shared network.
`SecIPList`	Creates a security IP list.
`SecList`	Creates a security list.
`SecRule`	Creates a security rule.
`SecurityProtocol`	Creates a security protocol that can be used in a security rule created for IP networks.
`SecurityRule`	Creates a security rule which can be added to an access control list (ACL). ACLs are used to control the flow of traffic across your IP networks.
`SSHKey`	Adds an SSH key.
`StorageAttachment`	Attaches a storage volume to an instance.
`StorageSnapshot`	Creates a snapshot of a storage volume.
`StorageVolume`	Creates a storage volume.
`VirtualNicSet`	Creates a vNICset, which contains one or more virtual network interfaces (vNICs). While creating an instance, you can specify the vNICsets that you want to add each vNIC to.

Orchestration v2 Templates and Samples

The templates and samples 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 v2. To get started with building an orchestration, see Building Your First Orchestration v2.

Note:

The orchestration templates provided here use placeholders for object names, labels, and other user-specific values. Replace these placeholders with values specific to your environment. For example, replace the identity domain acme with your identity domain and the user name joe or joe.jonathan@example.com with your user name.

Orchestration v2 Template

The following is a JSON template for the structure of an orchestration, with the top-level attributes highlighted.

{
  "name": "/Compute-identity_domain/user/orchestration_name",	
  "description": "OrchestrationDescription",
  "desired_state": "state",
  "tags": ["tag-1", "tag-2"],
  "objects": [
    {
      "type": "objectType",
      "description": "ObjectDescription",
      "label": "ObjectLabel",
      "persistent": true,
      "template": {
        attributes  
      }
    },
    {
      "type": "objectType",
      "description": "ObjectDescription",
      "label": "ObjectLabel",
      "persistent": true,
      "template": {
        attributes
      }
    },
    .
    . up to 100 objects
    .
  ]
}

Orchestration v2 Template for Objects

The objects attribute is a top-level attribute in an orchestration. Within this attribute, you can specify one or more objects.

"objects": [
  {
    "type": "ObjectType",
    "description": "ObjectDescriptionHere",
    "label": "ObjectLabel",
    "persistent": true,
    "template": {
                          }
  }
]

Orchestration v2 Samples for Each Object Type

Orchestration v2 Sample for Acl

Use this type of object to create an access control list that can be applied to vNICsets in IP networks. See Configuring IP Networks.

"objects": 
[
 {
  "label": "My-access-control-list",
  "type": "Acl",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/Acl-for-vnicset1"
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for Backup

Use this type of object to create a backup of a storage volume using a specified backup configuration. See Scheduling Backups of Storage Volumes and Restoring from Backups.

"objects": 
[
 {
  "label": "Backup-from-backup-config-1",
  "type": "Backup",
  "template": 
  {
     "backupConfigurationName": "/Compute-acme/joe.jonathan@example.com/backupConfig-for-vol1",
     "name": "/Compute-acme/joe.jonathan@example.com/backup-1"
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for BackupConfiguration

Use this type of object to create a backup configuration. This configuration is used to schedule backups for a specified storage volume. See Scheduling Backups of Storage Volumes and Restoring from Backups.

"objects": 
[
 {
  "label": "Backup-schedule-for-vol1",
  "type": "BackupConfiguration",
  "template": 
   {
    "volumeUri": "http://api-z999.compute.us0.oraclecloud.com/storage/volume/Compute-acme/joe.jonathan@example.com/vol1",
    "name": "/Compute-acme/joe.jonathan@example.com/backupConfig-for-vol1",
    "enabled": false,
    "backupRetentionCount": 2,
    "interval": {
         "Hourly":{"hourlyInterval": 1}
                }
     }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for Instance

Use this type of object to create instances.

"objects": 
[
 {
  "label": "MyInstance",
  "type": "Instance",
  "description": "My instance",
  "template": 
   {
     "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 objects here.>
]

Orchestration v2 Sample for IpAddressAssociation

Use this type of object to create an IP association between an IP reservation and a vNIC in an IP network. See Configuring IP Networks.

"objects": 
[
 {
  "label": "IP-Association-for-vnic1-on-instance1",
  "type": "IpAddressAssociation",
  "template": 
  {
    "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 objects here.>
]

Orchestration v2 Sample for IpAddressPrefixSet

Use this type of object to create an IP address prefix set to use in IP networks. See Configuring IP Networks.

"objects": 
[
 {
  "label": "IPaddress-prefix-set-1",
  "type": "IpAddressPrefixSet",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/ext_ip_addresses",
    "ipAddressPrefixes": ["203.0.113.0/30", "192.51.100.1/24"]
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for IpAddressReservation

Use this type of object to reserve an IP address to use in IP networks. See Configuring IP Networks.

"objects": 
[
 {
  "label": "IP-Reservation-for-instance-1-on-IP-network-1",
  "type": "IpAddressReservation",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/IPres-for-instance1-vnic1",
    "ipAddressPool": "/oracle/public/public-ippool"
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for IpNetwork

Use this type of object to create IP networks. See About IP Networks.

"objects":
[
 {
  "label": "ipnet1",
  "type": "IpNetwork",
  "description": "My IP network with IP network exchange",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/ipnet1",
    "ipAddressPrefix": "192.168.3.0/24",
    "ipNetworkExchange": "/Compute-acme/joe.jonathan@example.com/ipnetworkexchange1",
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for IpNetworkExchange

Use this type of object to create an IP network exchanges. IP network exchanges are used to connect IP networks. See Configuring IP Networks.

"objects": 
[
 {
  "label": "ipnetworkexchange",
  "type": "IpNetworkExchange",
  "description": "My IP network exchange",
  "template": 
	{
	  "name": "/Compute-acme/joe.jonathan@example.com/ipnetworkexchange1"
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for IPReservation

Use this type of object to reserve permanent public IP addresses to use on the shared network. See About Public IP Addresses.

"objects": 
[
 {
  "label": "IP-Reservation",
  "type": "IPReservation",
  "description": "My IP address reservation",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/ipres1",
    "parentpool": "/oracle/public/ippool",
    "permanent": true
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for OSSContainer

Use this type of object to create a container in your associated Oracle Cloud Infrastructure Object Storage Classic account.

"objects": 
[
 {
  "label": "My-OSS-Container",
  "type": "OSSContainer",
  "template": 
  {
    "account": "/Compute-acme/cloud_storage",
    "container": "Container_1",
    "delete_remote": false
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for Restore

Use this type of object to restore a storage volume from a backup created using a backup configuration. See Scheduling Backups of Storage Volumes and Restoring from Backups.

"objects": 
[
 {
  "label": "Restored-vol-1",
  "type": "Restore",
  "template": 
   {
     "name": "/Compute-acme/joe.jonathan@example.com/restored-vol-1",
     "backupName": "/Compute-acme/joe.jonathan@example.com/backup-1",
     "volumeUri": "http://api-z999.compute.us0.oraclecloud.com/storage/volume/Compute-acme/joe.jonathan@example.com/restored-vol-1"
    }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for Route

Use this type of object to create routes to direct traffic across your IP networks. See Configuring IP Networks.

"objects": 
[
 {
  "label": "MyRoute",
  "type": "Route",
  "template": 
  {
    "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 objects here.>
]

Orchestration v2 Sample for SecApplication

Use this type of object to define security applications for use in security rules in the shared network. See About Security Applications.

"objects": 
[
 {
  "label": "MySecApplication",
  "type": "SecApplication",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/wlsadmin_ssl",
    "dport": 7002,
    "protocol": "tcp"
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for SecIPList

Use this type of object to define a set of IP addresses that you want to use as a source in a security rule in the shared network. See About Security IP Lists.

"objects": 
[
 {
  "label": "MySecurityIPList",
  "type": "SecIPList",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/admin_ips",
    "secipentries": ["203.0.113.0/30"]
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for SecList

Use this type of object to define security lists. See About Security Lists.

"objects": 
[
 {
  "label": "MySecurityList",
  "type": "SecList",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/sysadmin_seclist"
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for SecRule

Use this type of object to define security rules that control access to your instances in the shared network. See About Security Rules.

"objects": 
[
 {
  "label": "MySecurityRules",
  "type": "SecRule",
  "template": 
  {
    "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"
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for SecurityProtocol

Use this type of object to create a security protocol that can be used in a security rule in IP networks. See Configuring IP Networks.

"objects": 
[
 {
  "label": "Security-protocol-for-IP-networks",
  "type": "SecurityProtocol",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/secprotocol_1",
    "description": "Security Protocol 1",
    "ipProtocol": "tcp",
    "srcPortSet": ["10", "55-100"],
    "dstPortSet": ["20", "155-1100"]
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for SecurityRule

Use this type of object to create a security rule that can be used to control traffic to vNICs in IP networks. See Configuring IP Networks.

"objects": 
[
 {
  "label": "IP-network-secrule-1",
  "type": "SecurityRule",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/ipnetSecrule1",
    "acl": "/Compute-acme/joe.jonathan@example.com/acl_1",
    "description": "Security Rule for ACL-1",
    "flowDirection": "egress",
    "secProtocols": ["/Compute-acme/joe.jonathan@example.com/secprotocol_1"],
    "srcIpAddressPrefixSets": ["/Compute-acme/joe.jonathan@example.com/ext_ip_address_list_1"]
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for SSHKey

Use this type of object to add an SSH public key to your account. See Enabling Secure Access to Instances Using SSH.

"objects": 
[
 {
  "label": "My-SSH-key",
  "type": "SSHKey",
  "template": 
   {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDzU21CEj6JsqIMQAYwNbmZ5P2BVxA...",
    "name": "/Compute-acme/joe.jonathan@example.com/key1"
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for StorageAttachment

Use this type of object to attach a storage volume to an instance after the instance has been created.

"objects":
[
 {
  "label": "Attach-vol1-to-instance1",
  "type": "StorageAttachment",
  "template": 
   {
     "index": 1,
     "storage_volume_name": "/Compute-acme/joe.jonathan@example.com/vol1",
     "instance_name": "/Compute-acme/joe.jonathan@example.com/instance1/a6462ba5-5933-41a1-b853-fcfcb421cb07/5fd18f4a-2ac2-4548-a0cf-57774c024742"
    }
  },
  <Define other objects here.>
]

Orchestration v2 Sample for StorageSnapshot

Use this type of object to create a snapshot of a storage volume. See Backing Up and Restoring Storage Volumes Using Snapshots.

"objects": 
[
 {
  "label": "My-Storage-Snapshot",
  "type": "StorageSnapshot",
  "template": 
   {
     "name": "/Compute-acme/joe.jonathan@example.com/vol1-snapshot
     "volume": "/Compute-acme/joe.jonathan@example.com/vol1",
     "property": "/oracle/public/storage/snapshot/default"
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for StorageVolume

Use this type of object to create storage volumes that you want to attach to your instances. See About Storage Volumes.

"objects": 
[
 {
  "label": "MyStorageVolume",
  "type": "StorageVolume",
  "template": 
  {
    "name": "/Compute-acme/joe.jonathan@example.com/boot",
    "bootable": true,
    "imagelist": "/oracle/public/oel_6.6_20GB_x11_RD",
    "properties": ["/oracle/public/storage/default"],
    "size": "22548578304"
   }
 },
  <Define other objects here.>
]

Orchestration v2 Sample for VirtualNicSet

Use this type of object to create vNICsets to use in IP networks. See Configuring IP Networks.

"objects": 
[
 {
  "label": "vNICset-1",
  "type": "VirtualNicSet",
  "template": 
  {
    "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 objects here.>
]

Workflow for Creating Instances Using Orchestrations v2

To use an orchestration to create and manage compute, networking, or storage resources:

Build your orchestration.
An orchestration is defined in a JavaScript Object Notation (JSON) file that contains the attributes of the Compute Classic objects that you want to create. See Building Your First Orchestration v2.
Upload the orchestration to Compute Classic. See Uploading an Orchestration v2.
Start an orchestration. See Starting an Orchestration v2.

Note:

If the desired_state parameter is set to active in the orchestration JSON, the orchestration is activated automatically when you upload it.
While the orchestration is running, you can add, update, or delete an instance. See Updating an Orchestration v2.
To delete objects that are not set to be persistent, suspend the orchestration.
To delete all objects defined in the orchestration, stop the orchestration. See Terminating an Orchestration v2.

Building Your First Orchestration v2

Sample Orchestration v2 for Creating a Single Instance

You can define all your cloud resources in a single orchestration and manage the resources individually.

Use the following sample JSON as a starting point for building your first orchestration.

{
  "description": "Simple orchestration with an instance, storage volumes, ssh key, and a security list",
  "name": "/Compute-acme/joe.jonathan@example.com/simple_orchestration",
  "desired_state": "active",
  "objects": [
    {
      "type": "SSHKey",
      "label": "my_key",
      "template": {
        "enabled": false,
        "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDzU21CEj6JsqIMQAYwNbmZ5P2BVxA...",
        "name": "/Compute-acme/jack.jones@example.com/key1"
       }
    },
    {
      "type": "SecList",
      "label": "my_seclist",
      "template": {
        "name": "/Compute-acme/joe.jonathan@example.com/my_instances"
      }
    },
    {
      "type": "StorageVolume",
      "label": "boot_volume",
      "description": "Boot disk for your instance",
      "persistent": true,
      "template": {
        "name": "/Compute-acme/jack.jones@example.com/BootVolume",
        "bootable": true,
        "imagelist": "/oracle/public/OL_6.7_UEKR4_x86_64",
        "properties": [
          "/oracle/public/storage/default"
         ],
         "size": "23G"
      }
    },
    {
      "type": "StorageVolume",
      "label": "data_volume",
      "description": "Data disk for your instance",
      "persistent": true,
      "template": {
        "name": "/Compute-acme/jack.jones@example.com/DataVolume",
        "properties": [
          "/oracle/public/storage/default"
         ],
         "size": "2G"
      }
    },
    {
      "type": "IPReservation",
      "label": "ip_reservation",
      "description": "IP reservation for your instance",
      "persistent": true,
      "template": {
        "parentpool": "/oracle/public/ippool",
        "permanent": true
      }
    },
    {
      "type": "Instance",
      "description": "demo instance",
      "label": "demo_instance",
      "template": {
        "label": "demo_instance",
        "shape": "oc3",
        "networking": {
          "eth0": {
            "seclists": [ "{{my_seclist:name}}" ],
            "nat": "ipreservation:{{ip_reservation:name}}"
          }
        },
        "storage_attachments": [
        {
          "index": 1,
          "volume": "{{boot_volume:name}}"
        },
        {
          "index": 2,
          "volume": "{{data_volume:name}}"
        }
        ],
      "boot_order": [1],
      "sshkeys": [
        "{{my_key:name}}"
        ]
      }
    }
  ],
  "tags": ["sample"]
}

This sample orchestration does the following:

Defines an instance with the label demo_instance, the oc3 shape, and using the /oracle/public/OL_6.7_UEKR4_x86_64 image.
Defines and associates an SSH public key with the label my_key with the instance.
Defines a security list with the label my_seclist and adds the instance to it.
Defines and attaches the bootable storage volume with the label boot_volume to the instance.
Defines and attaches the data storage volume with the label data_volume to the instance.
Defines an IP reservation with the label ip_reservation and associates it with the instance.

Note:

To learn about the structure of an orchestration, see Orchestration v2 Templates and Samples. For information about all the attributes that you can define in an orchestration, see Attributes in Orchestrations v2.

Steps for Building Your First Orchestration v2

Copy the sample orchestration JSON to a plain text file, and open the file in any text editor.
Replace the name of the orchestration with an appropriate three-part name (/Compute-identity_domain/user/object).

Note:

While editing the sample, remember to replace all the placeholder values with values specific to your environment. For example, replace the identity domain acme with your identity domain and the user name joe.jonathan@example.com with your user name.
Change the value of the imagelist attribute to any image that you want to use.
Under template, change the value of the label attribute to any label that you want.
If you want to attach the instance to more security lists, define each security list in the orchestration, and reference each security list in the instance. In the instance object, remember to enclose each security-list name in double quotation marks and separate the security-list names by using commas. See the following example:
```
"seclists": [
  "{{my_seclist:name}}",
  "{{my_devlist:name}}",
  "{{my_prodlist:name}}"
]
```
If you’re creating a Linux instance enabled for SSH access, replace the key in the my_key object with your public key.
If you want to add more SSH keys, define each key as an object in the orchestration, and reference each key in double quotation marks and separate the keys by using commas. See the following example:
```
"sshkeys": [
  "{{my_key1:name}}",
  "{{my_key2:name}}",
  "{{my_key3:name}}"
]
```
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. To log in to your Windows instance using RDP, see Accessing a Windows Instance Using RDP.
Save the JSON file.

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 format isn’t valid, then an error message is displayed when you upload the orchestration.

Note:

Oracle doesn’t support or endorse any third-party JSON-validation tool.

Your orchestration JSON file is ready now.

To create instances by using this orchestration, you must upload it to Compute Classic. See Uploading an Orchestration v2.

Attributes in Orchestrations v2

You specify attributes in orchestrations at several levels. At the top level, you specify certain attributes for the orchestration as a whole. Then, you specify attributes for each object defined in the orchestration. Finally, there are attributes that are specific to each type of object.

Top-level orchestration attributes

The top-level orchestration attributes define the name and description of an orchestration, along with other information such as the desired state, the current status of the orchestration, and the tags associated with the orchestration. See Top-Level Orchestration v2 Attributes.
General attributes for all object types

These attributes specify the object type; a label, name, and description for the object, and so on. See General Attributes for Objects in Orchestrations v2.
Attributes specific to each object type

These are the attributes defined in the template for each object type. See Orchestration v2 Attributes Specific to Each Object Type.

Top-Level Orchestration v2 Attributes

The top-level orchestration attributes define the name and description of an orchestration, along with other information such as the desired state, the current status of the orchestration, and the tags associated with the orchestration.

The following JSON template shows the top-level orchestration attributes. A description of each attribute is provided in the table that follows the JSON template.

Note:

Attributes for each object that you define in an orchestration vary depending on the object type. For information about object-specific attributes, see Object Types in Orchestrations v2.

{
  "name": "/Compute-identity_domain/user/orchestration_name",	
  "description": "OrchestrationDescriptionHere",
  "desired_state": "state",
  "tags": ["sometag", "sometag2"],
  "objects": [
    {
      ...
    },
    {
     ...
    },
    .
    . up to 100 objects
    .
  ]
}

Attribute	Required or Optional	Description
`name`	required	The three-part name of the orchestration (`/Compute-identity_domain/user/orchestration_name`).
`desired_state`	required	The desired state for the orchestration. You can specify one of the following desired states: `active`: The orchestration starts immediately and all objects defined by the orchestration are created. `inactive`: The orchestration stops immediately and all objects defined by the orchestration are deleted. `suspend`: Nonpersistent objects are deleted and persistent objects are retained. `delete`: All objects are deleted and the orchestration itself is also deleted.
`description`	optional	Text string describing the orchestration.
`objects`	required	The list of objects in the orchestration. An object is the primary building block of an orchestration. An orchestration can contain up to 100 objects.
`tags`	optional	A list of the tags that you want to associate with your orchestration.

General Attributes for Objects in Orchestrations v2

Any object that you define in an orchestration, regardless of the object type, has certain general attributes.

The following is a JSON template for an orchestration, with the general attributes for objects highlighted. The table that follows the template contains the descriptions for these attributes.

{
  "name": "/Compute-identity_domain/user/orchestration_name",	
  "description": "OrchestrationDescriptionHere",
  "desired_state": "state",
  "tags": ["sometag","sometag2"],
  "objects": [
    {
      "label": "someText",
      "type": "objectType",
      "desired_state": "inherit",
      "template": {
        attributes  
        }
      "name": "objectName",
      "description": "ObjectDescriptionHere",
      "persistent": true,
      "relationships": [
        "type": "rel_type",
        "targets": "["object1","object2",...]
        ]
    },
    .
    . up to 100 objects
    .
  ]
}

Parameter	Required or Optional	Description
`label`	required	A text string describing the object. A label can contain only alphanumeric characters, hyphens, and underscores. It can’t contain unicode characters and spaces. In an orchestration, the label for each object must be unique. Maximum length: 256 characters.
`type`	required	The type of object that you want to create. Specify one of the following object types. `Acl` `Backup` `BackupConfiguration` `Instance` `IpAddressAssociation` `IpAddressPrefixSet` `IpAddressReservation` `IpNetwork` `IpNetworkExchange` `IPReservation` `OSSContainer` `Restore` `Route` `SecApplication` `SecIPList` `SecList` `SecRule` `SecurityProtocol` `SecurityRule` `SSHKey` `StorageAttachment` `StorageSnapshot` `StorageVolume` `VirtualNicSet` For a brief description of each object type, see Object Types in Orchestrations v2.
`template`	required	The parameters specific to each object `type`. See Orchestration v2 Attributes Specific to Each Object Type.
`name`	optional	The four-part name of the object (`/Compute-identity_domain/user/orchestration/object` If you don’t specify a name for this object, 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 a object already exists, then another object of the same type and with the same name won’t be created and the existing object won’t be updated.
`orchestration`	optional	The three-part name of the orchestration (`/Compute-identity_domain/user/orchestration_name`) to which the object belongs.
`desired_state`	optional	Specifies the desired state of an object. This allows you to manage the state of an object independently from the state of the orchestration. Specify one of the following: `inherit`: The default. The desired state of the object is the same as the desired state of the orchestration. Note that you can’t specify states such as `active`, `inactive`, or `suspend` at the object level. These states must be inherited from the orchestration’s desired state. `delete`: The object definition is removed from the orchestration JSON and the underlying object that was created by this orchestration is also deleted.
`description`	optional	A text string describing the object.
`persistent`	optional	Specifies whether the object should persist when the orchestration is suspended. Specify one of the following: `true`: The object persists when the orchestration is suspended. `false`: The object is deleted when the orchestration is suspended. By default, `persistent` is set to `false`. It is recommended that you specify `true` for storage volumes and other critical objects. Persistence applies only when you’re suspending an orchestration. When you terminate an orchestration, all the objects defined in it are deleted.
`relationships`	optional	The relationship between the objects that are created by this orchestration. The `depends` relationship indicates that the specified target objects must be created first. For example, if you define two instances – `instance1` and `instance2` – in an orchestration and you want `instance1` to be created first, then in the `relationships` attribute of `instance2`, specify that it `depends` on `instance1`. `"relationships": [ { "type": "depends", "targets": ["instance1"] } ]` Note that when recovering from a failure, the orchestration doesn’t consider object `relationships`. Orchestrations v2 use object references to recover interdependent objects to a healthy state. See Object References and Relationships.

Orchestration v2 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.

Orchestration v2 Attributes for `Acl`

The following sample JSON shows the key attributes of the 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`enabledFlag`	optional	Allows the ACL to be enabled or disabled. This parameter is set to `true` by default. Specify `false` to disable the ACL.
`description`	optional	Description of the ACL.
`tags`	optional	Strings that you can use to tag the ACL.

Orchestration v2 Attributes for `Backup`

The following sample JSON shows the required attributes of the Backup 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.

{
    "backupConfigurationName": "{{My_Backup_Configuration:name}}",
    "name": "/Compute-acme/jack.jones@example.com/BACKUP-A"
 }

Parameter Required or Optional Description

Parameter	Required or Optional	Description
`backupConfigurationName`	required	A reference to the `name` of the `BackupConfiguration` object or the multi-part name of the backup configuration.
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`description`	optional	Description of the backup storage volume.

backupConfigurationName

required

A reference to the name of the BackupConfiguration object or the multi-part name of the backup configuration.

name

required

The three-part name of the object (/Compute-identity_domain/user/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.

description

optional

Description of the backup storage volume.

Orchestration v2 Attributes for `BackupConfiguration`

The following sample JSON shows the required attributes of the BackupConfiguration 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.

{
       "volumeUri": "{{My_Storage_Volume:uri}}",
       "name": "/Compute-acme/jack.jones@example.com/backupConfigVol1",
       "enabled": false,
       "backupRetentionCount": 2,
       "interval": {
         "Hourly": {
           "hourlyInterval": 1
         }
      }
}

Parameter	Required or Optional	Description
`interval`	required	The interval between back ups. There are two kinds of intervals. Each Interval has its own JSON format. Your Interval field should look like one of the following: `"interval":{"Hourly":{"hourlyInterval":2}}` `{"DailyWeekly":{"daysOfWeek":["MONDAY"],"timeOfDay":"03:15","userTimeZone":"America/Los_Angeles"}}`
`volumeUri`	required	The URI of the storage volume that you want to back up, or a reference to the `uri` parameter of the `StorageVolume` object.
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`backupRetentionCount`	required	The number of backups that should be retained. Minimum is 1.
`enabled`	optional	Set to `true` to enable backups. If not specified, the default is `true`.
`description`	optional	Description of the backup configuration.

Orchestration v2 Attributes for `Instance`

Topics

Instance Attributes

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"],
              "relationships": [
                      "type": "different_node",
                      "instances": ["instance:/Compute-acme/jack.jones@example.com/instance1"]  
        ]
              "storage_attachments": 
                    [
                      {
                  "index": 1,
                  "volume": "/Compute-acme/joe/boot"
                       }
                    ]
            }
       ]
 }

Parameter	Required or Optional	Description
`shape`	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.
`name`	optional	The three-part name of the instance (`/Compute-identity_domain/user/name`). If you specify this parameter, then the full name of the instance would be in the format, `/Compute-identity_domain/user/name_you_specify/id`. If you don’t specify this parameter, then the full name would be in the format, `/Compute-identity_domain/user/id`. In either case, id is an autogenerated ID. Examples of Instance Names: When you specify `/Compute-acme/jack/vm1` as the value of the `name` parameter: `/Compute-acme/jack/vm1/300a7479-ec90-4826-98b9-a725662628f1` When you don’t specify the `name` parameter: `/Compute-acme/jack/38ef677e-9e13-41a7-a40c-2d99afce1714` Although this is an optional parameter, specifying a meaningful name makes it easier for you to identify your instances.
`label`	optional	A text string to identify the instance. This label is used when defining relationships in an orchestration.
`tags`	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.
`desired_state`	optional	The only allowed values are `running` or `shutdown`. If you specify `running`, the instance is started. If you specify `shutdown`, the instance is stopped. You can start the instance again later by updating the instance with the `desired_state` specified as `running`.
`attributes`	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: `{ "enable_rdp": true, "administrator_password": "Specify_password_here" }` 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 `http://192.0.0.192/latest/attributes`. For more information about retrieving user-defined attributes, see Retrieving User-Defined Instance Attributes.
`imagelist`	optional	The three-part name (`oracle/public/imagelist_name`) of the image list containing the image to be used (example: `/oracle/public/OL_6.7_UEKR4_x86_64`). You must use this attribute if you don’t specify a bootable storage volume by using the `boot_order` attribute. If you specify the `imagelist` attribute as well as the `boot_order` attribute, then the `imagelist` attribute is ignored.
`storage_attachments`	optional	If you specify the `storage_attachments` parameter, then specify the following subparameters for each attachment: `volume`: The three-part name (`/Compute-identity_domain/user/object_name`) of the storage volume that you want to attach to the instance. Note that volumes attached to an instance at launch time can't be detached. `index`: The index number for the volume. The allowed range is 1 to 10. If you want to use a storage volume as the boot disk for an instance, you must specify the index number for that volume as `1`. The index determines the device name by which the volume is exposed to the instance. Index 0 is allocated to a nonpersistent boot disk, `/dev/xvda.` An attachment with index 1 is exposed to the instance as `/dev/xvdb`, an attachment with index 2 is exposed as `/dev/xvdc`, and so on.
`boot_order`	optional	The index number of the bootable storage volume that should be used to boot the instance. The only valid value is `1`. If you set this attribute, you must also specify a bootable storage volume with index number `1` in the `volume` sub-parameter of `storage_attachments`. When you specify `boot_order`, you don’t need to specify the `imagelist` attribute, because the instance is booted using the image on the specified bootable storage volume. If you specify both `boot_order` and `imagelist,` the `imagelist` attribute is ignored.
`hostname`	optional	The host name assigned to the instance. On an Oracle Linux instance, this host name is displayed in response to the `hostname` command. 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: If no DNS name is specified in the `networking` attribute, then the DNS name is set to the host name, and a reverse DNS record (PTR) is created for the host name. If the DNS name specified in the `networking` attribute matches the host name, then that record also creates a reverse DNS record for the host name. If the `dns` attribute under `networking` is set to an empty list (`[]`), then no DNS records are created even if a host name is specified. The instance still receives its host name through DHCP, and can perform a reverse lookup of its host name. However, no other instance can perform this reverse lookup. Note: If an instance has network interfaces defined only for IP networks and doesn’t have any interface on the shared network, then when `hostname` is specified, no DNS entries are set. In this case, DNS entries are set by the `dns` subparameter of the `networking` attribute.
`reverse_dns`	optional	If set to `true` (default), then reverse DNS records are created. If set to `false`, no reverse DNS records are created.
`networking` (attributes for the shared network)	optional	`ethn`: The interface that you’re defining. Oracle-provided images with release version 16.3.6 and later support eight vNICs. You can also create private images that support multiple vNICs. If the image you’ve specified supports eight vNICs, then you can specify up to eight network interfaces, from `eth0` to `eth7`. 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 `ethn` interface. 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: `seclists:` (Optional) The security lists that you want to add the instance to. `nat:` (Optional) Indicates whether a temporary or permanent public IP address should be assigned to the instance. `dns:` (Optional) A list of the DNS A record names for the instance. This name is relative to the internal DNS domain. `model:` (Optional) The type of network interface card (NIC). The only allowed value is `e1000`. `name_servers:` (Optional) The name servers that are sent through DHCP as option 6. You can specify a maximum of eight name server IP addresses per interface. `search_domains:` (Optional) The search domains that should be sent through DHCP as option 119. You can enter a maximum of eight search domain zones per interface. For more information about each of these subparameters, see Subparameters for a Network Interface on the Shared Network.
`networking` (attributes for IP networks)	optional	`ethn`: The interface that you’re defining. Oracle-provided images with release version 16.3.6 and later support eight vNICs. You can also create private images that support multiple vNICs. If the image you’ve specified supports eight vNICs, then you can specify up to eight network interfaces, from `eth0` to `eth7`. 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 `ethn` interface. To add an interface to an IP network, specify the following subparameters: `ipnetwork:` The name of the IP network that you want to add the instance to. `ip:` (Optional) If you want to associate a static private IP address with the instance, specify an available IP address from the IP address range of the specified `ipnetwork`. `address:` (Optional) The MAC address of the interface, in hexadecimal format, where each digit is separated by colon. For example, you can enter `01:02:03:04:ab:cd` as the MAC address but not `01-02-03-04-ab-cd`. `nat:` (Optional) A list of IP reservation that you want to associate with this interface, in the format: `"nat": ["network/v1/ipreservation:IP_reservation_name"]`. Here IP_reservation_name is the three-part name of the IP reservation in the `/Compute-identity_domain/user/object_name` format. `vnic:` (Optional) The three-part name of the vNIC in the `/Compute-identity_domain/user/object_name` format. `vnicsets:` (Optional) A list of the three-part names of the vNICsets that you want to add this interface to. `is_default_gateway:` (Optional) If you want to specify the interface to be used as the default gateway for all traffic, set this to `true`. The default is `false`. If the instance has an interface on the shared network, that interface is always used as the default gateway. `dns:` (Optional) A list of the DNS A record names for the instance. `name_servers:` (Optional) A list of the name servers that should be sent through DHCP as option 6. You can specify a maximum of eight name server IP addresses per interface. `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. For more information about each of these subparameters, see Subparameters for a Network Interface on an IP Network.
`relationships`	optional	You can also define relationships to indicate that you want the specified instances to be created on the same or different physical server. Relationship: `same_node` The `same_node` relationship indicates that you want the specified instances to be created on the same physical server. This is useful if you want to ensure low latency across instances. Example: to ensure that `instance1` is created on the same physical server. `"relationships": [ { "type": "same_node", "instances": [ "instance:/Compute-acme/jack.jones@example.com/instance1"] } ]` Relationship: `different_node` The `different_node` relationship indicates that you do not want the specified instances to be created on the same physical server. This is useful if you want to isolate instances for security or redundancy. Example: to ensure that `instance1` is not created on the same physical server. `"relationships": [ { "type": "different_node", "instances": [ "instance:/Compute-acme/jack.jones@example.com/instance1"] } ]`
`sshkeys`	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 `/Compute-identity_domain/user/object_name` format. 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`. Oracle-provided images include a script that runs automatically when the instance starts, retrieves the keys, and adds them to the `authorized_keys` file of the `opc` user. In images that you build, you can write and include a script that runs automatically when the instance starts, retrieves the SSH public keys, and adds the keys to the `authorized_keys` file of the appropriate users.

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_name format. 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/default security 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, where ipreservation_name is the three-part name of an existing IP reservation in the /Compute-identity_domain/user/object_name format.
If nat is 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 is e1000.
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. If name_servers are 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. If search_domains are 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_name format.

⁭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 selected IP 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 enter 01:02:03:04:ab:cd as the MAC address but not 01-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. Specify network/v1/ipreservation:ipreservation_name, where ipreservation_name is the three-part name of an existing IP reservation in the /Compute-identity_domain/user/object_name format.

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_name format.

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 to true. The default is false. 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. If name_servers are 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.1 and 192.168.12.2 will 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. If search_domains are 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.com and us.example1.com will be pushed to the instance through DHCP.

Orchestration v2 Attributes for `IpAddressAssociation`

The following sample JSON shows the key attributes of the IpAddressAssociation 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`ipAddressReservation`	optional	The name of the IP reservation that you want to associate with an instance.
`vnic`	optional	The name of the vNIC that you want to associate the IP reservation with.
`description`	optional	Description of the IP association.
`tags`	optional	Strings that you can use to tag the IP association.

Orchestration v2 Attributes for `IpAddressPrefixSet`

The following sample JSON shows the key attributes of the 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`ipAddressPrefixes`	optional	Set of IPv4 addresses in CIDR address prefix format.
`description`	optional	Description of the IP address prefix set.
`tags`	optional	Strings that you can use to tag the IP address prefix set.

Orchestration v2 Attributes for `IpAddressReservation`

The following sample JSON shows the key attributes of the IpAddressReservation 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`ipAddressPool`	required	The IP address pool from which you want to reserve an IP address. Enter one of the following: `/oracle/public/public-ippool`: When you attach an IP address from this pool to an instance, you enable access between the public Internet and the instance. `/oracle/public/cloud-ippool`: When you attach an IP address from this pool to an instance, the instance can communicate privately (that is, without traffic going over the public Internet) with other Oracle Cloud services, such as the REST endpoint of an Oracle Cloud Infrastructure Object Storage Classic account in the same region.
`description`	optional	Description of the IP reservation.
`tags`	optional	Strings that you can use to tag the IP reservation.

Orchestration v2 Attributes for `IpNetwork`

The following sample JSON shows the attributes of the 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`ipAddressPrefix`	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.
`ipNetworkExchange`	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.
`description`	optional	Description of the IP network.
`tags`	optional	Strings that you can use to tag the IP network.

Orchestration v2 Attributes for `IpNetworkExchange`

The following sample JSON shows the required attribute of the 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

name

required

The three-part name of the object (/Compute-identity_domain/user/object).

Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive.

description

optional

Description of the IP network exchange.

tags

optional

Strings that you can use to tag the IP network exchange.

Orchestration v2 Attributes for `IPReservation`

The following sample JSON shows the key attributes of the IPReservation 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
`parentpool`	required	Specify `/oracle/public/ippool`
`permanent`	required	Set to `True`
`account`	optional	Specify `/Compute-identity_domain/default`
`name`	optional	The three-part name of the object (`/Compute-identity_domain/user/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 Attributes for `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
`account`	required	The two-part name of the account (`/Compute-identity_domain/cloud_storage`) that contains the credentials and access details of the associated Oracle Cloud Infrastructure Object Storage Classic instance.
`container`	required	The name of the container that you want to create. Container names must: Contain only UTF-8 characters Be a maximum of 256 bytes Avoid using a slash (/) character because this character acts as a delimiter between the container name and the object name Ensure that a container of the same name doesn’t already exist.
`delete_remote`	required	When set to `true`, deletes the Oracle Cloud Infrastructure Object Storage Classic container along with all the objects in the container when you delete the `integration/osscontainer` object created by this orchestration. When set to `false`, only the `integrations/osscontainer` object created by this orchestration is deleted. The container in Oracle Cloud Infrastructure Object Storage Classic remains intact, along with all objects in the container.
`name`	optional	The three-part name of the `integrations/osscontainer` object created by this orchestration. This name is in the format `/Compute-identity_domain/user/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 v2 Attributes for `Restore`

The following sample JSON shows the required attributes of the Restore 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/jack.jones@example.com/RESTORE-A",
       "backupName": "{{My Backup:name}}",
       "volumeUri": "http://api-z999.compute.us0.oraclecloud.com/storage/volume/Compute-acme/jack.jones@example.com/restored-example-volume",
       "description": null
}

Parameter	Required or Optional	Description
`backupName`	required	The multi-part name of the backup that you want to restore. The backup must be in the completed state.
`volumeUri`	required	The URI of the storage volume that should be created when the backup is restored. Ensure that another volume with the same URI does not exist.
`name`	optional	The three-part name of the object (`/Compute-identity_domain/user/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.
`description`	optional	Description of the restored storage volume.

Orchestration v2 Attributes for `Route`

The following sample JSON shows the required attributes of the 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`ipAddressPrefix`	required	The IP address prefix, in CIDR format, of the destination network that you want to specify the route to.
`nextHopVnicSet`	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.
`adminDistance`	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.
`description`	optional	Description of the route.
`tags`	optional	Strings that you can use to tag the route.

Orchestration v2 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`protocol`	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 (`http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml`). For example, you can specify either `tcp` or the number 6. The following text representations are allowed: `tcp`, `udp`, `icmp`, `igmp`, `ipip`, `rdp`, `esp`, `ah`, `gre`, `icmpv6`, `ospf`, `pim`, `sctp`, `mplsip`, `all`. To specify all protocols, set this to `all`.
`dport`	optional	The TCP or UDP destination port number. You can also specify a port range, such as 5900-5999 for TCP. If you specify `tcp` or `udp` as the protocol, then the `dport` parameter is required; otherwise, it is optional. 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.
`icmptype`	optional	The ICMP type. This parameter is relevant only if you specify `icmp` as the protocol. You can specify one of the following values: `echo` `reply` `ttl` `traceroute` `unreachable` If you specify `icmp` as the protocol and don't specify `icmptype` or `icmpcode`, then all ICMP packets are matched.
`icmpcode`	optional	The ICMP code. This parameter is relevant only if you specify `icmp` as the protocol. You can specify one of the following values: `network` `host` `protocol` `port` `df` `admin` If you specify `icmp` as the protocol and don't specify `icmptype` or `icmpcode`, then all ICMP packets are matched.
`description`	optional	A description of the security application.

Orchestration v2 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

name

required

The three-part name of the object (/Compute-identity_domain/user/object).

Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive.

secipentries

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:

“203.0.113.0/30”

“203.0.113.1”, “203.0.113.2”

description

optional

A description of the security IP list.

Orchestration v2 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`policy`	optional	The policy for inbound traffic to the security list. You can specify one of the following values: `deny` (default): Packets are dropped. No response is sent. `reject`: Packets are dropped, but a response is sent. `permit`: Packets are allowed. This policy effectively turns off the firewall for all instances in this security list.
`outbound_cidr_policy`	optional	The policy for outbound traffic from the security list. You can specify one of the following values: `deny`: Packets are dropped. No response is sent. `reject`: Packets are dropped, but a response is sent. `permit` (default): Packets are allowed.
`description`	optional	A description of the security list.

Orchestration v2 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`src_list`	required	The three-part name (`/Compute-identity_domain/user/object_name`) of the source security list or security IP list. You must use the prefix `seclist:` or `seciplist:` to identify the list type.
`dst_list`	required	The three-part name (`/Compute-identity_domain/user/object_name`) of the destination security list or security IP list. You must use the prefix `seclist:` or `seciplist:` to identify the list type. Note: You can specify a security IP list as the destination in a secrule, provided `src_list` is a security list that has DENY as its outbound policy.
`application`	required	The three-part name of the security application: (`/Compute-identity_domain/user/object_name`) for user-defined security applications and `/oracle/public/object_name` for predefined security applications.
`action`	required	Set this parameter to `PERMIT`.
`description`	optional	A description of the security rule.
`disabled`	optional	Indicates whether the security rule is enabled (set to `True`) or disabled (`False`). The default setting is `False`.

Orchestration v2 Attributes for `SecurityProtocol`

The following sample JSON shows the key attributes of the SecurityProtocol 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`ipProtocol`	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 (`http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml`). The following text representations are allowed: `tcp` `udp` `icmp` `igmp` `ipip` `rdp` `esp` `ah` `gre` `icmpv6` `ospf` `pim` `sctp` `mplsip` `all` Any number from 0 to 254 If no protocol is specified, all protocols are allowed.
`srcPortSet`	optional	List of port numbers or port range strings to match the packet's source port. For `tcp,` `sctp,` and `udp,` each port is a source transport port, between 0 and 65535, inclusive. For `icmp`, each port is an ICMP type, between 0 and 255, inclusive. If no source ports are specified, all source ports or ICMP types are allowed.
`dstPortSet`	optional	List of port numbers or port range strings to match the packet's destination port. For `tcp,` `sctp,` and `udp,` each port is a destination transport port, between 0 and 65535, inclusive. For `icmp`, each port is an ICMP code, between 0 and 255, inclusive. If no destination ports are specified, all destination ports or ICMP codes are allowed.
`description`	optional	Description of the security protocol.
`tags`	optional	Strings that you can use to tag the security protocol.

Orchestration v2 Attributes for `SecurityRule`

The following sample JSON shows the key attributes of the SecurityRule 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`flowDirection`	required	The direction of flow of traffic that this rule applies to. Allowed values are `ingress` or `egress`.
`srcVnicSet`	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.
`dstVnicSet`	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.
`srcIpAddressPrefixSets`	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.
`dstIpAddressPrefixSets`	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.
`secProtocols`	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.
`enabledFlag`	optional	Allows the security rule to be enabled or disabled. This parameter is set to `true` by default. Specify `false` to disable the security rule.
`acl`	optional	The name of the access control list (ACL) that contains this security rule.
`description`	optional	Description of the security rule.
`tags`	optional	Strings that you can use to tag the security rule.

Orchestration v2 Attributes for `SSHKey`

The following sample JSON shows the required attributes of the SSHKey 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/key1"
          "enabled": false,
          "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDzU21CEj6JsqIMQAYwNbmZ5P2BVxA...",
 }

Parameter Required or Optional Description

name

required

The three-part name of the object (/Compute-identity_domain/user/object).

Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive.

key

required

The SSH public key value.

enabled

optional

Indicates whether the key must be enabled or disabled. SSH keys are enabled by default. To explicitly enable the key, specify true. To disable a key, specify false. Disabled keys can’t be associated with instances.

Orchestration v2 Attributes for `StorageAttachment`

The following sample JSON shows the key attributes of the StorageAttachment 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.

{
    "storage_volume_name": "{{My_Storage_Volume:name}}",
    "instance_name": "{{My_Instance:name}}",
    "index": 1
 }

Parameter	Required or Optional	Description
`name`	optional	The three-part name of the object (`/Compute-identity_domain/user/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.
`instance_name`	required	The name of the instance to which you want to attach the storage volume. You can specify the object name as a reference to an object. For example, for an instance with the label `my_instance`, you can specify its name as follows: `"instance_name": "{{my_instance:name}}",`
`storage_volume_name`	required	The name of the storage volume that you want to attach to the instance. You can specify the object name as a reference to an object. For example, for a storage volume with the label `my_volume`, you can specify its name as follows: `"storage_volume_name": "{{my_volume:name}}",`
`index`	required	The index number for the volume. The allowed range is 1 to 10. If you want to use a storage volume as the boot disk for an instance, you must specify the index number for that volume as `1`. The index determines the device name by which the volume is exposed to the instance. Index 0 is allocated to a nonpersistent boot disk, `/dev/xvda.` An attachment with index 1 is exposed to the instance as `/dev/xvdb`, an attachment with index 2 is exposed as `/dev/xvdc`, and so on.

Orchestration v2 Attributes for `StorageSnapshot`

The following sample JSON shows the key attributes of the StorageSnapshot 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.

{
           "volume": "/Compute-acme/joe/vol1",
           "name": "/Compute-acme/joe/vol1-snapshot"
           "description": "Remote snapshot of vol1"
}

Parameter	Required or Optional	Description
`volume`	required	The three-part name `/Compute-identity_domain/user/object_name` of the storage volume that you want to create a snapshot of.
`name`	optional	The three-part name of the object (`/Compute-identity_domain/user/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.
`property`	optional	Specify `/oracle/private/storage/snapshot/collocated` to create a colocated snapshot. Colocated snapshots are stored in the same physical location as the original storage volume. Colocated snapshots and volumes from colocated snapshots can be created very quickly. If you don't specify a value, a remote snapshot is created. Remote snapshots aren't stored in the same location as the original storage volume. Instead, they are stored in the associated Oracle Cloud Infrastructure Object Storage Classic instance. Creating a remote snapshot and restoring a storage volume from a remote snapshot can take a longer time than for colocated snapshots, as data is written to and from the Oracle Cloud Infrastructure Object Storage Classic instance.
`platform`	optional	Specify the operating system platform for a bootable storage volume, such as Linux or Windows.
`tags`	optional	Strings that you can use to tag the storage snapshot.
`description`	optional	Description of the storage snapshot.

Orchestration v2 Attributes for `StorageVolume`

The following sample JSON shows the key attributes of the StorageVolume 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/object`). Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive.
`size`	required	The size of this storage volume. Use one of the following abbreviations for the unit of measurement: `B` or `b` for bytes `K` or `k` for kilobytes `M` or `m` for megabytes `G` or `g` for gigabytes `T` or `t` for terabytes For example, to create a volume of size 10 gigabytes, you can specify `10G`, or `10240M`, or `10485760K`, and so on. The allowed range is from 1 GB to 2 TB, in increments of 1 GB.
`properties`	required	Based on your latency and IOPS requirements, select one of the following storage properties: For standard latency and throughput, specify `/oracle/public/storage/default`. For high latency and throughput, specify `/oracle/public/storage/latency`. For the highest latency and throughput, specify `/oracle/public/storage/ssd/gp1`.
`description`	optional	The description of the storage volume.
`bootable`	optional	Indicates whether the storage volume can be used as the boot disk for an instance. The default value is `False` (not a bootable volume). If you set the value to `True`, then you must specify values for the following parameters: `imagelist` The machine image that you want to extract on to the storage volume that you’re creating. `imagelist_entry` (Optional) The version of the image list entry that you want to extract. The default value is 1.
`tags`	optional	Strings that you can use to tag the storage volume.

Orchestration v2 Attributes for `VirtualNicSet`

The following sample JSON shows the key attributes of the VirtualNicSet 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
`name`	required	The three-part name of the object (`/Compute-identity_domain/user/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.
`vnics`	optional	The list of vNICs associated with this vNICset.
`appliedAcls`	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.
`description`	optional	Description of the route.
`tags`	optional	Strings that you can use to tag the IP network exchange.

Orchestration v2 Life Cycle

When you activate an orchestration, all the objects defined in it are created and the orchestration moves to the active state. When you suspend an orchestration, the nonpersistent objects defined in it are deleted and the orchestration moves to the suspended state. When you deactivate an orchestration, all the objects defined in it are deleted and the orchestration moves to the inactive state.

activating

The orchestration is starting.

Compute Classic is provisioning the objects defined in the orchestration. The time to complete this action varies depending on the number and type of objects that are being provisioned.

active

The orchestration is running.

Compute Classic successfully provisioned all the objects in the orchestration. For example, an orchestration displays that it is in the active state when all its instances have been created, storage volumes are online, and so on.

suspending

The orchestration is being suspended.

All the nonpersistent (persistent: false) objects are being deleted.
All persistent (persistent: true) objects are being created if they were not already created.

suspended

All the nonpersistent objects are deleted.
All persistent objects are created if they were not already created.

terminating

The orchestration is being terminated.

Compute Classic is deleting all the objects defined in the orchestration.

inactive

The orchestration is inactive.

Compute Classic successfully deleted all the objects defined in the orchestration.

terminal_error

The orchestration reached an error state from which it can’t recover. You must identify and address the issue.

The following are a few examples of the possible issues:

Errors in the template of your orchestration are preventing the orchestration from being created.
You don’t have the necessary permissions to provision a specified object.

transient_error

The orchestration is automatically recovering from a failure. You don’t need to intervene.

For example, if an instance crashes and Compute Classice is automatically re-creating the instance, a transient_error is displayed.

Managing Orchestrations v2

Topics

Uploading an Orchestration v2

To use an orchestration to control the provisioning and life cycle of objects 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_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.
You must have already created the orchestration file that you want to upload. See Building Your First Orchestration v2
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

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.
Click Upload Orchestration and select the orchestration file that you want to upload.

The orchestration is uploaded. If you upload an orchestrations v2 file with the desired_state specified as active, the orchestration is started automatically and the objects defined in it are created.

To upload an orchestration using the CLI, use the opc compute orchestration-v2 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 orchestrations v2 using the API, use the POST /platform/v1/orchestration/ method. See REST API for Oracle Cloud Infrastructure Compute Classic.

Starting an Orchestration v2

When you start an orchestration, the objects defined in it are created, and when you stop an orchestration, those objects are deleted.

If your orchestration has the desired_state defined as active, it starts immediately when you upload the orchestration. If the desired state specified isn’t active, then you must explicitly start the orchestration. You can also start an orchestration if you had previously suspended or stopped it.

Note:

If you’re about to start an orchestration that creates a large number of storage volumes or instances, 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_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.
You must have uploaded the orchestration to Compute Classic. See Uploading an Orchestration v2.

Note:

Ensure that each object defined in an orchestration has a unique name, and that objects of the same type with the same name don’t already exist. If any of the objects defined in an orchestration already exists, when the orchestration attempts to start, it reports an error.

Procedure

Sign in to the Compute Classic console.
(Optional) If your domain spans multiple sites, then check that the site you’ve selected has sufficient capacity to create the required resources. Click Site near the top of the page to view the aggregate resource usage by all tenants on the currently selected site. If resource usage on the selected site is close to maximum, pick another site.

If you’re using the REST API to create resources, note the API end point of the site that you want to use.
Click the Orchestrations tab.
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 Transient Error or Terminal Error. An orchestration might transition from the Transient Error to the Ready state when it completes creating all the specified objects.

If the status of your orchestration shows Terminal Error, then you must stop the orchestration, identify and fix the issues in the orchestration JSON file, and then start the orchestration again.

To start an orchestration using the CLI, use the opc compute orchestration-v2 update 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 orchestrations v2 using the API, use the PUT /platform/v1/orchestration/orchestrationName method with the query argument desired_state=active. 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 all the objects, stop the orchestration. Alternatively, to delete only nonpersistent objects, suspend the orchestration. See Terminating an Orchestration v2 or Suspending an Orchestration v2.

Monitoring Orchestrations v2

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.

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.
All orchestrations are displayed, with information about their description and status.

Tip:

You can filter the list of orchestrations according to their category or status. To view orchestrations with a specific status (such as ready, error, or stopped), click the Show menu and select the appropriate filter. To view orchestrations of a specific category (such as all or personal), click the Category menu and select the appropriate filter.
Go to the orchestration that you want to view and, from the menu, select View.
The orchestration details page displays the orchestration JSON along with other information about objects created by the orchestration, such as instances, IP networks, interfaces on IP networks, storage volumes, and so on.

To get a list of your orchestrations using the CLI, use the opc compute orchestration-v2 list command and to view the details of an orchestration, use the opc compute rchestration-v2 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 v2 using the API, use the GET /platform/v1/orchestration/container/ method and to view the details of an orchestration, use the GET /platform/v1/orchestration/name/ method. See REST API for Oracle Cloud Infrastructure Compute Classic.

For information about the status of an orchestration, see Orchestration v2 Life Cycle.

To start an orchestration, see Starting an Orchestration v2 and to stop an orchestration, see Terminating an Orchestration v2.

Suspending an Orchestration v2

When you suspend an orchestration, all nonpersistent resources that were provisioned by that orchestration are deleted. Persistent objects aren’t deleted.

Prerequisites

The orchestration that you want to suspend must be in the Ready state or Error state. You can’t suspend orchestration in a transient state such as Starting or Stopping.
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.

Procedure

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 suspend. From the menu, select Suspend.
The status of the orchestration changes to Suspending.

After all nonpersistent objects have been deleted, the status of the orchestration changes to Suspended. You can view the orchestration, stop it, delete it, or start it again.

To suspend an orchestration using the CLI, use the opc compute orchestration-v2 update name [--desired-state suspend] 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 only the nonpersistent objects in orchestrations v2 using the API, use the PUT /platform/v1/orchestration/orchestrationName method with the query argument desired_state=suspend. For more information, see REST API for Oracle Cloud Infrastructure Compute Classic.

Terminating an Orchestration v2

When you terminate or stop an orchestration, all the instances and other resources that were provisioned by that orchestration are deleted.

Caution:

When you terminate an orchestration, all 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.

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 terminate. From the menu, select Terminate.
The status of the orchestration changes to Stopping.

After all objects have been deleted, the status of the orchestration changes to Stopped. You can start the orchestration again, or if you don’t require the orchestration any more, you can delete it.

To terminate an orchestration using the CLI, use the opc compute orchestration-v2 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 all the objects in orchestrations v2 using the API, use the PUT /platform/v1/orchestration/orchestrationName method with the query argument desired_state=inactive. For more information, see REST API for Oracle Cloud Infrastructure Compute Classic.

If you no longer need an orchestration, you can delete it. See Deleting an Orchestration v2.

Downloading an Orchestration v2

You can download the orchestration file to your local host, edit it, and upload a modified orchestration file as a new orchestration.

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 v2.

To download an orchestration using the CLI, use the opc compute orchestration-v2 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 orchestrations v2 using the API, use the GET /platform/v1/orchestration/name/ method. See REST API for Oracle Cloud Infrastructure Compute Classic.

Workflows for Updating Orchestrations v2

You can update an orchestration that is in the Active, Suspended, Stopped, or Error state.

When an orchestration is stopped, all objects created by that orchestration are deleted, so all the attributes of an object can be updated. When you start the orchestration, the objects are created with the updated attributes.

When an orchestration is suspended, nonpersistent objects have the status Inactive and all attributes of those objects can be updated. Those objects are created with the updated attributes when you start the orchestration or when you change the object’s properties from nonpersistent to persistent.

When an orchestration is suspended, persistent objects aren’t deleted. Those objects have the status Active and some attributes of those objects can’t be updated. For example, you can’t update the name of a storage volume while the storage volume is online. Updates to attributes of persistent objects take effect immediately. Attempting to modify attributes that can’t be modified while an object has the status Active might cause the orchestration to go into a terminal error state, indicating that the update failed.

The following table displays the situations in which some or all of an object’s attributes can be modified and the actions required for the updates to be effective.

Orchestration Status	Object Persistence	Object Status	Modifiable Attributes of an Object	Updates Effective
Ready	Persistent	Active	Some	Immediately.
Ready	Nonpersistent	Active	Some	Immediately.
Suspended	Persistent	Active	Some	Immediately.
Suspended	Nonpersistent	Inactive	All	When orchestration is started or object is updated to be persistent.
Stopped	Persistent	Inactive	All	When orchestration is started.
Stopped	Nonpersistent	Inactive	All	When orchestration is started.

Topics

Workflow for Changing the Persistence of an Object

You can specify persistence for each object in an orchestration. When you suspend an orchestration, nonpersistent objects are deleted, but persistent objects are retained. For most object types, certain attributes of an object can’t be modified while the object exists. This means that, if you want to update those attributes of an object, after suspending the orchestration you must also ensure that the object is nonpersistent and its current status is Inactive.

Similarly, if you’ve suspended an orchestration and added or updated an object in that orchestration, then to start that object without changing the status of the orchestration, you can specify the object to be persistent. The object is created right away while the orchestration remains in the Suspended state.

Caution:

When you specify an object as nonpersistent, if the orchestration is in the Suspended state, the object is deleted immediately.

Select the name of the required orchestration to open the orchestrations details page.
On the orchestrations details page, go to the object for which you want to specify persistence. From the menu, select Properties.
In the Object Properties dialog box, to set the object as persistent, select the Persistent check box. To set the object as nonpersistent, deselect the Persistent check box. Then click Update.

If the orchestration is in the Suspended state, the change in object persistence is effective immediately. If you updated the object to be nonpersistent, it is deleted and the orchestration details page shows the object’s status as Inactive. If you updated the object to be persistent, it is created and the orchestration details page shows its status as Active.

If the orchestration is in the Stopped state, the change in object persistence is updated in the orchestration and it is effective when the orchestration is started.

Workflow for Adding an Instance

To add an instance to an existing orchestration:

Select the name of the required orchestration to open the orchestrations details page.
On the orchestrations details page, go to the Instance section and click Add. An instance with default configuration is added to the orchestration with the status Inactive.
(Optional) To view or modify the instance configuration, from the menu, select Update. The instance details page displays the instance configuration. You can modify the configuration as required.

Alternatively, you can view and modify the instance configuration JSON by selecting Edit JSON.
To create the instance, start the orchestration, or if the orchestration is in the Suspended state, set the instance to be persistent.

Workflow for Adding an Object to an Orchestration

To add an object to an existing orchestration:

Select the name of the required orchestration to open the orchestrations details page.
On the orchestrations details page, go to the object type that you want to add and click Add.
A dialog box is displayed. Enter the required information to create the object. The object is added to the orchestration.
To create the object, start the orchestration, or if the orchestration is in the Suspended state, set the object to be persistent.

Workflow for Updating a Nonpersistent Object

You can specify persistence for each object in an orchestration. All nonpersistent objects are deleted when you either suspend or stop an orchestration. To update a nonpersistent object:

Select the name of the required orchestration to open the orchestrations details page.
On the orchestration details page, go to the object that you want to update and from the menu, select Update.

Alternatively, you can view and modify the JSON by selecting Edit JSON.
A dialog box is displayed. Modify the object attributes as required. The orchestration is updated.
To create the object with the updated attributes, start the orchestration, or if the orchestration is in the Suspended state, set the object to be persistent.

Workflow for Updating a Persistent Object

You can specify persistence for each object in an orchestration. While persistent objects are deleted when you stop an orchestration, when you suspend an orchestration, persistent objects aren’t deleted. The orchestration details page shows the status for these object as Active. Although you can update almost all the attributes of an object while it has the status Active, the name of the object can’t be updated.

To update a persistent object:

Select the name of the required orchestration to open the orchestrations details page.
If you want to change the name of the object, then modify the object to be nonpersistent:
1. On the orchestration details page, go to the object that you want to update and from the menu, select Properties.
2. In the Object Properties dialog box, to set the object as nonpersistent, deselect the Persistent check box. Then click Update.
  
  Caution:
  
  When you specify an object as nonpersistent, if the orchestration is in the Suspended state, the object is deleted immediately.
On the orchestration details page, go to the object that you want to update and from the menu, select Update.

Alternatively, you can view and modify the JSON by selecting Edit JSON.
A dialog box is displayed. Modify the object attributes as required.
To create the object with the updated attributes, start the orchestration, or if the orchestration is in the Suspended state, set the object to be persistent.

Workflow for Resizing an Instance

You can’t resize a running instance. Before you resize an instance, you must ensure that the instance is deleted. You can re-create the instance later, after it has been resized. To resize an instance:

Select the name of the required orchestration to open the orchestrations details page.
If the instance status is displayed as Active, then:
1. On the orchestration details page, go to the instance that you want to resize and from the menu, select Properties.
2. In the Object Properties dialog box, deselect the Persistent check box. Then click Update. The status of the instance changes from Active to Inactive.
On the orchestration details page, go to the instance that you want to update and from the menu, select Update.
In the Resize an Instance dialog box, select the required shape. Ensure that the shape you select is bigger than the current shape and click Resize. The orchestration is updated with the selected shape.
To create the instance with the updated shape, start the orchestration, or if the orchestration is in the Suspended state, update the instance to be persistent.

Workflow for Updating an Instance

When an instance is running, you can modify some attributes of the instance. For example, you can add storage volumes to the instance and you can add the instance to security lists in the shared network. However, many other instance attributes can be modified only when the instance is deleted. To update an instance:

Select the name of the required orchestration to open the orchestrations details page.
If the orchestration is suspended (not stopped), and if the updates that you want to make require the instance to be deleted, then ensure that the instance is nonpersistent:
1. On the orchestration details page, go to the instance that you want to update and from the menu, select Properties.
2. In the Object Properties dialog box, ensure that the Persistent check box isn’t selected. If it is, then deselect it, and then click Update. The status of the instance changes from Active to Inactive.
On the orchestration details page, go to the instance that you want to update and from the menu, select Update.

Alternatively, you can view and modify the instance configuration JSON by selecting Edit JSON.
Make the required changes to the instance configuration. The orchestration is updated with your changes.
To create the instance with the updated attributes, start the orchestration, or if the orchestration is in the Suspended state, set the instance to be persistent.

Updating an Orchestration v2

The web console allows you to update each object of an orchestration separately. You can add or remove objects, modify general attributes of objects such as persistence and dependencies, or update the object-specific attributes.

You can update an orchestration in either of the following ways:

By downloading the orchestration file to your local host and updating it using a text editor.

You’ll have to delete the existing orchestration before you can upload the modified orchestration. Alternatively, you can upload the modified orchestration with a new name. See Downloading an Orchestration v2, Deleting an Orchestration v2, and Uploading an Orchestration v2
Directly in the web console, by selecting the Update option, as described in the following procedure.

Prerequisites

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.

Note:

The following table displays the situations in which some or all of an object’s attributes can be modified and the actions required for the updates to be effective.

Orchestration Status	Object Persistence	Object Status	Modifiable Attributes of an Object	Updates Effective
Ready	Persistent	Active	Some	Immediately.
Ready	Nonpersistent	Active	Some	Immediately.
Suspended	Persistent	Active	Some	Immediately.
Suspended	Nonpersistent	Inactive	All	When orchestration is started or object is updated to be persistent.
Stopped	Persistent	Inactive	All	When orchestration is started.
Stopped	Nonpersistent	Inactive	All	When orchestration is started.

Procedure

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.
Go to the orchestration that you want to update. From the menu, select Update.
On the orchestration details page, go to the object that you want to update.
- To add an instance, in the Instance section, click Add. An instance with default configuration is added to the orchestration with the status Inactive. When you start the orchestration, the instance is created.
- To add any other object type, go to the appropriate section and click Add. For example, to create an access control list (ACL), click Add in the ACL section. The Create dialog box appears. Enter the required information and click Create. The object is added to the orchestration with the status Inactive. When you start the orchestration, the object is created.
- To update the general properties of an object, from the menu, select Properties. The Object Properties dialog box appears. You can update the description, persistence, and dependencies of the object.
- To update the general properties or attributes of an object by editing the JSON, from the menu, select Edit JSON. The Edit Orchestration Object JSON dialog box appears, with the JSON for the general properties as well as the object-specific attributes. You can update the JSON for the specified object as required and then click Update. The changes are saved in the orchestration.
- To change the shape of an instance, ensure that the status of the instance is Inactive. From the menu, select Resize Instance. In the Resize an Instance dialog box, select the shape you want to use and click Resize. The instance configuration is updated in the orchestration.
- To update attributes of an instance, go to the appropriate instance and from the menu, select Update. The instance details page is displayed. You can update the instance attributes as required. When you’re done, click Back to Orchestration Details. The instance attributes are updated in the orchestration.
  
  Note:
  
  It is recommended that you ensure that an instance is nonpersistent before updating its attributes. Nonpersistent instances are deleted when the orchestration is suspended and all attributes can be modified. Persistent instances are still running when the orchestration is suspended and many attributes can’t be modified while the instance is running. Attempting to modify attributes that can’t be modified might cause the orchestration to go into an error state.
- To update attributes of any other object, from the menu, select Update. The Update dialog box appears. Update the information as required and click Update. The object attributes are updated in the orchestration.
- To remove an object from the orchestration, from the menu, select Delete. The Delete Orchestration Object dialog box appears. When you confirm the deletion, the object is removed from the orchestration.
When you’re done making changes to the objects in the orchestration, use the buttons at the top of the page to do the following:
- If the orchestration is in the Suspended state, you can start the orchestration to create all objects, or stop the orchestration to delete all persistent objects.
- If the orchestration is in the Stopped state, you can start the orchestration to create all objects.
Note:

If the changes you made cause the orchestration to go into an Error state, you can update the orchestration to undo your changes.

To update an orchestration using the API, download the orchestration, modify it, and then upload the modified JSON.

To download an orchestration using the CLI, use the opc compute orchestration-v2 get command. After editing an orchestration, to upload it using the CLI, use the opc compute orchestration-v2 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 orchestrations v2 using the API, use the GET /platform/v1/orchestration/orchestrationName/ method. After modifying an orchestration, to upload it using the API, use the PUT /platform/v1/orchestration/orchestrationName method. See REST API for Oracle Cloud Infrastructure Compute Classic.

Note:

When you use the API to update an orchestration, you don’t need to stop the orchestration to update it. However, you can update an orchestration only if the orchestration is not in a transient state (activating, suspending, or deactivating).

When you update an orchestration without stopping it, the orchestration attempts to update the objects that you’ve modified. Remember, however, that various attributes of any object are immutable and modifying those attributes isn’t permitted. For example, the name of an object, the bootable attribute of a storage volume, or the shape of a running instance are immutable. If you attempt to modify immutable attributes of any object, the update will fail and the orchestration will go into the terminal_error state. If this happens, you must identify and fix the issues and then update or activate the orchestration again.

When you stop an orchestration, all the objects created by the orchestration are deleted. You can then update any attribute of any object. The objects are created afresh when the updated orchestration starts.

Deleting an Orchestration v2

If you don’t need an orchestration 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. Orchestrations v2 can be deleted even when they are in a ready or error state. In such cases, any resources that have been created by the orchestration and haven’t been stopped or deleted yet, are deleted when you delete the orchestration.

Prerequisites

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.
The orchestration that you want to delete must be in the Ready, Suspended, Stopped, or Error state. You can’t delete an instance in a transient state such as Starting or Stopping.

Procedure

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 delete. From the menu, select Delete.

Note:

When you delete an orchestration that isn’t in the Stopped state, all existing resources created by the orchestration are deleted.

When all objects created by the orchestration have been deleted, the orchestration itself is deleted and it is no longer listed on the Orchestrations page.

To delete an orchestration using the CLI, use the opc compute orchestration-v2 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 orchestrations v2 using the API, use the DELETE /platform/v1/orchestration/orchestrationName method. See REST API for Oracle Cloud Infrastructure Compute Classic.

Managing Orchestrations v2 Using the REST API

You can create and manage your orchestrations as well as objects within an orchestration using the REST API.

Use the following APIs to upload and manage orchestrations. See Orchestration v2 in REST API for Oracle Cloud Infrastructure Compute Classic.

To upload an orchestration, use the POST /platform/v1/orchestration/ method.

Note that if you upload an orchestration with the desired_state attribute set to active, the orchestration is activated automatically and all objects are created.
To view the details of all of the orchestrations in a container, use the GET /platform/v1/orchestration/container/ method.
To view the details of an orchestration, use the GET /platform/v1/orchestration/orchestrationName method.
To start an orchestration, use the PUT /platform/v1/orchestration/orchestrationName?desired_state=active method.
To update an orchestration, use the PUT /platform/v1/orchestration/orchestrationName method.

You can update an orchestration only if the orchestration is not in a transient state (activating, suspending, or deactivating).

Note:

When you update an orchestration, the orchestration attempts to update the objects that you’ve modified without deleting the object or stopping the orchestration. Remember, however, that various attributes of any object are immutable and modifying those attributes isn’t permitted. For example, the name of an object, the bootable attribute of a storage volume, or the shape of a running instance are immutable. If you attempt to modify immutable attributes of any object, the update will fail and the orchestration will go into the terminal_error state. If this happens, you must identify and fix the issues and then update or activate the orchestration again.
To delete all of the nonpersistent objects defined in the orchestration, use the PUT /platform/v1/orchestration/orchestrationName?desired_state=suspend method.

When you suspend an active orchestration, only the nonpersistent objects are deleted; the persistent objects are not deleted.
To delete all the objects in an orchestration, use the PUT /platform/v1/orchestration/orchestrationName?desired_state=inactive method.

Managing Objects in an Orchestration

Use the following APIs to manage the objects in orchestrations. See Orchestration Objects in REST API for Oracle Cloud Infrastructure Compute Classic.

To add an object to an orchestration, use the POST /platform/v1/object/ method.

In the JSON file, specify the orchestration to which you want to add the object.
To update an object in an orchestration, use the PUT /platform/v1/object/orchestrationName/objectName method.

Note:

If you want to modify the attributes of an instance, remember that some attributes can’t be updated while the instance is running. To modify these attributes, update the instance with the desired_state specified as shutdown to stop the instance. Then change the attributes as required and update the instance with the desired_state specified as running.

Before you update an object, note the following:
- In the JSON file, specify the label and the version of the object.
- You can’t update objects when the orchestration is in a transient state, such as activating, suspending, or deactivating.
- You can’t update the type of an object.
- To update multiple objects in a single operation, update the orchestration.
To view the details of an object, use the GET /platform/v1/object/orchestrationName/objectName method.

To delete an object from an orchestration, use the DELETE /platform/v1/object/orchestrationName/objectName method.

If the object currently exists, specify the query argument terminate=True to delete the object and then remove it from the orchestration.

See the following table for the appropriate method of deleting an object from an orchestration.

Desired State of the Orchestration	Method
`active`	`DELETE /platform/v1/object/orchestrationName/objectName?terminate=True`
`suspended`	If object persistence is set to `true`: `DELETE /platform/v1/object/orchestrationName/objectName?terminate=True` If object persistence set to false or not specified: `DELETE /platform/v1/object/orchestrationName/objectName`
`inactive`	`DELETE /platform/v1/object/orchestrationName/objectName`

Managing Orchestrations v2 Using CLI

You can create and manage your orchestrations as well as objects within an orchestration using the CLI commands.

Use the following CLI commands to upload and manage orchestrations. See Orchestration v2 in CLI Reference for Oracle Cloud Infrastructure Compute Classic.

To upload an orchestration, use the opc compute orchestration-v2 add command.
To view the details of all of the orchestrations in a container, use the opc compute orchestration-v2 list command.
To view the details of all of the orchestrations and subcontainers in a container, use the opc compute orchestration-v2 discover command.
To view the details of an orchestration, use the opc compute orchestration-v2 get command.
To update an orchestration, use the opc compute orchestration-v2 update command.

You can update an orchestration only if the orchestration is not in a transient state (activating, suspending, or deactivating).

You can specify the desired_state as inactive to add the orchestration without starting or activating. You can activate the orchestration later by changing the desired_state to active.

Note:

When you update an orchestration, the orchestration attempts to update the objects that you’ve modified without deleting the object or stopping the orchestration. Remember, however, that various attributes of any object are immutable and modifying those attributes isn’t permitted. For example, the name of an object, the bootable attribute of a storage volume, or the shape of a running instance are immutable. If you attempt to modify immutable attributes of any object, the update will fail and the orchestration will go into the terminal_error state. If this happens, you must identify and fix the issues and then update or activate the orchestration again.
To delete all of the nonpersistent objects defined in the orchestration, use the opc compute orchestration-v2 update name [--desired-state suspend] command.

When you suspend an active orchestration, only the nonpersistent objects are deleted; the persistent objects are not deleted.
To delete all the objects in an orchestration, use the opc compute orchestration-v2 update name [--desired-state inactive] command.

Managing Objects in an Orchestration

Use the following CLI commands to manage the objects in orchestrations. See Orchestration Object in CLI Reference for Oracle Cloud Infrastructure Compute Classic.

To add an object to an orchestration, use the opc compute orchestration-object add [--request-body=FILE.json] command.

In the JSON file, specify the orchestration to which you want to add the object.
To update an object in an orchestration, use the opc compute orchestration-object update name [--request-body=FILE.json] command.

Note:

If you want to modify the attributes of an instance, remember that some attributes can’t be updated while the instance is running. To modify these attributes, update the instance with the desired_state specified as shutdown to stop the instance. Then change the attributes as required and update the instance with the desired_state specified as running.

Before you update an object, note the following:
- In the JSON file, specify the label and the version of the object.
- You can’t update objects when the orchestration is in a transient state, such as activating, suspending, or deactivating.
- You can’t update the type of an object.
- To update multiple objects in a single operation, update the orchestration.
To view the details of all objects in a container, use the opc compute orchestration-object list container [--orchestration orchestration-name] command.
To view the details of all objects and subcontainers in a container, use the opc compute orchestration-object discover container command.
To view the details of an object, use the opc compute orchestration-object get name command.
To delete an object from an orchestration, use the opc compute orchestration-object delete name [--terminate=true] command.

If the object currently exists, specify the query argument [--terminate=true] to delete the object and then remove it from the orchestration.

About Orchestrations v2

Comparing Orchestrations v1 and Orchestrations v2

Object References and Relationships

Object Persistence in Orchestrations v2

Object Types in Orchestrations v2

Orchestration v2 Templates and Samples

Workflow for Creating Instances Using Orchestrations v2

Building Your First Orchestration v2

Attributes in Orchestrations v2

Top-Level Orchestration v2 Attributes

General Attributes for Objects in Orchestrations v2

Orchestration v2 Attributes Specific to Each Object Type

Orchestration v2 Attributes for Acl

Orchestration v2 Attributes for Backup

Orchestration v2 Attributes for BackupConfiguration

Orchestration v2 Attributes for Instance

Orchestration v2 Attributes for IpAddressAssociation

Orchestration v2 Attributes for IpAddressPrefixSet

Orchestration v2 Attributes for IpAddressReservation

Orchestration v2 Attributes for IpNetwork

Orchestration v2 Attributes for IpNetworkExchange

Orchestration v2 Attributes for IPReservation

Orchestration Attributes for OSSContainer

Orchestration v2 Attributes for Restore

Orchestration v2 Attributes for Route

Orchestration v2 Attributes for SecApplication

Orchestration v2 Attributes for SecIPList

Orchestration v2 Attributes for SecList

Orchestration v2 Attributes for SecRule

Orchestration v2 Attributes for SecurityProtocol

Orchestration v2 Attributes for SecurityRule

Orchestration v2 Attributes for SSHKey

Orchestration v2 Attributes for StorageAttachment

Orchestration v2 Attributes for StorageSnapshot

Orchestration v2 Attributes for StorageVolume

Orchestration v2 Attributes for VirtualNicSet

Orchestration v2 Life Cycle

Managing Orchestrations v2

Uploading an Orchestration v2

Starting an Orchestration v2

Monitoring Orchestrations v2

Suspending an Orchestration v2

Terminating an Orchestration v2

Downloading an Orchestration v2

Workflows for Updating Orchestrations v2

Updating an Orchestration v2

Deleting an Orchestration v2

Managing Orchestrations v2 Using the REST API

Managing Orchestrations v2 Using CLI

Orchestration v2 Attributes for `Acl`

Orchestration v2 Attributes for `Backup`

Orchestration v2 Attributes for `BackupConfiguration`

Orchestration v2 Attributes for `Instance`

Orchestration v2 Attributes for `IpAddressAssociation`

Orchestration v2 Attributes for `IpAddressPrefixSet`

Orchestration v2 Attributes for `IpAddressReservation`

Orchestration v2 Attributes for `IpNetwork`

Orchestration v2 Attributes for `IpNetworkExchange`

Orchestration v2 Attributes for `IPReservation`

Orchestration Attributes for `OSSContainer`

Orchestration v2 Attributes for `Restore`

Orchestration v2 Attributes for `Route`

Orchestration v2 Attributes for `SecApplication`

Orchestration v2 Attributes for `SecIPList`

Orchestration v2 Attributes for `SecList`

Orchestration v2 Attributes for `SecRule`

Orchestration v2 Attributes for `SecurityProtocol`

Orchestration v2 Attributes for `SecurityRule`

Orchestration v2 Attributes for `SSHKey`

Orchestration v2 Attributes for `StorageAttachment`

Orchestration v2 Attributes for `StorageSnapshot`

Orchestration v2 Attributes for `StorageVolume`

Orchestration v2 Attributes for `VirtualNicSet`