Orchestration automates the management of your system components for high availability, monitoring, and persistence.
Orchestration ties together the components that you create into a single, manageable collection. In addition, you can specify the dependencies to control the sequence in which the components are created. For example, you can coordinate the creation of network and storage resources with the creation of the instance and, if high availability is enabled, restart the instance automatically if it terminates unexpectedly. In Oracle Compute Cloud Service, all instances are created using orchestrations.
Note:
Life-cycle commands (such asstart
, stop
, restart
etc.) that change the status of an orchestration, return immediately with the status change proceeding on the server side. Orchestration status can be monitored by retrieving the orchestration details.For more information about procedures related to orchestrations, see Orchestration Templates in Using Oracle Compute Cloud Service.
This API enables you to create a new orchestration from a JSON definition.
Method
POST
REST Resource
/orchestration/
URI
https://api_endpoint/orchestration/
Request Body Parameters
The JSON format of the orchestration is passed in the request body. For more information about the format and attributes of an orchestration JSON file, see section Orchestration Templates in Using Oracle Compute Cloud Service.Example URI
https://api.oc.example.com/orchestration
Example Request Body
{ "relationships": [], "account": null, "description": "", "schedule": {"start_time": null, "stop_time": null}, "uri": null, "oplans": [{ "ha_policy": null, "obj_type": "launchplan", "objects": [{ "instances": [{ "imagelist": "/oracle/public/linux6_12.2.1.0.0_64", "networking": { "net1": {"vnet": "/mytenant/public/ipoib1"}, "net0": {"vnet": "/mytenant/public/eoib1"} }, "shape": "oc3", "label": "pv-mixed1" }] }], "label": "pv-mixednet" }], "name": "/mytenant/public/pv-mixed1" }
Example Response Body
{ "relationships": [], "status": "stopped", "account": "/mytenant/default", "description": "", "schedule": {"start_time": null, "stop_time": null}, "uri": "http ://api/orchestration/mytenant/public/pv-mixed1", "oplans": [{ "status": "stopped", "info": {}, "obj_type": "launchplan", "ha_policy": "", "label": "pv-mixednet", "objects": [{ "instances": [{ "imagelist": "/oracle/public/linux6_12.2.1.0.0_64", "uri": null, "networking": { "net1": {"vnet": "/mytenant/public/ipoib1"}, "net0": {"vnet": "/mytenant/public/eoib1"} }, "shape": "oc3", "label": "pv-mixed1" }] }], "status_timestamp": null }], "info": {}, "status_timestamp": null, "name": "/mytenant/public/pv-mixed1" }
This API enables you to delete an orchestration from the system. Only orchestrations with stopped
status can be deleted.
Method
DELETE
REST Resource
/orchestration/name
URI
https://api_endpoint/orchestration/name
URI Parameter
Parameter | Description |
---|---|
name |
A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch |
Example URI
https://api.oc.example.com/orchestration/mytenant/public/myorch
This API enables you to start a specific orchestration. Only orchestrations with stopped
status can be started.
Starting an orchestration creates all the objects defined in the orchestration. The state of the orchestration changes as the start operation progresses. The start API request returns the response immediately, however the start operation continues on the server. The start operation is completed only when the orchestration reaches the ready
status.
Method
PUT
REST Resource
/orchestration/name
URI
https://api_endpoint/orchestration/name?action=START
URI Parameter
Parameter | Description |
---|---|
name | A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch |
action | (Optional) Specifies the action that should be performed on the orchestration. For this API, the valid value of this parameter is START . |
Example URI
https://api.oc.example.com/orchestration/mytenant/public/user1/test-vm?action=START
Example Response Body
{ "result": [ { "relationships": [], "status": "starting", "account": "/mytenant/default", "description": "", "schedule": {"start_time": "2015-10-23T09:58:52Z", "stop_time": null}, "uri": "https://api/orchestration/mytenant/public/mytenantdb", "oplans": [{ .....}] "status_timestamp": "2015-10-23T10:01:02Z"}], "info": {"errors": {}, "warnings": {}}, "status_timestamp": "2015-10-23T10:01:02Z", "name": "/mytenant/public/db" } ] }
This API enables you to stop a specific orchestration. Stopping an orchestration deletes all instances, releasing all resources allocated by the orchestration. This includes boot (root) disks and unreserved IP addresses. You can stop orchestrations in any one of the following statuses:ready
, shutdown
, warning
, and error
. The orchestration can be started again, thereby creating new instances and allocating new resources.
Method
PUT
REST Resource
/orchestration/name
URI
https://api_endpoint/orchestration/name?action=STOP
URI Parameters
Parameter | Description |
---|---|
name | A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch |
action | (Optional) Specifies the action which should be performed on the orchestration. The valid value of this parameter for this API is STOP . |
Example URI
https://api.oc.example.com/orchestration/mytenant/public/dev-vm?action=STOP
Example Response Body
{ "account": "/mytenant/default", "description": "", "info": { "errors": {}, "warnings": {} }, "name": "/mytenant/public/dev-vm", "oplans": [ { "ha_policy": "", "info": { "errors": {}, "warnings": {} }, "label": "sj-dev-vm", "obj_type": "launchplan", "objects": [ { "instances": [ { "imagelist": "/oracle/public/oel6", "ip": "10.128.0.10", "label": "sj-oel6-vm", "name": "/mytenant/public/d5baeacd-e97d-4933-b170-fcfad113bf1e", "networking": { "eth0": { "dns": [ "ccd371.mytenant.public.t1700-4186.example.com." ], "seclists": [ "/mytenant/default/default" ], "vethernet": "/oracle/public/default" } }, "shape": "small", "start_time": "2015-11-23T21:15:32Z", "state": "stopping", "uri": null } ] } ], "status": "ready", "status_timestamp": "2015-11-23T21:18:11Z" } ], "relationships": [], "schedule": { "start_time": "2015-11-23T21:15:27Z", "stop_time": "2015-11-24T18:43:13Z" }, "status": "ready", "status_timestamp": "2015-11-23T21:18:11Z", "uri": "http://api/orchestration/mytenant/public/dev-vm" }
This API enables you to shut down a VM instance while preserving the resources used by the instance, such as IP addresses and boot disk contents. When the orchestration is restarted, it gets back the same boot disks and IP addresses. If you do not need to preserve these resources use stop orchestration
. Orchestrations with a ready
or warning
state can be shut down.
Method
PUT
REST Resource
/orchestration/name
URI
https://api_endpoint/orchestration/name?action=SHUTDOWN
URI Parameters
Parameter | Description |
---|---|
name | A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch . |
action | (Optional) Specifies the action that should be performed on the orchestration. The valid value of this parameter for this API is SHUTDOWN. |
Example URI
https://api.oc.example.com/orchestration/mytenant/public/dev-vm?action=SHUTDOWN
Example Response Body
{ "account": "/mytenant/default", "description": "", "info": { "errors": {}, "warnings": {} }, "name": "/mytenant/public/dev-vm", "oplans": [ { "ha_policy": "", "info": { "errors": {}, "warnings": {} }, "label": "sj-dev-vm", "obj_type": "launchplan", "objects": [ { "instances": [ { "imagelist": "/oracle/public/oel6", "ip": "10.128.0.10", "label": "sj-oel6-vm", "name": "/mytenant/public/d5baeacd-e97d-4933-b170-fcfad113bf1e", "networking": { "eth0": { "dns": [ "ccd371.mytenant.public.t1700-4186.example.com." ], "seclists": [ "/mytenant/default/default" ], "vethernet": "/oracle/public/default" } }, "shape": "small", "start_time": "2015-11-23T21:15:32Z", "state": "shutting_down", "uri": null } ] } ], "status": "ready", "status_timestamp": "2015-11-23T21:18:11Z" } ], "relationships": [], "schedule": { "start_time": "2015-11-23T21:15:27Z", "stop_time": "2015-11-24T18:43:13Z" }, "status": "ready", "status_timestamp": "2015-11-23T21:18:11Z", "uri": "http://api/orchestration/mytenant/public/dev-vm" }
This API enables you to restart an orchestration that was previously in the shut_down
status. You can restart an orchestration with status warning
, shut_down
or error
.
Method
PUT
REST Resource
/orchestration/name
URI
https://api_endpoint/orchestration/name?action=RESTART
URI Parameters
Parameter | Description |
---|---|
name | A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch . |
action | (Optional) Specifies the action to be performed on the orchestration. The valid value of this parameter for this API is RESTART . |
Example URI
https://api.oc.example.com/orchestration/mytenant/public/dev-vm?action=RESTART
Example Response Body
{ "account": "/mytenant/default", "description": "", "info": { "errors": {}, "warnings": {} }, "name": "/mytenant/public/dev-vm", "oplans": [ { "ha_policy": "", "info": { "errors": {}, "warnings": {} }, "label": "sj-dev-vm", "obj_type": "launchplan", "objects": [ { "instances": [ { "imagelist": "/oracle/public/oel6", "ip": "10.128.0.10", "label": "sj-oel6-vm", "name": "/mytenant/public/d5baeacd-e97d-4933-b170-fcfad113bf1e", "networking": { "eth0": { "dns": [ "ccd371.mytenant.public.t1700-4186.example.com." ], "seclists": [ "/mytenant/default/default" ], "vethernet": "/oracle/public/default" } }, "shape": "small", "start_time": "2015-11-23T21:15:32Z", "state": "restarting", "uri": null } ] } ], "status": "ready", "status_timestamp": "2015-11-23T21:18:11Z" } ], "relationships": [], "schedule": { "start_time": "2015-11-23T21:15:27Z", "stop_time": "2015-11-24T18:43:13Z" }, "status": "ready", "status_timestamp": "2015-11-23T21:18:11Z", "uri": "http://api/orchestration/mytenant/public/dev-vm" }
This API enables you to update information for a specific orchestration.
You can update any part of an orchestration aside from the name when it is in stopped
status. When the orchestration is in ready
status, you can update the ha_policy
and label
of an existing oplan in the orchestration. You can also add and remove oplans. Added oplans will be started
, and removed oplans will be stopped
.
Method
PUT
REST Resource
/orchestration/name
URI
https://api_endpoint/orchestration/name
URI Parameters
Parameter | Description |
---|---|
name | A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch |
Request Body Parameters
You can update the orchestration parameters in JSON format. For more information on the orchestration parameters, see section Orchestration Templates in Using Oracle Compute Cloud Service.Example URI
https://api.oc.example.com/orchestration/mytenant/public/ac-control-vms
Example Request Body
{ "relationships": [], "status": "ready", "account": "/mytenant/default", "description": "", "schedule": { "start_time": "2015-07-27T09:02:27Z", "stop_time": null }, "uri": "https://api.oc.example.com/orchestration/mytenant/public/ac-control-vms", "oplans": [{ "status": "ready", "info": {"errors": {}, "warnings": {}}, "obj_type": "launchplan", "ha_policy": "active", "label": "ac-control-vms", "objects": [{"relationships": [{"instances": ["ac-control-vm1", "ac-control-vm2"], .........}], "status_timestamp": "2015-09-17T22:54:14Z" }], "info": {"errors": {}, "warnings": {}}, "status_timestamp": "2015-09-17T22:54:14Z", "name": "/mytenant/public/ac-control-vms" }
Example Response Body
{ "relationships": [], "status": "ready", "account": "/mytenant/default", "description": "", "schedule": { "start_time": "2015-07-27T09:02:27Z", "stop_time": null }, "uri": "https://api.oc.example.com/orchestration/mytenant/public/ac-control-vms", "oplans": [{ "status": "ready", "info": {"errors": {}, "warnings": {}}, "obj_type": "launchplan", "ha_policy": "active", "label": "ac-control-vms", "objects": [{"relationships": [{"instances": ["ac-control-vm1", "ac-control-vm2"], .........}], "status_timestamp": "2015-09-17T22:54:14Z" }], "info": {"errors": {}, "warnings": {}}, "status_timestamp": "2015-09-17T22:54:14Z", "name": "/mytenant/public/ac-control-vms" }
This API enables you to discover orchestrations within a specific container or subcontainer.
Note:
The discover API calls display the names of the objects in the specified container, not the details about the objects. To list the names of the objects, you must set theAccept
header to application/oracle-compute-v3+directory+json
. For all other purposes, you must set the Accept
header to application/oracle-compute-v3+json
.Method
GET
REST Resource
/orchestration/container/
URI
https://api_endpoint/orchestration/container/
URI Parameter
Parameter | Description |
---|---|
container | Hierarchical namespace for the orchestrations |
Example URI
https://api.oc.example.com/orchestration/mytenant/public
Example Response Body
{ "result": [ "/mytenant/public/el-control-vms", "/mytenant/public/el-db-vms", "/mytenant/public/scae09-sdi-sdivm-el1-4-storagevolume-app", "/mytenant/public/scae09-sdi-sdivm-el1-5-storagevolume-ops", "/mytenant/public/scae09-sdi-sdivm-el1-6-storagevolume-data", "/mytenant/public/scae09-sdi-sdivm-el1-8-instance" ] }
This API enables you to retrieve details of a specific orchestration.
Method
GET
REST Resource
/orchestration/name
URI
https://api_endpoint/orchestration/name
URI Parameter
Parameter | Description |
---|---|
name | A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch |
Example URI
https://api.oc.example.com/orchestration/mytenant/public/el-db-vms
Example Response Body
{ "relationships": [], "status": "ready", "account": "/mytenant/default", "description": "", "schedule": {"start_time": "2015-07-27T09:05:50Z", "stop_time": null}, "uri": "https://api/orchestration/mytenant/public/el-db-vms", "oplans": [ {"status": "ready", "info": {"errors": {}, "warnings": {}}, "obj_type": "launchplan", "ha_policy": "active",.....}], "status_timestamp": "2015-09-06T21:11:39Z"}], "info": {"errors": {}, "warnings": {}}, "status_timestamp": "2015-09-06T21:11:39Z", "name": "/mytenant/public/el-db-vms" }
This API enables you to retrieve details about orchestrations in a specific container. The GET
method can be used to validate the results of the POST
, PUT
, and DELETE
operations.
Method
GET
REST Resource
/orchestration/container/
URI
https://api_endpoint/orchestration/container?status=statusValue
URI Parameter
Parameter | Description |
---|---|
container | Hierarchical namespace for orchestrations |
status=statusValue | (Optional) Current status of the orchestration. The following status options are supported:
If this parameter is specified, then the list orchestration output is filtered for the given status. |
Example URI
https://api.oc.example.com/orchestration/mytenant/public/
Example Response Body
{ "result": [ { "relationships": [], "status": "ready", "account": "/mytenant/default", "description": "", "schedule": {"start_time": "2015-10-23T09:58:52Z", "stop_time": null}, "uri": "https://api/orchestration/mytenant/public/mytenantdb", "oplans": [{ .....}] "status_timestamp": "2015-10-23T10:01:02Z"}], "info": {"errors": {}, "warnings": {}}, "status_timestamp": "2015-10-23T10:01:02Z", "name": "/mytenant/public/db" } { "relationships": [], "status": "ready", "account": "/mytenant/default", "description": "", "schedule": {"start_time": "2015-10-24T00:43:10Z", "stop_time": null}, "uri": "https://api/orchestration/mytenant/public/mytenantgrill", "oplans": [{.....}], "status_timestamp": "2015-10-24T00:46:31Z"}], "info": {"errors": {}, "warnings": {}}, "status_timestamp": "2015-10-24T00:46:31Z", "name": "/mytenant/public/mytenantgrill" } ]