Managing Snapshots

A snapshot is a copy of the machine image boot disk taken at a specific time from an instance that is in running or shutdown state. You can add this copy to image lists, and use it to create a new instance.

Instance modifications are not preserved when an instance is deleted as a result of stopping an orchestration. Deleting an instance also removes all customizations and changes made to the boot disk since its creation. To keep the customized virtual machine (VM), create a snapshot to preserve the machine image. Then use the snapshot to create new VMs with the same customizations.

Note:

Another way to preserve customizations is to shut down that instance to free CPU and memory resources. When the VM is restarted, its customizations remain in effect. For more information about shutting down VM, see Shutdown Instance.

Topics:

Add Snapshot

This API enables you to add a snapshot.

Method

POST

REST Resource

/snapshot/

URI

https://api_endpoint/snapshot/

Request Body Parameters

Parameter	Description
instance	Instance for which snapshot must be taken
name	(Optional) Unique identifier of the Snapshot which replaces the identifier generated by the server. Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.
quota	(Optional) Quota against which this snapshot will be stored
machineimage	(Optional) Unique identifier of the machine image. If you do not provide this option, then the unique identifier is generated by the server.

Example URI

https://api.oc.example.com/snapshot/

Example Request Body

{
  "instance": "/mytenant/administrator/a6fbb572-a584-486a-9314-56a24499028d",
  "name": null, 
  "quota": null, 
  "machineimage": "/mytenant/administrator/snapshot1"
}

Delete Snapshot Request

This API enables you to delete a snapshot creation request. This deletes only the request; the machine image that was the result of the request is not removed.

The following restrictions apply for deleting a snapshot request:

Requests in the active state cannot be deleted.
Requests can only be deleted when they are in the error or complete state.

Method

DELETE

REST Resource

/snapshot/name

URI

https://api_endpoint/snapshot/name

URI Parameter

Parameter	Description
name	Snapshot unique identifier

Example URI

https://api.oc.example.com/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec

Retrieve Snapshot Details

You can retrieve the snapshot details by using the REST APIs.

Topics:

Discover Snapshots

This API enables you to discover snapshots in a specific container.

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

/snapshot/container/

URI

https://api_endpoint/snapshot/container/

URI Parameter

Parameter	Description
container	Hierarchical name-space for snapshots

Example URI

https://api.oc.example.com/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/

Example Response Body

{"result": 
        [
                "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec", 
                "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/df8caca5-8a27-4153-9c5f-7440080b40c8"
        ]
}

Get Snapshot

This API enables you to retrieve details for a specific snapshot.

Method

GET

REST Resource

/snapshot/name

URI

https://api_endpoint/snapshot/name

URI Parameter

Parameter	Description
name	Snapshot unique identifier

Example URI

https://api.oc.example.com/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec

Example Response Body

{
"instance_id": "a6fbb572-a584-486a-9314-56a24499028d",
"account": "/mytenant/default", 
"platform": "linux", 
"name": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec", 
"client_owned": true, 
"sizes": {}, 
"creation_time": "2015-08-20T06:54:58Z", 
"uri": "https://10.32.80.5/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec", 
"quota": null, 
"delay": "", 
"instance": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d", 
"machineimage": "/mytenant/public/snapshot1", 
"state": "complete", 
"quota_reservation": null, 
"user": "/mytenant/public", 
"file": "hdfs:///bimage/a6fbb572-a584-486a-9314-56a24499028d-4dbb2b4c-d315-47ba-b938-696f74826bec-snapshot.tar.gz", 
"request_id": "4dbb2b4c-d315-47ba-b938-696f74826bec", 
"error_reason": "", 
"image_format": "raw"
}

List Snapshots

This API enables you to list information about snapshots in a specific container.

Method

GET

REST Resource

/snapshot/{container |name}

URI

https://api_endpoint/snapshot/container | name?quota=quotaValue&instance=instanceValue&machineimage=machineimageValue

URI Parameters

Note:

The output of this command is filtered based on the optional parameters (if specified).

Parameter	Description
container	Hierarchical namespace for snapshots
name	(Optional) Unique identifier of the Snapshot which replaces the identifier generated by the server
quota=quotaValue	(Optional) Quota against which this snapshot is stored
instance=instanceValue	(Optional) Instance for which the snapshot should to be taken
machineimage=macineimageValue	(Optional) Unique identifier of the machine image. If you do not provide this option, then the unique identifier is generated by the server.

Example URI

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

Example Response Body

{"result":[
 {
  "instance_id": "a6fbb572-a584-486a-9314-56a24499028d",
  "account": "/mytenant/default", 
  "platform": "linux", 
  "name": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec", 
  "client_owned": true, 
  "sizes": {}, 
  "creation_time": "2015-08-20T06:54:58Z", 
  "uri": "https://api.ic.example.com/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec", 
  "quota": null, 
  "delay": "", 
  "instance": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d", 
  "machineimage": "/mytenant/public/snapshot1", 
  "state": "complete", 
  "quota_reservation": null, 
  "user": "/mytenant/public", 
  "file": "hdfs:///bimage/a6fbb572-a584-486a-9314-56a24499028d-4dbb2b4c-d315-47ba-b938-696f74826bec-snapshot.tar.gz", 
  "request_id": "4dbb2b4c-d315-47ba-b938-696f74826bec", 
  "error_reason": "", 
  "image_format": "raw"
 },
{
  "instance_id": "a6fbb572-a584-486a-9314-56a24499028d",
  "account": "/mytenant/default", 
  "platform": "linux", 
  "name": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/0b0ef87a-a7c8-46b3-8cdc-3315a203a431", 
  "client_owned": true, 
  "sizes": {}, 
  "creation_time": "2015-08-20T06:54:58Z", 
  "uri": "https://api.oc.example.com/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/0b0ef87a-a7c8-46b3-8cdc-3315a203a431", 
  "quota": null, 
  "delay": "shutdown", 
  "instance": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d", 
  "machineimage": "/mytenant/public/snapshot2", 
  "state": "active", 
  "quota_reservation": null, 
  "user": "/mytenant/public", 
  "file": "hdfs:///bimage/a6fbb572-a584-486a-9314-56a24499028d-0b0ef87a-a7c8-46b3-8cdc-3315a203a431-snapshot.tar.gz", 
  "request_id": "0b0ef87a-a7c8-46b3-8cdc-3315a203a431", 
  "error_reason": "", 
  "image_format": "raw"
 }
]}