Clone volume API

The clone volume API lets you create a consistent copy of volumes that are available or attached to a virtual machine.

Clone volume API options

Table 1. Options for clone volume API
Method	URI	Description
POST	`/v3/<tenant_id>/clone-volumes`	The clone volumes API creates consistent cloned copies of given volumes.
GET	`/v3/{tenant_id}/clone-volumes/get_progress?action=clone-volumes&task_id={task_id}`	Gets the progress of the clone volumes.

Clone volumes API

This operation creates consistent cloned copy of volumes provided in the request body. This API takes display-name, description, volumes and target-volume-type-id in the request body. The response body contains the task URI that can be used to monitor the progress of clone volumes and to get the details of clone volume IDs.

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 cloning a volume
Name	Style	Type	Description
`display-name`	body	string	Display name used with ‘clone-' prefix to identify the cloned volumes. Refer to Cloned Volume – Naming Format for details.
`description`	body	string	Description of cloned volumes in case of single volume clone.
`volumes`	body	list of strings	Set of volumes to create cloned volumes.
`target-volume-type-id`	body	string	Cloned volumes will be created with new `target-volume-type-id provided`.

{
    "clone-volumes”: {
        "display-name": "display_name",
        "description": "description",
        "volumes": ["714a7ea5-4ec1-4272-81ec-c806973bc45b",
                    "714a8ea5-8abd-4367-91ec-bcf06973bc67"],
        "target-volume-type-id": "9577a6ab-d726-470c-a556-928a9a5af963"
    }
}

Response body

Table 3. Parameters in the response for clone volumes
Name	Style	Type	Description
`task_uri`	body	string	For long running clone volume API operations, the link to the task URI is returned that can be used to monitor the progress of clone volume operations.

{
  "clone-volumes": {
    "task_uri": "https://<powervc-hostname>:9000/v3/38d2d7a82d9c4142a295298087bf9459/clone-volumes/get_progress?action=clone-volumes&task_id=84a0bb4d-4644-40b0-b45a-00d2d0d75b2a
  }
}

Get progress of clone volumes

The operation fetches details about the progress of clone volumes operation and the cloned volumes created. This API does not take any request body. The response body contains details such as progress of a task, details of cloned volume IDs, whether task is completed successfully or failed.

Response codes

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

Response body

Table 4. Parameters in the response to get progress of clone volumes
Name	Style	Type	Description
`progress`	body	integer	Specifies the progress of clone operation in percentage.
`flow_details`	body	Dict of task flow and status	Details of task flow and status. Refer to Use cases for details.
`completed_tasks`	body	Dict of task details and status	Details and status of tasks completed.
`pending_tasks`	body	Dict of tasks status	Details of pending tasks, if any.
`results`	body	List of strings	Dictionary of source volume ID and clone volume ID.

{
	"details": {
		"results": {
			"60c31a2f-c6a0-40bf-9a89-0d8537c291e3": "f71c14a9-7d4e-473e-81d8-2ee86c3ad32b",
			"e58efc63-2906-49aa-935c-c78566b8e427": "bca9d8d9-1ece-4a1c-8c13-95a7fd920892"
		},
		"completed_tasks": {
			"create_group_clone-clone-DEL-a8584df2": "SUCCESS",
			"wait_for_group_snapshot_7cd566e9-ca88e5fc": "SUCCESS",
			"delete_group-tgt_grp-4346a777": "SUCCESS",
			"set_metadata_for_volume-a34d70ec": "SUCCESS",
			"remove_vols_from_src_grp-109b51d1": "SUCCESS",
			"wait_for_src_group_RemoveVolumesFromGroup-8c746a31": "SUCCESS",
			"get_clones_from_group-9dc6ed50": "SUCCESS",
			"wait_for_tgt_grp_delete-f4ebf6a4": "SUCCESS",
			"remove_vols_from_tgt_grp-8cc7fb55": "SUCCESS",
			"create_group_snapshot_7cd566e9-4c83ba51": "SUCCESS",
			"wait_for_vol_update_in_group-83ad6bb3": "SUCCESS",
			"delete_group_snapshot-b7b3f1bb": "SUCCESS",
			"add_vols_to_group-843f9360": "SUCCESS",
			"create_group_type_7cd566e9-e679d360": "SUCCESS",
			"delete_group-src_group-be460ab7": "SUCCESS",
			"delete_group_type-3e2e85ec": "SUCCESS",
			"wait_for_src_vol_group_-920b5398": "SUCCESS",
			"create_src_vol_group_7cd566e9-a912df19": "SUCCESS",
			"wait_for_src_grp_delete-fcd838c1": "SUCCESS",
			"wait_for_group_AddVolsToGroup-450c0200": "SUCCESS",
			"_TaskFlow_INJECTOR": "SUCCESS"
		},
	},
	"pending_tasks": {},
	"progress": 100,
	"flow_details": {
		"cloneFlow": "SUCCESS",
	}
}
}

Use cases

In case of success, results field is updated with clone volume IDs and clone flow is in SUCCESS state.

{
	"details": {
		"results": {
			"vol_id_1": "clone_vol_id_1",
			"vol_id_2": "clone_vol_id_2"
		},
		"progress": 100,
		"flow_details": {
			"cloneFlow": "SUCCESS"
		}
	}
}

In case of failure, results field is updated with failure message and clone flow is in REVERTED state.

{
	"details": {
		"results": {
			"failure": "failure message"
		},
		"progress": 100,
		"flow_details": {
			"cloneFlow": "REVERTED"
		}
	}
}

Cloned Volume – Naming Format

Group volume clone prefix

Group volume clone prefix is used to give the user friendly name to identify the clone volume name. By default this value is set as clone-. User can configure this value using the powervc-config CLI powervc-config storage clone-name-prefix. Example given below:

group_volume_clone_prefix= “clone-

Single volume - naming format

Table 5. Naming format for single volume
Display-name	Without Display-name
<clone_prefix>-<display-name>	<clone_prefix>-<sourcevolume_displayname>
Clone-prefix = “clone-” (default) Source_volume name = “srcvol1” Display_name = “demo” Cloned-volume name : “clone-demo”	Clone-prefix = “clone-” (default) Source_volume name = “srcvol1” Clone-volume name: “clone-srcvol1”

Multiple volume - naming format

Table 6. Naming format for single volume
Display-name	Without Display-name
<clone_prefix>-<display-name>-<idx>idx – count	volume-<cloned_volume_id>
Clone-prefix = “clone-” (default) Display_name = “demo” Volume count = 3 Cloned-volume name : “clone-demo-1” “clone-demo-2” “clone-demo-3”	Volume count = 3 Clone-volume name: “volume-<cloned_volume_id>” “volume-<cloned_volume_id>” “volume-<cloned_volume_id>”