1. CLI Reference for Oracle Cloud Infrastructure Compute Classic
  2. Command Line Reference
  3. Orchestration Object

25 Orchestration Object

This section describes the Compute Classic CLI commands you can use to add, delete, update, and view orchestration objects.

An orchestration object is an object in Compute Classic which is managed by orchestration v2. It 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. When you define an object in an orchestration, you can create dependencies with other objects by using references. See Object References and Relationships in Using Oracle Cloud Infrastructure Compute Classic.

Orchestrations are designed to handle up to 100 interdependent objects. Creating objects using other commands may compromise your orchestration.

Note:

You should always use your orchestrations to manage resources that you've created using orchestrations. For example, use the orchestration-object add command to add a security list to a running instance or to create a storage snapshot of an attached storage volume instead of using the sec-lists add or storage-snapshot add commands respectively. Don't, for example, use the web console, CLI commands, or REST API to delete an object that you created using an orchestration. This could cause your orchestration to either attempt to re-create the object and associated resources, or to go into an error state.

Also remember that you shouldn't try to use or manage resources created using orchestrations v1 by referencing them in orchestrations v2, or vice versa.

You can add objects to, remove objects from, or update objects in an orchestration by using the commands listed below.

Before running the CLI commands described in this section, make sure that you've installed the CLI client and set up the required environment variables as described in Preparing to Use the CLI.

Commands

orchestration-object add

Adds an object to the specified orchestration v2 in Compute Classic.

The action of the orchestration object you add is determined by the desired_state of the orchestration it is associated with.

  • Objects are created when the desired_state of the associated orchestration is set to active.

  • Objects are deleted when the desired_state of the associated orchestration is set to inactive.

  • Only non-persistent objects are deleted when the desired_state of the associated orchestration is set to suspend. Persistent objects are not deleted when the associated orchestration is suspended. 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 persistent objects are not already in the active state, they are created. If the orchestration is terminated, then all the objects are deleted. 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. For more information, see Object Persistence in Orchestrations v2 in Using Oracle Cloud Infrastructure Compute Classic.

To change the desired_state of an orchestration, run the orchestration-v2 update command.

You can determine the status of an object by viewing the value of its health parameter.

Required Role

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.

Syntax

opc compute orchestration-object add [--request-body=FILE.json]

For help with the parameters and options of this command, run the command with the -h option.

Example

opc -f json compute orchestration-object add --request-body=addObject.json

Example of addObject.json

The following shows an example of the content in the addObject.json file to create a security list with default attribute values. As persistent is set to true, a persistent security list is created. A persistent object is not deleted when the orchestration is suspended. /Compute-acme/jack.jones@example.com/seclist1 is the name of the persistent security list that is created, and /Compute-acme/jack.jones@example.com/myOrchestration/seclist1 is the name of the orchestration object that will track this security list. The state of the security list is determined by the desired_state of the associated orchestration, /Compute-acme/jack.jones@example.com/myOrchestration. 

{
  "type":"SecList",
  "orchestration": "/Compute-acme/jack.jones@example.com/myOrchestration",
  "name": "/Compute-acme/jack.jones@example.com/myOrchestration/seclist1",
  "label": "mySeclist1",
  "persistent": true,
  "template": {
   "name": "/Compute-acme/jack.jones@example.com/seclist1"
      },
  "description": "a persistent security list"
}

Sample Output

You can find the current status of the object by looking at the value of the health parameter in the output. As the desired_state of the associated orchestration is inactive, the security list object is also inactive. 

{
	"relationships": [],
	"account": "/Compute-acme/default",
	"time_updated": null,
	"description": "a persistent security list",
	"user": "/Compute-acme/jack.jones@example.com",
	"persistent": true,
	"uri": "https://api-z999.compute.us0.oraclecloud.com/platform/v1/object/Compute-acme/jack.jones@example.com/myOrchestration/seclist1",
	"template": {
		"name": "/Compute-acme/jack.jones@example.com/seclist1"
	},
	"label": "mySeclist1",
	"time_audited": null,
	"version": 1,
	"health": {
		"status": "inactive"
	},	
  "time_created": "2017-03-10T11:05:39Z",
	"orchestration": "/Compute-acme/jack.jones@example.com/myOrchestration",
	"type": "SecList",
	"name": "/Compute-acme/jack.jones@example.com/myOrchestration/seclist1"
}

orchestration-object list

Retrieves details of all the orchestration objects that are available and match the specified query criteria. To filter the search results, you can pass one or more names of orchestrations as query options. This retrieves only the names of the objects that belong to the specified orchestration. If you don't specify any query criteria, then details of all the orchestration objects in the container are displayed.

Required Role

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.

Syntax

opc compute orchestration-object list container [--orchestration orchestration-name]

For help with the parameters and options of this command, run the command with the -h option.

Example

opc -f json compute orchestration-object list /Compute-acme/jack.jones@example.comfirstOrchestration

Sample Output

{
  "result": [
     {
      "relationships": [
        
      ],
      "account": "/Compute-acme/default",
      "time_updated": "2017-03-10T08:42:39Z",
      "description": "",
      "user": "/Compute-acme/jack.jones@example.com",
      "persistent": false,
      "uri": "https://api-z999.compute.us0.oraclecloud.com/platform/v1/object/Compute-acme/jack.jones@example.com/firstOrchestration/my-seclist",
      "template": {
        "name": "/Compute-acme/jack.jones@example.com/my-seclist"
      },
      "label": "my-seclist",
      "time_audited": "2017-03-10T12:29:43Z",
      "version": 2,
      "health": {
        "status": "active",
        "object": {
          "account": "/Compute-acme/default",
          "description": "",
          "uri": "https://api-z999.compute.us0.oraclecloud.com/seclist/Compute-acme/jack.jones@example.com/my-seclist",
          "outbound_cidr_policy": "PERMIT",
          "policy": "DENY",
          "name": "/Compute-acme/jack.jones@example.com/my-seclist"
        }
      },
      "time_created": "2017-03-09T11:05:43Z",
      "orchestration": "/Compute-acme/jack.jones@example.com/firstOrchestration",
      "type": "SecList",
      "name": "/Compute-acme/jack.jones@example.com/firstOrchestration/my-seclist"
    },
    {
      "relationships": [
        
      ],
      "account": "/Compute-acme/default",
      "time_updated": "2017-03-10T08:44:45Z",
      "description": "a persistent storage volume",
      "user": "/Compute-acme/jack.jones@example.com",
      "persistent": true,
      "uri": "https://api-z999.compute.us0.oraclecloud.com/platform/v1/object/Compute-acme/jack.jones@example.com/firstOrchestration/volume1",
      "template": {
        "size": "2G",
        "properties": [
          "/oracle/public/storage/default"
        ],
        "name": "/Compute-acme/jack.jones@example.com/volume1"
      },
      "label": "myVolume1",
      "time_audited": "2017-03-20T16:04:20Z",
      "version": 4,
      "health": {
        "status": "active",
        "object": {
          "managed": true,
          "snapshot_id": null,
          "snapshot_account": null,
          "machineimage_name": null,
          "status_timestamp": "2017-03-20T15:57:57Z",
          "imagelist": null,
          "writecache": false,
          "size": "2147483648",
          "platform": null,
          "readonly": false,
          "storage_pool": "/Compute-acme/storagepool/iscsi/thruput_1",
          "shared": false,
          "status": "Online",
          "hash": 1665999033,
          "description": null,
          "tags": [
            
          ],
          "quota": null,
          "status_detail": null,
          "properties": [
            "/oracle/public/storage/default"
          ],
          "account": "/Compute-acme/default",
          "name": "/Compute-acme/jack.jones@example.com/volume1",
          "bootable": false,
          "hypervisor": null,
          "uri": "http://api-z999.compute.us0.oraclecloud.com/storage/volume/Compute-acme/jack.jones@example.com/volume1",
          "imagelist_entry": -1,
          "snapshot": null
        }
      },
      "time_created": "2017-03-10T07:05:24Z",
      "orchestration": "/Compute-acme/jack.jones@example.com/firstOrchestration",
      "type": "StorageVolume",
      "name": "/Compute-acme/jack.jones@example.com/firstOrchestration/volume1"
    }
  ]
}

orchestration-object get

Retrieves details of the specified orchestration object.

You can use the get command to verify whether add and update operations were completed successfully. Use the -F option (for example, -F status) to filter the output for specific attributes.

Required Role

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.

Syntax

opc compute orchestration-object get name

For help with the parameters and options of this command, run the command with the -h option.

Example

opc -f json compute orchestration-object get /Compute-acme/jack.jones@example.com/myOrchestration/seclist1

Sample Output

{
  "relationships": [],
  "account": "/Compute-acme/default",
  "time_updated": "2017-03-10T11:17:42Z",
  "description": "a persistent security list",
  "user": "/Compute-acme/jack.jones@example.com",
  "persistent": true,
  "uri": "https://api-z999.compute.us0.oraclecloud.com/platform/v1/object/Compute-acme/jack.jones@example.com/myOrchestration/seclist1",
  "template": {
    "name": "/Compute-acme/jack.jones@example.com/seclist1"
  },
  "label": "mySeclist1",
  "time_audited": "2017-03-10T11:27:44Z",
  "version": 2,
  "health": {
    "status": "active",
    "object": {
      "account": "/Compute-acme/default",
      "description": "",
      "uri": "https://api-z999.compute.us0.oraclecloud.com/seclist/Compute-acme/jack.jones@example.com/seclist1",
      "outbound_cidr_policy": "PERMIT",
      "policy": "DENY",
      "name": "/Compute-acme/jack.jones@example.com/seclist1"
    }
  },
  "time_created": "2017-03-10T11:05:39Z",
  "orchestration": "/Compute-acme/jack.jones@example.com/myOrchestration",
  "type": "SecList",
  "name": "/Compute-acme/jack.jones@example.com/myOrchestration/seclist1"
}

orchestration-object discover

Required Role

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.

Syntax

opc compute orchestration-object discover container

For help with the parameters and options of this command, run the command with the -h option.

Example

opc compute orchestration-object discover /Compute-acme/jack.jones@example.com/myOrchestration

Sample Output

result
-------------------------------------------------------------
/Compute-acme/jack.jones@example.com/myOrchestration/seclist1
/Compute-acme/jack.jones@example.com/myOrchestration/c18a1d1b-fdf4-48fd-b6f7-271bfa4d8bd7

orchestration-object update

Updates the specified orchestration object. You can update the following fields of an orchestration object: description, label, persistent, relationships, and template. You cannot update an object while the orchestration within which it is contained is in a transient state, such as activating, deactivating, and suspending.

Also note that you cannot move an object from one orchestration to another.

To update an orchestration object:

  1. Retrieve the details of the orchestration object in JSON format by running the orchestration-object get command.

  2. Note down the version of the orchestration object. You’ll need to specify the version of the orchestration object while running the update command.

  3. Modify the JSON file as per your requirements. You can update the following fields of an orchestration object: description, label, persistent, relationships, and template. You cannot update values for the other fields.

  4. After updating the JSON file, you should validate it. 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 update the orchestration object.

  5. Provide the modified JSON as the request body for this command.

Required Role

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.

Syntax

opc compute orchestration-object update name [--request-body=FILE.json]

For help with the parameters and options of this command, run the command with the -h option.

Example

opc compute orchestration-object update /Compute-acme/jack.jones@example.com/myOrchestration/seclist1 --request-body=update_object.json

Example of update_object.json File

The following example shows the content in the update_object.json file to update the /Compute-acme/jack.jones@example.com/myOrchestration/mySeclist object which is present in the/Compute-acme/jack.jones@example.com/myOrchestration orchestration. The following fields are updated for this object: persistent is set to false, label, description, and outbound_cidr_policy is set to PERMIT. 

{
  "type": "SecList",
  "orchestration": "/Compute-acme/jack.jones@example.com/myOrchestration",
  "name": "/Compute-acme/jack.jones@example.com/myOrchestration/seclist1",
  "label": "my-Security-list-1",
  "persistent": false,
  "template": {
   "name": "/Compute-acme/jack.jones@example.com/seclist1",
   "outbound_cidr_policy": "PERMIT", 
   "policy": "DENY"
   },
  "version": 2,
  "description": "an updated security list which is not persistent"
}

Sample Output

Some lines have been truncated with ellipses (...) for readability. When you run the command in your environment, you'll see the full output. 

{
  "relationships": [   
  ],
  "account": "/Compute-acme/default",
  "time_updated": "2016-11-10T22:36:23Z",
  "name": "/Compute-acme/jack.jones@example.com/mySeclist",
  "persistent": false,
  "uri": "https://api-z999.compute.us0.oraclecloud.com/platform/v1/object/Compute-acme/jack.jones@example.com/myOrchestration/mySeclist",
  "time_created": "2016-11-10T16:47:05Z",
  "label": "my-seclist",
  "time_audited": "2016-11-10T22:36:16Z",
  "orchestration": "/Compute-acme/jack.jones@example.com/myOrchestration",
  "version": 3,
  "health": {
    "status": "inactive"
    "object": {
      "account": "/Compute-acme/default",
      "description": "",
      "uri": null,
      "outbound_cidr_policy": "PERMIT",
      "policy": "DENY",
      "name": "/Compute-acme/jack.jones@example.com/seclist1"
    } 
  },
  "user": "/Compute-acme/jack.jones@example.com",
  "template": {
    "name": "/Compute-acme/jack.jones@example.com/seclist1"
    "policy": "PERMIT", 
    "outbound_cidr_policy": "PERMIT",
  },
  "type": "SecList",
  "description": "an updated security list which is not persistent"
}

orchestration-object delete

Deletes the specified orchestration object and the underlying object. For example, if you send a request to delete the/Compute-acme/jack.jones@example.com/myOrchestration/mySeclist orchestration object, the underlying /Compute-acme/jack.jones@example.com/mySeclist security list is also deleted.

No response is returned for this command.

Required Role

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.

Syntax

opc compute orchestration-object delete name [--terminate=true]

For help with the parameters and options of this command, run the command with the -h option.

Example 1: Deleting an inactive object

The following example shows how to delete an object, /Compute-acme/jack.jones@example.com/myOrchestration/mySeclist, which is in the inactive state. 

opc compute orchestration-object delete /Compute-acme/jack.jones@example.com/myOrchestration/mySeclist

Example 2: Deleting an active object

The following example shows how to delete an object, /Compute-acme/jack.jones@example.com/myOrchestration/Seclist1, which is in the active state. To delete an orchestration object in any active state, provide the terminate=True option to delete the orchestration object. 

opc compute orchestration-object delete /Compute-acme/jack.jones@example.com/myOrchestration/Seclist1 --terminate=True