Managing Instances

An instance is a logical representation of a virtual machine (VM). An instance defines the properties of a virtual machine and has a life cycle that surrounds and extends beyond the life cycle of a single virtual machine. You create virtual machine instances by starting orchestrations, but you can manage them individually thereafter by using CLI commands or API requests.

Note:

Life-cycle commands (such as start, stop, restart etc.) that change the state of an instance, return immediately with the state change proceeding on the server side. Instance state can be monitored by retrieving the instance details.

Topics:

Delete Instance

This API request enables you to delete a specific instance. You can delete an instance only when it is in any of the following states:running, shut_down, or error.

Note:

When an instance is deleted, the associated orchestration transitions to the warning state. You need to stop and start this orchestration if you want to associate it with a new instance.

Method

DELETE

REST Resource

/instance/name

URI

https://api_endpoint/instance/name

URI Parameter

Parameters Description
name A unique hierarchical name of an instance. For example, /mytenant/public/e6640ebc-6953-444f-848d-4a3bf6050ea5.

Example URI

https://api.oc.example.com/instance/mytenant/admin/f653a677-b566-4f92-8e93-71d47b364119

Restart Instance

This API request enables you to restart a specific instance. You can restart an instance only when it is in one of the following states: shut_down, warning, or error.

Method

PUT

REST Resource

/instance/name/

URI

https://api_endpoint/instance/name?action=RESTART

URI Parameters

Parameter Description
name A unique hierarchical name for an instance. For example, /mytenant/public/e6640ebc-6953-444f-848d-4a3bf6050ea5e.

Example URI

https://api.oc.example.com/instance/mytenant/public/test123/6fffcc31-5fc4-4d68-828e-5310229f8840?action=RESTART

Shutdown Instance

This API request enables you to shutdown an instance.

Method

PUT

REST Resource

/instance/name/

URI

https://api_endpoint/instance/name?action=SHUTDOWN

URI Parameters

Parameter Description
name A unique hierarchical name for an instance. For example, /mytenant/public/e6640ebc-6953-444f-848d-4a3bf6050ea5e.

Example URI

https://api.oc.example.com/instance/mytenant/public/test123/6fffcc31-5fc4-4d68-828e-5310229f8840?action=SHUTDOWN

Update Instance

This API request enables you to update parameters for a specific instance.

Method

PUT

REST Resource

/instance/name/

URI

https://api_endpoint/instance/name

URI Parameters

Parameter Description
name A unique hierarchical name for an instance. For example, /mytenant/public/e6640ebc-6953-444f-848d-4a3bf6050ea5e.

Request Body Parameters

To update an instance, use the GET /instance/name API to fetch the existing list of instance parameters. You can use this list of instance parameters to make desired changes, and re-send it as part of the PUT /instance/name API request body.

Note:

You cannot modify all the parameters of the instance.

The following table lists the instance parameters that can be modified.

Parameter Description
shape (Optional) The name of the shape to be associated with the instance. You can update the shape only when the instance is in the shut_down state.
networking (Optional) Mapping of device name to network specifiers for virtual NICs to be attached to this instance. You can update the instance when it is either in the running state or shut_down state.
nis (Optional) Network Information Service (NIS) configuration. You can update the NIS configuration only when the instance is in the running state or shut_down state.

Note:

The nis parameter appears in two places in the instances definition. You must update the first occurrence.
tags (Optional) Instances can be tagged with a list of user-friendly strings that identify a specific instance. You can add tags to the instance in any state.

For more information on Instance optional parameters, see section Orchestration Templates in Using Oracle Compute Cloud Service.

Example URI

http://api.oc.example.com/instance/mytenant/public/func_storage_12/2/c041981f-99a6-4af2-a31d-b3dce1fe719f

Example Request Body


{
   "domain": "mytenant.public.host1.example.com.",
   "placement_requirements": ["/system/compute/placement/default",
   "/system/compute/allow_instances", "/system/infiniband/ready"],
   "ip": "192.168.120.4",
   "fingerprint": "",
   "site": "",
   "shape": "oc1",
   "nis": {"domain": "mytenant-domain", "servers": [{"ip": "111.11.11.111","name": "mytenant.nis.server1"}]},
   "imagelist": "/oracle/public/linux5_12.2.1.0.0_64",
   "networking": {"eth1": {"vnet": "/oracle/public/IPoIB-virt-admin",
   "dns": ["e47fdb.mytenant.public.host1.example.com."]}},
   "storage_attachments": [],
   "hostname": "e47fdb.mytenant.public.host1.example.com.",
   "quota_reservation": "/mytenant/cb4f9ecf-5ac7-4496-b8c9-26c10be8207c",
   "disk_attach": "",
   "label": "test2",
   "priority": "/oracle/public/default",
   "state": "shut_down",
   "virtio": false,
   "vnc": "10.0.0.49:5900",
   "tags": ["/mytenant/public/func_storage_12","78992f1753f37e2a687f743c0df14d38", "new tag"],
   "start_time": "2015-12-28T22:46:48Z",
   "quota": "/mytenant",
   "last_shutdown_time": null,
   "attributes":
    {
    "nis": {},
    "network": {"nimbula_vcable-eth1": {"net_config": {"owner": {"type": 
    "svcnet", "name": "IPoIB-virt-admin-2"}, "ip": "192.168.120.4",
    "netmask": "255.255.248.0", "type": "IPoIB", "membership": "limited"},
    "vethernet_id": "-1", "options": {}, "vethernet": 
    "/oracle/public/IPoIB-virt-admin", "address": [null, "192.168.120.4"],
    "model": "", "vethernet_type": "ipoib", "id": 
    "/mytenant/public/02855c15-c088-4f33-a120-dbe0c31388ae", "dhcp_options":[]}},
    "nimbula_orchestration": "/mytenant/public/func_storage_12",
    "dns": {"domain": "mytenant.public.host1.example.com.", "hostname": 
    "e47fdb.mytenant.public.host1.example.com.", "nimbula_vcable-eth1": 
    "e47fdb.mytenant.public.host1.example.com."},
    "sshkeys": []
    },
   "error_reason": null,
   "sshkeys": null,
   "resolvers": null,
   "account": "/mytenant/default",
   "name": 
   "/mytenant/public/func_storage_12/2/c041981f-99a6-4af2-a31d-b3dce1fe719f",
   "vcable_id": "/mytenant/public/02855c15-c088-4f33-a120-dbe0c31388ae",
   "uri": 
   "http://api.oc.example.com/instance/mytenant/public/func_storage_12/2/c041981f-99a6-4af2-a31d-b3dce1fe719f", 

   "reverse_dns": true,
   "entry": 1,
   "boot_order": []
}

Retrieve Instance Details

You can retrieve instance details by using the REST API.

Topics:

Discover Instances

This API request enables you to discover instances in the specific container and subcontainers.

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 the Accept 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

/instance/container/

URI

https://api_endpoint/instance/container/

URI Parameter

Parameter Description
container Hierarchical namespace containing instances

Example URI

https://api.oc.example.com/instance/mytenant/public/

Example Response Body

{"result": 
        [
                "/mytenant/public/primary_webserver/", 
                "/mytenant/public/secondary_webserver/"
        ]
}

Get Instance

This API request enables you to retrieve information for a specific instance.

Method

GET

REST Resource

/instance/name

URI

https://api_endpoint/instance/name

URI Parameter

Parameter Description
name A unique hierarchical name for an instance. For example, /mytenant/public/e6640ebc-6953-444f-848d-4a3bf6050ea5

Example URI

https://api.oc.example.com/instance/mytenant/public/dev1/f653a677-b566-4f92-8e93-71d47b364119

Example Response Body

{
 "list": [
  {
   "domain": "mytenant...",
   "placement_requirements": [
    "/system/compute/placement/default",
    "/system/compute/allow_instances"
   ],
   "ip": "10...",
   "site": "",
   "shape": "oc5",
   "imagelist": "/oracle/public/oel_6.4_60GB",
   "attributes": {
    "network": {
     "nimbula_vcable-eth0": {
      "vethernet_id": "0",
      "vethernet": "/oracle/public/default",
      "address": [
       "c6:b0:09:f4:bc:c0",
       "0.0.0.0"
      ],
      "model": "",
      "vethernet_type": "vlan",
      "id": "/mytenant/public/016e75e7-e911-42d1-bfe1-6a7f1b3f7908",
      "dhcp_options": []
     }
    },
    "dns": {
     "domain": "mytenant...",
     "hostname": "d06886.mytenant...",
     "nimbula_vcable-eth0": "d06886.mytenant..."
    },
    "sshkeys": [
     "ssh-rsa AAAAB3NzaC1yc2EAAA..."
    ]
   },
   "networking": {
    "eth0": {
     "model": "",
     "dns": [
      "d06886.mytenant..."
     ],
     "seclists": [
      "/mytenant/default/default",
      "/mytenant/public/prod-ng"
     ],
     "vethernet": "/oracle/public/default",
     "nat": "ipreservation:/mytenant/public/prod-vm1"
    }
   },
   "hostname": "d06886.mytenant...",
   "quota_reservation": "/mytenant/ffc8e6d4-8f93-41f3-a062-bdbb042c3191",
   "disk_attach": "",
   "label": "Production instance 1",
   "priority": "/oracle/public/default",
   "state": "running",
   "vnc": "10...",
   "storage_attachments": [
    {
     "index": 1,
     "storage_volume_name": "/mytenant/public/prod-vol1",
     "name": "/mytenant/public/dev1/f653a677-b566-4f92-8e93-71d47b364119/f1a67244-9abc-45d5-af69-8..."
    }
   ],
   "start_time": "2014-06-24T17:51:35Z",
   "quota": "/mytenant",
   "fingerprint": "19:c4:3f:2d:dc:76:b1:06:e8:88:bd:7f:a3:3b:3c:93",
   "error_reason": "",
   "sshkeys": [
    "/mytenant/public/mytenant-prod-admin"
   ],
   "tags": [
    "prod2"
   ],
   "resolvers": null,
   "account": "mytenant/default",
   "name": "/mytenant/public/dev1/f653a677-b566-4f92-8e93-71d47b364119",
   "vcable_id": "/mytenant/public/016e75e7-e911-42d1-bfe1-6a7f1b3f7908",
   "uri": "http://10....",
   "reverse_dns": true,
   "entry": 1,
   "boot_order": []
  }
 ]
}

List Instances

This API request enables you to retrieve instance information in a specific container or subcontainer.

Method

GET

REST Resource

/instance/container/

URI

https://api_endpoint/instance/container/?tags=tagValue&quota=quotaValue&vcable_id=vcable_idValue

URI Parameters

Parameters Description
container Hierarchical name-space for instances
tags=tagValue (Optional) Instances can be tagged with a list of user-friendly strings that identify a specific instance
quota=quotaValue (Optional) The name of a quota associated with an instance
vcable_id=vcable_idValue (Optional) The unique identifier of a virtual cable (vCable) associated with an instance

Example URI

https://api.oc.example..com/instance/mytenant/

Example Response Body

{
"result": 
        [{
                "domain": "mytenant.public.oc.example.com.",
                "placement_requirements": ["/system/compute/placement/default", 
                "/system/compute/allow_instances", 
                "/system/infiniband/ready"], 
                "ip": "10.128.206.94", 
                "fingerprint": "08:8f:8f:f9:f4:3c:19:ee:11:3c:0a:1f:fd:ee:1d:e9", 
                "site": "", 
                "shape": "oc3", 
                "nis": {}, 
                "imagelist": null, 
                "networking": {"eth0": {"seclists": [], 
                "vnetreservation": "/mytenant/public/instance1-wls-vm-1-instance1-wls-1-svcnet-1", 
                "options": 
                {
                        "hostname": "instance1-wls-1", 
                        "network_route": [], 
                        "dns": {"search_domains": "mytenant.public.oc.example.com", "servers": "192.168.126.1,192.168.126.2"}
                }, 
                "dns": [], 
                "address": []}, "eth4": {"seclists": [], "vnet": "/cloud/public/EoIB-OMS-c2", "dns": [], "address": []
............
}