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 (activatingsuspending, 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 activatingsuspending, 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