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

24 Orchestration

This section describes the Compute Classic CLI commands that you can use to add, start, stop, view, update, and delete orchestrations.

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.

After creating an orchestration (in a JSON-formatted file) and adding it to Compute Classic, you can trigger the creation and removal all the resources defined in the orchestration with a single step.

An orchestration contains one or more object plans (oplans). The attributes that you can specify in an oplan vary depending on the object type (obj_type). For detailed information about the object types that you can create by using orchestrations and the attributes for each object type, see Attributes in Orchestrations in Using Oracle Cloud Infrastructure Compute Classic.

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 add

Adds an orchestration to Compute Classic. 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.

Prerequisites

  • Create a JSON file to specify attributes for the Compute Classic objects that you want to create. See Building Your First Orchestration in Using Oracle Cloud Infrastructure Compute Classic.

  • After creating 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 add your orchestration.

After adding an orchestration, you can start the orchestration as described in orchestration update to create all the objects you have defined in the orchestration JSON file.

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

Use any one of the following syntax.

  • In this syntax, filename is the complete path and name of the file where you have defined the details of the orchestration in JSON format. For information about building an orchestration JSON file, see Building Your First Orchestration in Using Oracle Cloud Infrastructure Compute Classic. 

    opc compute orchestration add --request-body=filename.json
  • opc compute orchestration add oplans [--name name] [--description description] [--relationships relationships] [--schedule schedule]

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

Example 1: Specifying all orchestration attributes in a single JSON file

opc -f json compute orchestration add --request-body=./orchestration.json

Example of orchestration.json

The following is an example of a JSON-formatted file showing the attributes, such as storage volume, description, SSH key, security list, shape, and image list for a single instance.

{
  "description": "Simple orchestration with an SSH key and a security list",
  "name": "/Compute-acme/joe.jonathan@example.com/simple_orchestration",
  "oplans": [
    {
      "label": "simple_oplan",
      "obj_type": "launchplan",
      "objects": [
        {
          "instances": [
            {
              "imagelist": "/oracle/public/oel6",
              "label": "Linux",
              "networking": {
                "eth0": {
                  "seclists": [
                    "/Compute-acme/joe.jonathan@example.com/seclist1"
                  ],
                  "nat": "ippool:/oracle/public/ippool"
                }
              },
              "shape": "oc3",
              "storage_attachments": [
                {
                  "index": 1,
                  "volume": "/Compute-acme/joe.jonathan@example.com/vol1"
                  
                }
              ],
              "sshkeys": [
                "/Compute-acme/joe.jonathan@example.com/ssh-key1"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Sample Output for Example 1

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

{
 "account": "/Compute-acme/default",
 "description": "Simple orchestration with an SSH key and a security list",
 "info": {},
 "name": "/Compute-acme/jack.jones@example.com/simple_orchestration",
 "oplans": [
  {
   "ha_policy": "",
   "info": {},
   "label": "simple_oplan",
   "obj_type": "launchplan",
   "objects": [
    {
     "instances": [
      {
       "imagelist": "/oracle/public/oel6",
       "label": "Linux",
       "networking": {
        "eth0": {
         "nat": "ippool:/oracle/public/ippool",
         "seclists": [
          "/Compute-acme/jack.jones@example.com/seclist1"
         ]
        }
       },
       "shape": "oc3",
       "sshkeys": [
        "/Compute-acme/jack.jones@example.com/ssh-key1"
       ],
       "storage_attachments": [
        {
         "index": 1,
         "volume": "/Compute-acme/jack.jones@example.com/vol1"
        }
       ],
       "uri": null
      }
     ]
    }
   ],
   "status": "stopped",
   "status_timestamp": null
  }
 ],
 "relationships": [],
 "schedule": {
  "start_time": null,
  "stop_time": null
 },
 "status": "stopped",
 "status_timestamp": null,
 "uri": "https://api-z999.compute.us0.oraclecloud.com/orchestration/Compute-acme/jack.jones@example.com/simple_orchestration",
 "user": "/Compute-acme/jack.jones@example.com"
}

Example 2: Specifying orchestration attributes in different JSON files

In the following example, orchestration attributes are specified in different JSON files. Instance attributes are defined in the oplan.json file. Relationship between oplans is defined in the relationship.json file. The schedule to start the orchestration is defined in the schedule.json file. 

opc -f json compute orchestration add  file://./oplan.json --relationships file://./relationship.json --name /Compute-acme/jack.jones@example.com/orchestration2 --schedule file://./schedule.json --description 'an orchestration containing multiple oplan with relationship and schedule defined'

Example of oplan.json

[ {
    "ha_policy": "active",
    "label": "launchplan1",
    "obj_type": "launchplan",
    "objects": [
      {
        "instances": [
          {
            "imagelist": "/oracle/public/oel6",
            "label": "instance1",
            "name": "/Compute-acme/jack.jones@example.com/instance1",
            "shape": "oc3"
          }
        ]
      }
    ]
  },
  {
    "ha_policy": "active",
    "label": "launchplan2",
    "obj_type": "launchplan",
    "objects": [
      {
        "instances": [
          {
            "imagelist": "/oracle/public/oel6",
            "label": "instance2",
            "name": "/Compute-acme/jack.jones@example.com/instance2",
            "shape": "oc3"
          }
        ]
      }
    ]
  }
]

Example of relationship.json

[
    {
      "oplan": "launchplan2",
      "to_oplan": "launchplan1",
      "type": "depends"
    }
]

Example of schedule.json

{
    "start_time": "2017-04-04T13:31:45Z",
    "stop_time": null
}

Sample Output for Example 2

{
 "account": "/Compute-acme/default",
 "description": "an orchestration containing multiple oplan with relationship and schedule defined",
 "info": {},
 "name": "/Compute-acme/jack.jones@example.com/orchestration2",
 "oplans": [
  {
   "ha_policy": "active",
   "info": {},
   "label": "launchplan1",
   "obj_type": "launchplan",
   "objects": [
    {
     "instances": [
      {
       "imagelist": "/oracle/public/oel6",
       "label": "instance1",
       "name": "/Compute-acme/jack.jones@example.com/instance1",
       "shape": "oc3",
       "uri": null
      }
     ]
    }
   ],
   "status": "stopped",
   "status_timestamp": null
  },
  {
   "ha_policy": "active",
   "info": {},
   "label": "launchplan2",
   "obj_type": "launchplan",
   "objects": [
    {
     "instances": [
      {
       "imagelist": "/oracle/public/oel6",
       "label": "instance2",
       "name": "/Compute-acme/jack.jones@example.com/instance2",
       "shape": "oc3",
       "uri": null
      }
     ]
    }
   ],
   "status": "stopped",
   "status_timestamp": null
  }
 ],
 "relationships": [
  {
   "oplan": "launchplan2",
   "to_oplan": "launchplan1",
   "type": "depends"
  }
 ],
 "schedule": {
  "start_time": null,
  "stop_time": null
 },
 "status": "stopped",
 "status_timestamp": null,
 "uri": "https://api-z999.compute.us0.oraclecloud.com/orchestration/Compute-acme/jack.jones@example.com/orchestration2",
 "user": "/Compute-acme/jack.jones@example.com"
}

orchestration list

Retrieves details of all the orchestrations in the specified container that match the specified query criteria. You can pass one or more query parameters to filter the search results. If you don't specify any query criteria, then details of all the orchestrations 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 list container [--status status]

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

Example

opc -f table -F name,status compute orchestration list /Compute-acme/jack.jones@example.com

Sample Output

+-----------------------------------------------------------+----------+
|                             NAME                          |  STATUS  |
+-----------------------------------------------------------+----------+
| /Compute-acme/jack.jones@example.com/webportal            | stopping |
| /Compute-acme/jack.jones@example.com/webclient            | stopped  |
| /Compute-acme/jack.jones@example.com/appserver_master     | ready    |
| /Compute-acme/jack.jones@example.com/appserver_storage    | ready    |
+-----------------------------------------------------------+----------+

orchestration 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 discover container

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

Example

opc -f json compute orchestration discover /Compute-acme/jack.jones@example.com

Sample Output

{
 "result": [
  "/Compute-acme/jack.jones@example.com/webportal",
  "/Compute-acme/jack.jones@example.com/webserver"
 ]
}

orchestration get

Retrieves details of the specified orchestration.

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 get name

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

Example

opc -f table -F status compute orchestration get /Compute-acme/jack.jones@example.com/webportal

Sample Output

+--------+-------+
  status | ready
+--------+-------+

orchestration update

Updates an orchestration. You can update an orchestration by modifying the attributes specified in the orchestration JSON file. You can also start and stop an orchestration.

To modifying the attributes specified in an orchestration:

  1. Run the orchestration get command to get the latest contents of the orchestration in JSON format.

  2. Copy the content in JSON format, and then make the required changes in the JSON file offline using any text editor. Ensure that you specify the name of the orchestration that you want to modify in the updated orchestration JSON file.

    You can update orchestrations when they are in one of the following states: stopped and running. Depending on the state of an orchestration, you can make the following updates:

    • When an orchestration is in the stopped state, you can modify, add, or remove all the attributes defined in the orchestration JSON file.

    • When an orchestration is running, you can make the following changes to the orchestration:

      • Add or remove oplans. For example: when an orchestration is running, you can add a new oplan with attributes to launch a new instance.

      • Modify the HA policy of the existing oplans. You cannot modify any other attributes of existing oplans.

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

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

Use any one of the following syntax.

  • opc compute orchestration update name --request-body=filename.json [--action STOP/START]

  • opc compute orchestration update name [--oplans filename.json] [--description description] [--relationships relationships] [--schedule schedule] [--action STOP/START]

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

Example 1: Starting an orchestration

The following example starts the /Compute-acme/jack.jones@example.com/simple_orchestration that you added by sending the POST /orchestration/ HTTP request. When you start an orchestration, all the objects defined in the orchestration are created. To monitor the status of the orchestration, send the GET /orchestration/{name} HTTP request. 

opc -f json compute orchestration update /Compute-acme/jack.jones@example.com/simple_orchestration --request-body=orchestration.json --action START

Sample output for example 1

{
 "account": "/Compute-acme/default",
 "description": "Simple orchestration with an SSH key and a security list",
 "info": {},
 "name": "/Compute-acme/jack.jones@example.com/simple_orch",
 "oplans": [
  {
   "ha_policy": "",
   "info": {},
   "label": "simple_oplan",
   "obj_type": "launchplan",
   "objects": [
    {
     "instances": [
      {
       "imagelist": "/oracle/public/oel6",
       "label": "Linux",
       "networking": {
        "eth0": {
         "nat": "ippool:/oracle/public/ippool",
         "seclists": [
          "/Compute-acme/default/default"
         ]
        }
       },
       "shape": "oc3",
       "sshkeys": [
        "/Compute-acme/jack.jones@example.com/ssh-key1"
       ],
       "storage_attachments": [
        {
         "index": 1,
         "volume": "/Compute-acme/jack.jones@example.com/vol1"
        }
       ],
       "uri": null
      }
     ]
    }
   ],
   "status": "stopped",
   "status_timestamp": null
  }
 ],
 "relationships": [],
 "schedule": {
  "start_time": "2017-03-27T08:55:39Z",
  "stop_time": null
 },
 "status": "starting",
 "status_timestamp": null,
 "uri": "https://10.88.212.10:445/orchestration/Compute-acme/jack.jones@example.com/simple_orch",
 "user": "/Compute-acme/jack.jones@example.com"
}

Example 2: Updating the details of an orchestration

The following command updates the /Compute-acme/jack.jones@example.com/orchestration2 orchestration with the updated information provided in oplan.json file. In the example, the oplan.json file contains the downloaded orchestration details. The content of the oplan.json is updated offline using a text editor to use the /Compute-acme/jack.jones@example.com/prodimages image list in place of the /oracle/public/oel_6 image list. The description of the orchestration is updated at the command line. The orchestration is updated based on the information provided in the JSON file, and then it is started. 

opc -f json compute orchestration update /Compute-acme/jack.jones@example.com/orchestration2 --oplan file://./oplan1.json --relationships file://./relationship.json --description 'updating an orchestration containing multiple oplan with relationship and schedule defined' --action=START

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. 

{
 "account": "/Compute-acme/default",
 "description": "updating an orchestration containing multiple oplan with relationship and schedule defined",
 "info": {},
 "name": "/Compute-acme/jack.jones@example.com/orchestration2",
 "oplans": [
  {
   "ha_policy": "active",
   "info": {},
   "label": "launchplan1",
   "obj_type": "launchplan",
   "objects": [
    {
     "instances": [
      {
       "imagelist": "/Compute-acme/jack.jones@example.com/prodimages",
       "label": "instance1",
       "name": "/Compute-acme/jack.jones@example.com/instance1",
       "shape": "oc3",
       "uri": null
      }
     ]
    }
   ],
   "status": "stopped",
   "status_timestamp": null
  },
  {
   "ha_policy": "active",
   "info": {},
   "label": "launchplan2",
   "obj_type": "launchplan",
   "objects": [
    {
     "instances": [
      {
       "imagelist": "/Compute-acme/jack.jones@example.com/prodimages",
       "label": "instance2",
       "name": "/Compute-acme/jack.jones@example.com/instance2",
       "shape": "oc3",
       "uri": null
      }
     ]
    }
   ],
   "status": "stopped",
   "status_timestamp": null
  }
 ],
 "relationships": [
  {
   "oplan": "launchplan2",
   "to_oplan": "launchplan1",
   "type": "depends"
  }
 ],
 "schedule": {
  "start_time": "2017-03-28T07:17:39Z",
  "stop_time": null
 },
 "status": "starting",
 "status_timestamp": null,
 "uri": "https://api-z999.compute.us0.oraclecloud.com/orchestration/Compute-acme/jack.jones@example.com/orchestration2",
 "user": "/Compute-acme/jack.jones@example.com"
}

orchestration delete

Deletes an orchestration. No response is returned for the delete action.

Before deleting an orchestration, you must stop the orchestration and wait till the status of the orchestration changes to stopped. When you stop an orchestration, all the objects defined in the orchestration are deleted. However, stopping an orchestration doesn’t cause the orchestration itself to be deleted. Even after you stop an orchestration, you can still start, view, or update the orchestration.

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 delete name

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

Example

opc compute orchestration delete /Compute-acme/jack.jones@example.com/webportal