1. REST API for Oracle Cloud Infrastructure Compute Classic
  2. Tasks
  3. Instances

Update an Instance

put

/instance/{name}

You can use this request to shut down and restart individual instances which use a persistent bootable storage volume.

* Set the value of the desired_state parameter as shutdown to shut down the instance.

* Set the value of the desired_state parameter as running to restart an instance that you had previously shutdown. The instance is restarted without losing any of the instance data or configuration.

You can also update the value for the tags parameter. If the instance is already shut down, you can also change the value of the shape parameter.

Shutting down an instance is useful when you've created multiple instances in a single orchestration. In this case, stopping the instance orchestration would cause all instances to be deleted. If you want to stop one or more instances, while letting other instances in the same orchestration run, you can shut down the required instances individually.

Here's what happens when you shut down an instance:

* The instance ID is retained and reused when you restart the instance. So the multipart instance name doesn't change. This is useful in case the instance name is referenced by other objects, such as storage attachments.

* For instances created using orchestrations v1, the instance orchestration shows an error. However, even if the HA policy specified is active, the instance isn't automatically re-created.

* The resources associated with that instance, such as storage volumes and IP reservations, are freed up and can be used by other instances if required. However, if you attempt to restart an instance, ensure that the required resources are available, otherwise the instance can't restart and will go into an error state.

* The private IP address on the shared network is released. If you restart the instance later, it is allotted a private IP address afresh. So the private IP address of the instance on the shared network is likely to change.

* Dynamically allocated IP addresses on IP networks are also released. So if you start the instance later, dynamically allocated IP addresses on IP networks are also likely to change. Static private IP addresses that are allocated to interfaces in the instance orchestration won't change.

* Any changes that you'd made to the instance in Compute Classic after the instance was created will be lost. For example, if you added the instance to security lists, attached storage volumes to the instance, or detached and attached an IP reservation, you'll need to make those changes again. The instance will be restarted with the resources that are associated with it in the instance orchestration.

Note: Changes made to the instance by logging in to the instance won't be lost, however, as these are preserved on the persistent storage volumes attached to the instance. Data on storage volumes isn't affected by shutting down an instance.

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 My Services. See Modifying User Roles in Managing and Monitoring Oracle Cloud.

Request

Supported Media Types
Path Parameters
  • Multipart name of the instance that you want to update.
Header Parameters
Body ()
The request body contains details of the instance that you want to update.
Root Schema : Instance-put-request
Type: object
The request body contains details of the instance that you want to update.
Show Source
  • Desired state for the instance.

    * Set the value of the desired_state parameter as shutdown to shut down the instance.

    * Set the value of the desired_state parameter as running to restart an instance that you had previously shutdown. The instance is restarted without losing any of the instance data or configuration.

  • A shape is a resource profile that specifies the number of CPU threads and the amount of memory (in MB) to be allocated to an instance.

    If the instance is already shut down, you can change the shape that is associated with the instance.

  • tags
    Comma-separated list of strings that you can use to tag the instance. Later on you can use these tags to retrieve the instance.
Nested Schema : tags
Type: array
Comma-separated list of strings that you can use to tag the instance. Later on you can use these tags to retrieve the instance.
Show Source
Back to Top

Response

Supported Media Types

200 Response

OK. See Status Codes for information about other possible HTTP status codes.
Headers
Body ()
Root Schema : Instance-response
Type: object
Show Source
Nested Schema : attributes
Type: object
Additional Properties Allowed
Show Source
A dictionary of attributes to be made available to the instance. A value with the key "userdata" will be made available in an EC2-compatible manner.
Nested Schema : boot_order
Type: array
Boot order list.
Show Source
Nested Schema : hypervisor
Type: object
Additional Properties Allowed
Show Source
A dictionary of hypervisor-specific attributes.
Nested Schema : networking
Type: object
Additional Properties Allowed
Show Source
Mapping of to network specifiers for virtual NICs to be attached to this instance.
Nested Schema : placement_requirements
Type: array
A list of strings specifying arbitrary tags on nodes to be matched on placement.
Show Source
Nested Schema : relationships
Type: array
A list of relationship specifications to be satisfied on this instance's placement
Show Source
Nested Schema : resolvers
Type: array
Resolvers to use instead of the default resolvers.
Show Source
Nested Schema : sshkeys
Type: array
SSH keys that will be exposed to the instance.
Show Source
Nested Schema : storage_attachments
Type: array
List of dictionaries containing storage attachment Information.
Show Source
Nested Schema : tags
Type: array
Comma-separated list of strings used to tag the instance.
Show Source
Nested Schema : additionalProperties
Type: object
Nested Schema : additionalProperties
Type: object
Nested Schema : additionalProperties
Type: object
Nested Schema : items
Type: object
Additional Properties Allowed
Show Source
Nested Schema : additionalProperties
Type: object
Back to Top

Examples

cURL Command

The following example shows how to update an instance, /Compute-acme/jack.jones@example.com/app_instance1/95404c2c-3b42-4e11-a412-5108f3c43ec8, by submitting a PUT request on the REST object using cURL. For more information about cURL, see Use cURL.

Enter the command on a single line. Line breaks are used in this example for readability.

curl -i -X PUT
     -H "Cookie: $COMPUTE_COOKIE"
     -H "Content-Type: application/oracle-compute-v3+json"
     -H "Accept: application/oracle-compute-v3+json"
     -d "@requestbody.json"
        https://api-z999.compute.us0.oraclecloud.com/instance/Compute-acme/jack.jones@example.com/app_instance1/95404c2c-3b42-4e11-a412-5108f3c43ec8

  • COMPUTE_COOKIE is the name of the variable in which you stored the authentication cookie earlier. For information about retrieving the authentication cookie and storing it in a variable, see Authentication.

  • api-z999.compute.us0.oraclecloud.com is an example REST endpoint URL. Change this value to the REST endpoint URL of your Compute Classic site. For information about finding out REST endpoint URL for your site, see Send Requests.

  • acme and jack.jones@example.com are example values. Replace acme with the identity domain ID of your Compute Classic account, and jack.jones@example.com with your user name.

  • After creating the request body 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 pass the request body.

Example of Request Body

The following shows an example of the request body content in the requestbody.json file to shut down a running instance by setting desired_state of the instance to shutdown. 

{
  "desired_state":"shutdown"
}

Example of Response Body

The following example shows the response body in JSON format when you want to shut down a running instance by setting desired_state of the instance to shutdown. 

{
      "domain": "compute-acme.oraclecloud.internal.",
      "placement_requirements": [
        "/system/compute/placement/default",
        "/system/compute/allow_instances"
      ],
      "ip": "10.196.35.146",
      "fingerprint": "",
      "site": "",
      "shape": "oc1m",
      "imagelist": null,
      "image_format": "raw",
      "relationships": [],
      "networking": {
        "eth0": {
          "model": "",
          "seclists": [
            "/Compute-acme/default/default"
          ],
          "dns": [
            "abde9e.compute-acme.oraclecloud.internal."
          ],
          "vethernet": "/oracle/public/default",
          "nat": null
        }
      },
      "storage_attachments": [
        {
          "index": 1,
          "storage_volume_name": "/Compute-acme/jack.jones@example.com/volumes/app_boot_volume",
          "name": "/Compute-acme/jack.jones@example.com/app_instance1/95404c2c-3b42-4e11-a412-5108f3c43ec8/20cf7e9e-2bd2-4c57-9aa4-1568d5928034"
        }
      ],
      "hostname": "abde9e.compute-acme.oraclecloud.internal.",
      "quota_reservation": null,
      "disk_attach": "",
      "label": "1dafbfc8-dd3e-4858-8725-180c3d5fb9cf",
      "priority": "/oracle/public/default",
      "platform": "linux",
      "state": "running",
      "virtio": null,
      "vnc": "10.196.35.145:5900",
      "desired_state": "shutdown",
      "tags": [],
      "quota": "/Compute-acme",
      "entry": null,
      "error_reason": "",
      "sshkeys": null,
      "resolvers": null,
      "account": "/Compute-acme/default",
      "name": "/Compute-acme/jack.jones@example.com/app_instance1/95404c2c-3b42-4e11-a412-5108f3c43ec8",
      "vcable_id": "/Compute-acme/jack.jones@example.com/135fccfb-135c-4ede-87d3-e8efbf57016f",
      "hypervisor": {
        "mode": "hvm"
      },
      "uri": "http://api-z999.compute.us0.oraclecloud.com/instance/Compute-acme/jack.jones@example.com/app_instance1/95404c2c-3b42-4e11-a412-5108f3c43ec8",
      "reverse_dns": true,
      "attributes": {
        "oracle_metadata": {
          "v2": {
            "orchestration": "/Compute-acme/jack.jones@example.com/app_instance",
            "object": "/Compute-acme/jack.jones@example.com/app_instance/8d5754ce-73af-4abb-9a22-c7c3d96597dc"
          }
        },
        "sshkeys": [],
        "dns": {
          "domain": "compute-acme.oraclecloud.internal.",
          "hostname": "abde9e.compute-acme.oraclecloud.internal.",
          "nimbula_vcable-eth0": "abde9e.compute-acme.oraclecloud.internal."
        },
        "network": {
          "nimbula_vcable-eth0": {
            "vethernet_id": "0",
            "vethernet": "/oracle/public/default",
            "address": [
              "c6:b0:81:cf:f8:6c",
              "10.196.35.146"
            ],
            "model": "",
            "vethernet_type": "vlan",
            "id": "/Compute-acme/jack.jones@example.com/135fccfb-135c-4ede-87d3-e8efbf57016f",
            "dhcp_options": []
          }
        }
      },
      "boot_order": [
        1
      ]
 }

It takes some time for the state of the instance to change. You can track the change in the state of the instance by sending the GET /instance/{name} HTTP request.

Back to Top