Virtual machine snapshot and restore API

Edit online

The snapshot and restore API lets you create a point in time snapshots of the volumes or disks attached to a virtual machine (instance) and lets you revert the same to any instance snapshot created. The API capabilities include creating or removing instance snapshots, updating name and description of instance snapshots, retrieving information about all or instance snapshot and restore to any instance snapshot.

Instance snapshot and restore API options
Create an instance snapshot
Get list of all instance snapshots
Get details of an instance snapshot
Delete an instance snapshot and associated volumes
Update instance snapshot details
Get progress of instance snapshot
Restore instance
Retry instance snapshot restore
Rollback instance snapshot restore
Check FlashCopy mappings

Instance snapshot and restore API options

Table 1. Options for snapshot and restore API
Method	URI	Description
POST	`/compute/v2.1/{tenant_id}/servers/{server_id}/action`	Creates instance snapshot.
GET	`/volume/v3/{tenant_id}/instance-snapshots`	Gets a list of all instance snapshots.
GET	`/volume/v3/{tenant_id}/instance-snapshots/{instance_snapshot_id}`	Shows details of instance snapshot.
DELETE	`/volume/v3/{tenant_id}/instance-snapshots/{instance_snapshot_id}`	Deletes the instance snapshot and its associated volume snapshots in the backend.
PUT	`/volume/v3/{tenant_id}/instance-snapshots/{instance_snapshot_id}`	Updates the name and description of the instance snapshot.
GET	`/volume/v3/{tenant_id}/instance-snapshots/get_progress?action={action)&task_id={task_id}&id={instance_snapshot_id}`	Gets the progress of the instance snapshot.
POST	`/compute/v2.1/{tenant_id}/servers/{server_id}/action`	Restores the instance snapshot.
POST	`/compute/v2.1/{tenant_id}/servers/{server_id}/action`	Retries restore on failed snapshots of the instance snapshot. Retry operation can be done only when instance-snapshot status is restore-error.
POST	`/compute/v2.1/{tenant_id}/servers/{server_id}/action`	Rollback to back up snapshots taken before restore operation is performed. Rollback can be done only when instance-snapshot status is restore-error.
POST	`volume/v3/{tenant_id}/volumes/{volume_id}/action`	Check running FlashCopy® mappings for a volume.

Create an instance snapshot

This operation creates an instance snapshot. Instance snapshot is a point in time snapshot of the volumes attached to it. If volumes are not provided in the request, by default attaches all volumes to the instance while creating a snapshot. This API takes snapshot name, description and volumes details in the request body. The response body contains the task URI that can be used to monitor the progress of snapshot and restore operations.

Response codes

Normal response code: OK (200)
Error response code: Bad Request (400®), Forbidden (403), Not Found(404), Server Error (500)

Request parameters

Table 2. Parameters in the request for creating an instance snapshot
Name	Style	Type	Description
`name`	body	string	Name of the instance snapshot.
`description`	body	string	Description of instance snapshot.
`volumes`	body	list of strings	List of volumes associated with the instance snapshot.

Request body

{"vm-snapshot" :
            {"name": "VM_snapshot_1",
             "description": "VM_snapshot_desc",
             "volumes":
                ["1263e736-d648-473c-946e-6333f6018aa7", "13e7d54d-1a9f-4979-af30-c2bf12f6e118"]             }
         }

Table 3. Parameters in the response for creating an instance snapshot
Name	Style	Type	Description
`task_uri`	body	string	For long running instance snapshot or restore API operations, the link to the task URI is returned that can be used to monitor the progress of snapshot and restore operations.
`id`	body	integer	Specifies the instance snapshot ID.

Response body

{
  "instance_snapshot": {
    "task_uri": "https://ip9-114-192-242.pok.stglabs.ibm.com:9000/v3/38d2d7a82d9c4142a295298087bf9459/instance-snapshots/get_progress?action=snapshot&task_id=84a0bb4d-4644-40b0-b45a-00d2d0d75b2a&id=88fd0192-26db-47fc-b77e-6e8c8e8cf67f",
    "id": "88fd0192-26db-47fc-b77e-6e8c8e8cf67f"
  }
}

Get list of all instance snapshots

This operation fetches a list of all instance snapshots. This API does not take any request body. The response body contains details of instance snapshots, instance ID, failed snapshots, temporary snapshot the task URI.

Response codes

Normal response code: OK (200)
Error response code: Unauthorized (401)

Response body

Table 4. Parameters in response for list of all instance snapshots
Name	Style	Type	Description
`status`	body	string	Status of instance snapshot
`name`	body	string	Name of the instance snapshot.
`temp_snapshots`	body	dict of volume_id and snapshot_id pairs	Before performing the restore operation, temporary snapshot, and copy is taken for each volume, which can be used to rollback if restore fails. When `vm-restore` API is called with rollback flag, it uses `temp_snapshots` to recover the instance.
`created_at`	body	string	The date and time when an instance snapshot is created.
`updated_at`	body	list of strings	The date and time when an instance snapshot is updated.
`snapshots`	body	dict of volume_id and snapshot_id pairs	A dict of volume_id and snapshot_id pairs, where it stores the snapshot IDs for the volumes that are included during instance snapshot.
`instance_id`	body	integer	Specifies the instance snapshot ID.
`failed_snapshots`	body	dict of volume_id and snapshot_id pairs	Any snapshots that failed during restore are stored under this parameter as dict of volume_id and snapshot_id pairs. If a user requests `vm-restore` API with retry flag, restore operation is performed again only on failed-snapshots.
`task_uri`	body	string	For long running instance snapshot or restore API operations, the link to the task URI is returned that can be used to monitor the progress of snapshot and restore operations.
`id`	body	string	For long running instance snapshot or restore API operations, the link to the task URI is returned that can be used to monitor the progress of snapshot and restore operations.
`description`	body	string	Description of the instance snapshot.

{
    "instance_snapshots": [
        {
            "status": "available",
            "name": "Pun_VM_IS-1",
            "temp_snapshots": null,
            "created_at": "2020-01-14T07:27:39.000000",
            "updated_at": "2020-01-14T07:28:06.000000",
            "snapshots": {
                "fc75cfd9-c107-4e73-95cc-ba20770f367c": "71431a96-31ae-45b1-a461-a2ca78048734",
                "815089e3-9fac-4a4e-b2fa-8b40f0581b56": "4b3fcec4-5060-4a1c-9e6b-fbfef0daf353",
                "b5b6a39f-ccdf-49f2-a600-9569eb57f34b": "934bbb98-081e-4e4e-a14f-591454427ab0"
            },
            "instance_id": "b90d8d4d-2608-49f4-8f0b-5646ce904c65",
            "failed_snapshots": null,
            "task_uri": "https://jupiter-vm813.pok.stglabs.ibm.com:9000/v3/ab299b445ec74c28b680c7691b76a310/instance-snapshots/get_progress?action=snapshot&task_id=1032515d-5e12-4ee2-9ea1-fff18f5aae11&id=6ab89abd-3de9-48cf-9ded-b4d6ab7d9169",
            "id": "6ab89abd-3de9-48cf-9ded-b4d6ab7d9169",
            "description": "2st"
        },
        {
            "status": "available",
            "name": "Pun_VM_IS-2",
            "temp_snapshots": null,
            "created_at": "2020-01-14T07:25:26.000000",
            "updated_at": "2020-01-14T07:25:54.000000",
            "snapshots": {
                "f53c6939-aa04-4df2-88c1-bbf28472384c": "557f4f3a-4bf9-46c1-91c1-5ede90757008",
                "df317597-342d-4cf9-a53c-669c6d0259a8": "83f1102e-6f8e-448a-956f-3966a08cfe2e",
                "77675796-6e95-4f44-8388-ff3db240465d": "d388cec8-6e0a-4e9d-b6a3-9c72200a9631"
            },
            "instance_id": "1bec92a4-e300-43b4-aead-7d0af0aeb051",
            "failed_snapshots": null,
            "task_uri": "https://jupiter-vm813.pok.stglabs.ibm.com:9000/v3/ab299b445ec74c28b680c7691b76a310/instance-snapshots/get_progress?action=snapshot&task_id=37e5b695-fc60-4959-b563-c992509fb0cb&id=a1c1d141-a593-42d8-b954-b16183483f14",
            "id": "a1c1d141-a593-42d8-b954-b16183483f14",
            "description": "2st"
        }
    ]
}

Get details of an instance snapshot

This operation fetches details of an instance snapshot. This API does not take any request body. The response body contains details of instance snapshots, instance ID, failed snapshots, temporary snapshot, and the task URI.

Response codes

Normal response code: OK (200)
Error response code: Unauthorized (401), Not Found (404)

Response body

Table 5. Parameters in the response to get details of an instance snapshot
Name	Style	Type	Description
`status`	body	string	Status of instance snapshot
`name`	body	string	Name of the instance snapshot.
`temp_snapshots`	body	dict of volume_id and snapshot_id pairs	Before performing the restore operation, temporary snapshot copy is taken for each volume, which can be used to rollback if restore fail. When `vm-restore` API is called with rollback flag, it uses `temp_snapshots` to recover the instance.
`created_at`	body	string	The date and time when an instance snapshot is created.
`updated_at`	body	string	The date and time when an instance snapshot is updated.
`snapshots`	body	dict of volume_id and snapshot_id pairs	A dict of volume_id and snapshot_id pairs, where it stores the snapshot IDs for the volumes that are included during instance snapshot.
`instance_id`	body	integer	Specifies the instance snapshot ID.
`failed_snapshots`	body	dict of volume_id and snapshot_id pairs	Any snapshots that failed during restore are stored under this parameter as dict of volume_id and snapshot_id pairs. If a user requests `vm-restore` API with retry flag, restore operation is performed again only on failed-snapshots.
`task_uri`	body	string	For long running instance snapshot or restore API operations, the link to the task URI is returned that can be used to monitor the progress of snapshot and restore operations.
`id`	body	string	For long running instance snapshot or restore API operations, the link to the task URI is returned that can be used to monitor the progress of snapshot and restore operations.
`description`	body	string	Description of the instance snapshot.

{
    "instance_snapshot": {
            "status": "available",
            "name": "Pun_VM_IS-1",
            "temp_snapshots": null,
            "created_at": "2020-01-14T07:27:39.000000",
            "updated_at": "2020-01-14T07:28:06.000000",
            "snapshots": {
                "fc75cfd9-c107-4e73-95cc-ba20770f367c": "71431a96-31ae-45b1-a461-a2ca78048734",
                "815089e3-9fac-4a4e-b2fa-8b40f0581b56": "4b3fcec4-5060-4a1c-9e6b-fbfef0daf353",
                "b5b6a39f-ccdf-49f2-a600-9569eb57f34b": "934bbb98-081e-4e4e-a14f-591454427ab0"
            },
            "instance_id": "b90d8d4d-2608-49f4-8f0b-5646ce904c65",
            "failed_snapshots": null,
            "task_uri": "https://jupiter-vm813.pok.stglabs.ibm.com:9000/v3/ab299b445ec74c28b680c7691b76a310/instance-snapshots/get_progress?action=snapshot&task_id=1032515d-5e12-4ee2-9ea1-fff18f5aae11&id=6ab89abd-3de9-48cf-9ded-b4d6ab7d9169",
            "id": "6ab89abd-3de9-48cf-9ded-b4d6ab7d9169",
            "description": "2st"
        },
        {
            "status": "available",
            "name": "Pun_VM_IS-2",
            "temp_snapshots": null,
            "created_at": "2020-01-14T07:25:26.000000",
            "updated_at": "2020-01-14T07:25:54.000000",
            "snapshots": {
                "f53c6939-aa04-4df2-88c1-bbf28472384c": "557f4f3a-4bf9-46c1-91c1-5ede90757008",
                "df317597-342d-4cf9-a53c-669c6d0259a8": "83f1102e-6f8e-448a-956f-3966a08cfe2e",
                "77675796-6e95-4f44-8388-ff3db240465d": "d388cec8-6e0a-4e9d-b6a3-9c72200a9631"
            },
            "instance_id": "1bec92a4-e300-43b4-aead-7d0af0aeb051",
            "failed_snapshots": null,
            "task_uri": "https://jupiter-vm813.pok.stglabs.ibm.com:9000/v3/ab299b445ec74c28b680c7691b76a310/instance-snapshots/get_progress?action=snapshot&task_id=37e5b695-fc60-4959-b563-c992509fb0cb&id=a1c1d141-a593-42d8-b954-b16183483f14",
            "id": "a1c1d141-a593-42d8-b954-b16183483f14",
            "description": "2st"
        }
}

Delete an instance snapshot and associated volumes

The operation deletes an instance snapshot and the volume snapshots that are associated with it in the backend. This API does not take any request body. The response body contains the task URI that can be used to monitor the progress of snapshot and restore operations.

Response codes

Normal response code: OK (200)
Error Response Codes: Unauthorized (401), Not Found (404)

Response body

Table 6. Parameters in the response to delete an instance snapshot and associated volumes
Name	Style	Type	Description
`task_uri`	body	string	For long running instance snapshot or restore API operations, the link to the task URI is returned that can be used to monitor the progress of snapshot and restore operations.

Example:

{"task_uri": "https://jupiter-vm813.pok.stglabs.ibm.com:9000/v3/ab299b445ec74c28b680c7691b76a310/instance-snapshots/get_progress?action=delete&task_id=37e5b695-fc60-4959-b563-c992509fb0cb&id=a1c1d141-a593-42d8-b954-b16183483f14"}

Update instance snapshot details

The operation updates details of instance snapshot such as name and description. This API takes the instance snapshot name and description that you want to change. The response body contains the instance snapshot ID whose attributes are updated by the request.

Response codes

Normal response code: OK (200)
Error Response Codes: Unauthorized (401), Not Found (404)

Request parameters

Table 7. Parameters in the request to update snapshot details
Name	Style	Type	Description
`name`	body	string	Instance snapshot name.
`description`	body	string	Description of the instance snapshot.

Example:


{
    "instance-snapshot": {
        "name": "PUT_name",
        "description": " PUT request test"
    }
}

Response body

Table 8. Parameters in the response to update instance snapshot details
Name	Style	Type	Description
`id`	body	integer	Specifies the instance snapshot ID.

Example:

{'instance_snapshot': {'id': "a1c1d141-a593-42d8-b954-b16183483f14"}}

Get progress of instance snapshot

The operation fetches details about the progress of instance snapshot and restore operations. This API does not take any request body. The response body contains details such as progress of a task, whether creating or updating a snapshot is completed, or if there are any pending tasks.

Response codes

Normal response code: No Content (204)
Error Response Codes: Unauthorized (401), Not Found(404)

Response parameters

Table 9. Parameters in the response to get progress of instance snapshot
Name	Style	Type	Description
`progress`	body	integer	Specifies the progress of snapshot or restore operation in percentage.
`flow_details`	body	dict of task flow and status	Details of task flow and status.
`completed_tasks`			Details and status of tasks completed.
`pending_tasks`			Details of pending tasks, if any.

Example:

{
  "details": {
    "progress": 100,
    "flow_details": {
      "InstSnapshotFlow": "SUCCESS"
    },
    "completed_tasks": {
      "SnapshotDone": "SUCCESS",
      "creating_snapshot": "SUCCESS",
      "updating_snapshots": "SUCCESS",
      "powervc_cinder.volume.tasks.snapshots.CreateSnapshot": "SUCCESS"
    },
    "pending_tasks": {}
  }
}

Restore instance

The operation resets an instance snapshot. The API takes instance snapshot ID in the request body and in the response body returns the task URI that can be used to monitor the progress of snapshot and restore operations.

Response codes

Normal response code: OK (202)
Error Response Codes: Bad Request (400), Forbidden (403), Not Found (404), Server Error (500)

Request parameters

Table 10. Parameters in the request to restore instance snapshot
Name	Style	Type	Description
`instance_snapshot_id`	body	integer	Each string contains data about a virtual machine to manage or prepare for management.
`force`	body	Boolean	Optional value. When force is set to True, restore operation is performed without shutting off the virtual machine. Default value is False.

Example:


{"vm-restore" : {"instance_snapshot_id" : "44fbf6f8-988d-4510-85a7-1393d990d188", "force": "True"}}

Response body

Table 11. Parameters in the response to restore instance snapshot
Name	Style	Type	Description
`task_uri`	body	string	For long running instance snapshot or restore API operations, the link to the task URI is returned that can be used to monitor the progress of snapshot and restore operations.

Example:

{
  "task_uri": "https://jupiter-vm801.pok.stglabs.ibm.com:9000/v3/9cc7780e57bb45c5b4e85dccb0a075a2/instance-snapshots/get_progress?action=restore-retry&task_id=66ed930c-2235-4bea-a819-7a52d9e98d7d&id=49ad40bb-298b-4f8b-b443-7ee549b1ebc3"
}

Retry instance snapshot restore

The operation is performed to retry restoring a failed instance snapshot. The API takes instance snapshot ID in the request body and in the response body returns the task URI that can be used to monitor the progress of snapshot and restore operations.

Note: Retry operation can be performed only when instance-snapshot status is restore-error.

Response codes

Normal response code: OK (202)
Error Response Codes: Bad Request (400), Forbidden (403), Not Found (404), Server Error (500)

Request parameters

Table 12. Parameters in the request to retry instance snapshot restore
Name	Style	Type	Description
`instance_snapshot_id`	body	integer	Each string contains data about a virtual machine to manage or prepare for management.
`force`	body	Boolean	Optional value. When force is set to True, restore operation is performed without shutting off the virtual machine. Default value is False.
`retry`	body	Boolean	Optional value. Default value is False. Set retry parameter to true to perform retry restore operation.

Example:


body = {"vm-restore" :
            {"instance_snapshot_id": "uuid",
             "retry": True,
             "force": True}
         }

Response body

Table 13. Parameters in the response to restore instance snapshot
Name	Style	Type	Description
`task_uri`	body	string	For long running instance snapshot or restore API operations, the link to the task URI is returned that can be used to monitor the progress of snapshot and restore operations.

Example:

{
  "task_uri": "https://jupiter-vm801.pok.stglabs.ibm.com:9000/v3/9cc7780e57bb45c5b4e85dccb0a075a2/instance-snapshots/get_progress?action=restore-retry&task_id=66ed930c-2235-4bea-a819-7a52d9e98d7d&id=49ad40bb-298b-4f8b-b443-7ee549b1ebc3"
}

Rollback instance snapshot restore

The operation is performed to rollback to back up snapshots taken before restore operation is performed. The API takes instance snapshot ID in the request body and in the response body returns the task URI that can be used to monitor the progress of snapshot and restore operations.

Note: Rollback operation can be performed only when instance-snapshot status is restore-error.

Response codes

Normal response code: OK (202)
Error Response Codes: Bad Request (400), Forbidden (403), Not Found (404), Server Error (500)

Request parameters

Table 14. Parameters in the request to rollback instance snapshot restore
Name	Style	Type	Description
`instance_snapshot_id`	body	integer	Each string contains data about a virtual machine to manage or prepare for management.
`force`	body	Boolean	Optional value. When force is set to True, restore operation is performed without shutting off the virtual machine. Default value is False.
`rollback`	body	Boolean	Optional value. Default value is False. Set rollback parameter to true to perform rollback operation.

Example:


body = {"vm-restore" :
            {"instance_snapshot_id": "uuid",
             "rollback": True,
             "force": True}
         }

Response body

Table 15. Parameters in the response to rollback instance snapshot restore
Name	Style	Type	Description
`task_uri`	body	string	Internally generated identifier that is used to look up the task results of the manage action.
`name`	body	string	Name the storage provider.

Example:

{
  "task_uri": "https://jupiter-vm801.pok.stglabs.ibm.com:9000/v3/9cc7780e57bb45c5b4e85dccb0a075a2/instance-snapshots/get_progress?action=restore-rollback&task_id=66ed930c-2235-4bea-a819-7a52d9e98d7d&id=49ad40bb-298b-4f8b-b443-7ee549b1ebc3"
}

Check FlashCopy mappings

The operation checks FlashCopy mappings for a volume. This API is only applicable for Storewize volume driver and not supported for other storages. The API response body returns the task status, FlashCopy mapping name, restore operation progress, name of source and target disks, etc.

Response codes

Normal response code: OK (202)
Error Response Codes: Bad Request (400), Forbidden (403), Not Found (404), Server Error (500)

Request parameters

Table 16. Parameters in the request to check FlashCopy mappings for a volume
Name	Style	Type	Description
`copy-progress`	body	string	Checks the status of FlashCopy mappings for a volume.
`details`	body	Boolean	Default value is `False`. To view all the properties for FlashCopy mapping , set this value to `True`.

Example:


{"copy-progress":{}
}

Response body

Table 17. Parameters in the response to check FlashCopy mappings for a volume
Name	Style	Type	Description
`status`	body	string	TBD
`name`	body	string	Specifies name of the FlashCopy mapping for a volume.
`restore_prgress`	body	Integer	Specifies details about the progress of restore operation.
`target_vdisk_name`	body	string	Specifies the name of the target volume.
`incremental`	body	string	Specifies whether incremental copy is set to on or off. This parameter copies entire data when a user first initiates FlashCopy. Later, when the users stop and restarts the copy operation, copies only specific changes.
`source_vdisk_name`	body	string	Specifies the name of the source volume.
`progress`	body	integer	Specifies status of FlashCopy mappings for a volume.
`copyrate`	body	integer	Specifies the priority given to complete the copy. The copyrate determines how quickly the cluster copies data from the source volume to the target volume.
`restoring`	body	string	Specifies whether a restore operation is in progress.

Example:


{
  "copy_details": [{
    "status": "copying",
    "name": "fcmap265",
    "restore_progress": null,
    "target_vdisk_name": "snapshot-Cha01-3-bulk-1-35f0906b",
    "incremental": "off",
    "source_vdisk_name": "volume-bulk-1-fb338692-90f3",
    "progress": "0",
    "copyrate": null,
    "restoring": "no"
  }, {
    "status": "copying",
    "name": "fcmap1390",
    "restore_progress": null,
    "target_vdisk_name": "snapshot-jag7snap_3-bulk-1-d29ef74d",
    "incremental": "off",
    "source_vdisk_name": "volume-bulk-1-fb338692-90f3",
    "progress": "0",
    "copyrate": null,
    "restoring": "no"
  }}