Snapshots, restoring, and cloning

IBM Power Virtual Server in IBM data center

IBM Power Virtual Server Private Cloud in Client location

IBM® Power® Virtual Server provides the capability to capture full, point-in-time copies of entire logical volumes or data sets. Using IBM's FlashCopy feature, Power® Virtual Server APIs you can create delta snapshots, volumes-clones, and restore your disks.

Creating a Snapshot

A snapshot is a copy of the state of a volume or a set of volumes that is taken at a specific time. By using snapshot, you can restore your volumes to the state when you took the snapshot.

Prerequisites

Before you take a snapshot of a volume, it is recommended that you quiesce all the applications that access the volume. This action is required to ensure that all the data is moved to the disk to avoid loss of data.
If you are creating a snapshot of a volume that is shared among multiple virtual server instances (VMs) then you must quiesce all the applications on all these VMs. If you are not sure how to quiesce your applications, it is recommended to shut down any VMs attached to the volumes that you want to include in the snapshot.
Snapshot names must be unique for your workspace. If you want to reuse a snapshot name, delete the existing snapshot with that name, and then reuse the name.
Volumes to be included in the snapshot must be in the same storage pool.
Volumes to be included in the snapshot must not be in the error state and the health state of the volume must be ok.

Creating a snapshot

With the snapshot interface, you can create a relationship between your source disks and a target disk at a defined time, for example T1. Target disks are created as part of creating a snapshot operation. The snapshot operation tracks the changes that are made to the source disk beyond T1 time. Thus, you can restore the source disks to their T1 state at a later point in time.

Use case

The snapshot feature has several use cases. Consider the following example:

An administrator plans to upgrade the middleware. If the upgrade to the middleware fails, the administrator must restore the source disk to its original state.
The administrator completes the following steps:
1. Initiate the snapshot of the source disk where the middleware information resides by using the API command. A snapshot of the source disk is created.
2. Upgrade the middleware.
3. If the upgrade fails, the administrator restores the source disk by using the snapshot.
4. If the upgrade succeeds, the administrator deletes the snapshot.

You can initiate multiple snapshot operations. However, these concurrent snapshot operations occur on different sets of disks.

Creating a snapshot by using API or CLI commands

Use the following API and CLI commands to create a snapshot:

API: Create a PVM Instance snapshot.
CLI: ibmcloud pi snapshot create.

You must provide values for the following parameters in the API and CLI commands:

name: (Required) Specifies the name of the snapshot.

The name must be a unique value among all the snapshots for the workspace.
description: (Optional) Describes the snapshot.
volumeIDs: (Optional) Includes a list of one or more volumes to be included in the snapshot. If this parameter is left empty, all volumes that are attached to the Power virtual machine (PVM) Instance are included in the snapshot.

Restrictions and considerations for creating a snapshot

You must consider the following restrictions and considerations when you create a snapshot:

You cannot run PVM Instance snapshot operations in parallel from different PVM Instances for the same shared volume at a specific time.
You cannot resize a volume if the volume is included in a PVM Instance snapshot. To resize such a volume, you must first delete all the instance snapshots that the volume is part of.
You cannot detach volumes from the PVM Instance that are included in an instance snapshot. To detach such volumes, you must first delete all the instance snapshots these volumes are a part of.
You must attach all volumes that are included in the snapshot to the same PVM Instance.
If the volumeIDs option is not specified, all volumes that are attached to the PVM Instance are included in the snapshot.
If the volumes that are attached to the PVM Instance are not in the same storage pool, then use the volumeIDs option to include the volumes that are in the same storage pool. In this case, you must group the volumes from the same storage pool and create a snapshot for each volume group in the storage pool.

If the operation to create a snapshot fails, it results in an error state. You can delete this snapshot so that no other operations can be performed on it.

Restoring a snapshot

The restore operation restores the volumes that are part of a VM snapshot to the source disks. When the restore operation is in progress, Power Virtual Server creates a backup snapshot, which can be used if the restore operation fails. If the restore operation succeeds, the backup snapshots are deleted. If the restore operation fails, the snapshot status is set to restore-error. You can attempt to retry the restore or roll back operations to their original state. Use the restore_fail_action query parameter with retry value to retry the restore operation. To roll back to a previous disk state, use the restore_fail_action query parameter with the rollback value. When the restore operation fails, the VM enters an Error state.

Prerequisites

Ensure that the following prerequisites are met before you initiate the restore operation:

By default, you must shut down the PVM Instance before you initiate the restore operation.
To restore the data on a live PVM Instance, use the force restore operations. The following conditions must be met:
- Quiesce the applications
- Do not run I/O operations on the volume disks
Failure to meet the conditions for force restore operation can result in data corruption.
If you are restoring an instance snapshot of a volume that is shared among multiple VMs then you must quiesce all the applications on all VMs. Also, no I/O operations must be running on the shared volumes during the restore operation.
If you are not sure how to quiesce your applications, it is recommended to shut down any VMs attached to the volumes that you want to include in the snapshot.

Restoring a snapshot by using API or CLI commands

Use the following API and CLI commands to restore a snapshot:

API: Restore a PVM Instance snapshot.
CLI: ibmcloud pi snapshot-restore

You must provide values for the following parameters in the API and CLI commands:

SNAPSHOT_ID: (Required) Specify a unique identifier for the snapshot
force: (Optional) Specify the value of the flag as True or False. By default, the flag is set to False. This flag is set to true only if the VM instance is shut down. By default, the VM must be shut down before you initiate a snapshot restore operation. When the force flag is set to True, the prerequisite of the VM being shut down is relaxed.
restore: (Optional) Use the restore_fail_action query parameter only if a previous restore operation results in setting the PVM Instance snapshot to restore-error status. The restore_fail_action query parameter accepts the following retry or rollback values:
- If the snapshot status is set to retry, then again the failed restore operation is attempted.
- If the snapshot status is set to rollback, then the volumes that were failed to be restored are rolled back to their original state.

If you are using the force option, you must ensure that all the applications that access the volumes in the instance snapshot are quiesced and no I/O operations are running on the volume disk.

Use cases

Consider the following scenarios to restore a snapshot:

Restoring all of the volumes that are part of a VM snapshot
Running multiple VM restore operations
Retrying a VM restore operation if it originally failed
Rolling back a VM to its original volume state

Restrictions and considerations

Before the system begins the restore operation of the PVM Instance snapshot, a temporary backup snapshot of the volumes is created for internal use only. If the snapshot restore operation fails, the temporary backup is used by the system to restore the PVM Instance to the state before the restore operation failed.
Volume restore operation is not allowed if any copy operations are running on the target volume. The volumes in the instance snapshot are validated to ensure that no copy operations are running against them. Use the API to get a list of FlashCopy mappings for a volume or the CLI command to get a list of FlashCopy mappings for a volume.
When you perform a restore operation on a PVM Instance snapshot, the PVM Instance task status changes to restoring, the volume status is changed to reverting, and no other PVM Instance operations are allowed.
When restore operation on a PVM Instance snapshot fails, the PVM Instance status changes to restore-Error state. You can retry the PVM Instance snapshot restore operation or you can request to roll back the PVM Instance to its original state it was in before the restore operation failed.
If you perform a restore operation on the shared volume, all the virtual machines that are sharing the volume are restored.
If you perform a restore operation on the shared volume on one virtual machine, you cannot perform the snapshot, restore, clone, or capture operations on other virtual machines that use the shared volume.
Before you perform a restore operation on a boot disk, the virtual machine must be shut down and the status must change to shutoff state.
After successful restore retry operation, the VM state might not reset from Error state. Use Reset State feature on the UI to reset the VM state.
You cannot restore a PVM Instance snapshot if the snapshot was recently created and the FlashCopy operations are still running in the background. The FlashCopy operations must first get completed. Use the API to get a list of FlashCopy mappings for a volume or the CLI command to get a list of FlashCopy mappings for a volume.

Metering and pricing of snapshot

Each snapshot that you create is monitored during every hour and charged depending on the disk space that is requested for the snapshot. The space that is used by a snapshot is charged at 30% of the base rate.

For example, consider that you have M disks on a VM that add up to 600 GB of space. The M disks are used as source disks for snapshots. The following charges are applicable on M disks:

If you create one snapshot, you are charged for the disk space that is used by the base 600 GB of M disks plus 30% of 600 GB of disk space. That is, 600 GB (space of M disks) + 180 GB (30% of 600 GB) = 780 GB of disk space.
If you create another snapshot by using same disks, you are charged for the disk space that is used by M disks. That is, 600 GB (space of M disks) + (30% of 600 GB) + (30% of 600 GB) = 960 GB of disk space.
The pricing of a snapshot is calculated based on the volume size and storage tier of the individual source volumes that are present in the snapshot. For example, consider the following table to calculate the cost of a snapshot that has volume A and volume B.

An example to calculate the cost of a snapshot
Volume name	Volume size	Tier type	Cost of a volume
Volume A	100 GB	Tier 1	30% of 100 GB
Volume B	30 GB	Tier 0	30% of 30 GB

The cost of the snapshot is the sum of the costs of volume A and volume B.

Creating a volumes-clone

Creating a volumes-clone request

The clone operation creates a full copy of the volume. You can select multiple volumes and initiate a group clone operation. When multiple volumes are selected, the clone operation ensures that a consistent data copy is created.

The clone operation continues to copy data from the source disks to target disks in the background. Depending on the size of the source disks and the amount of data to be copied, the clone operation can take a significant amount of time.

Prerequisites

Ensure that the following prerequisites are met before you start to create a volumes-clone request:

A volumes-clone request name must be unique for your workspace. If you want to reuse a volumes-clone request name, delete the existing volumes-clone request with that name, and then reuse the name.
Volumes to be included in the volumes-clone request must be located in the same storage pool.
Volumes to be included in the volumes-clone request must not be in the error state and the health state of the volume must be ok.
Quiesce the applications that access the set of volumes that you want to include in the volumes-clone request.

Creating the volumes-clone request by using API and CLI commands

The Prepare action operation completes the preparatory work for creating the group snapshot of volumes that are getting cloned.

Prerequisites

Ensure that the following prerequisites are met before you initiate the Prepare action operation:

A minimum of two volumes
A minimum of one volume to be in the in-use state
A unique volumes-clone name

When a Prepare action operation is in progress, you cannot trigger another Prepare action operation for the same set of volumes. A Prepare action operation must be followed by Start and Execute operations. If you are not using the existing Prepare action operation, you must cancel the existing operation before you initiate the next Prepare action operation.

Use the following API and CLI command for initiating the Prepare action operation:

API: Create a new volumes clone request and initiates the Prepare action
CLI: ibmcloud pi volume clone create

You must provide values for the following parameters in the API and CLI commands:

name: (Required) Provide a name to be assigned to the volumes-clone request. The name must be unique among all the existing volumes-clone requests.
volumeIDs: Provide the list of volume identifiers or names to be cloned. A minimum of two volume IDs are required and at least one of the volumes must be in the in-use state. All volumes to be included in the volumes-clone request must be in the same storage pool.

When the Prepare action operation progresses to 100%, the Prepare status changes depending on the following conditions:

If Prepare action completes successfully, the status changes to prepared.
If Prepare action fails to complete successfully, the status changes to failed.

To check the status of the Prepare action operation, use the API or CLI command with volumesCloneID option.

Restrictions and considerations

A minimum of 2 volume IDs are required and at least one of them must be in the in-use state.

To clone a single volume, you can use the Create a volume clone for specified volumes API or the ibmcloud pi volume clone-async CLI command. To check on the status of the single volumes-clone, you can use the Get the status of a volumes clone request for the specified clone task ID API or the ibmcloud pi volume clone-async get CLI command.

When a clone operation is performed on a volume that is in the in-use state, Power Virtual Server creates a consistent group snapshot and re-creates the copy of the cloned volume by using the group snapshot.
You cannot modify the source or target disk attributes such as disk size, while the clone operation is in progress.
You cannot attempt to clone a volume that is part of a consistency group as part of an existing consistency group. A volume will belong to a consistency group after you must run the volumes-clone start request, or the volume is part of a snapshot create operation where the flash copying in the background is completed.
A volume cannot be cloned from one storage pool to a different storage pool.

Starting a volumes-clone request

This step allows the consistency group to initiate the FlashCopy operation.

As a prerequisite, the volumes-clone request must be in the Prepared state.

Starting a volumes-clone request by using API and CLI command

The initial status of the volume-colne request is set to Starting.

Use the following API and CLI command to initiate the volumes-clone request:

API: Initiate the Start action for a volumes-clone request
CLI: ibmcloud pi volume clone start

You must provide the unique identifier of a volumes-clone request in the volume_clones_id parameter. The identifier can be the volumes-clone ID or the volumes-clone name.

When the volumes-clone request is initiated, the initial status is set to Starting. When the group snapshot is created, the request status changes to Available. The start operation of the volumes-clone request is synchronous. When the API call returns to the client, the volumes-clone request status changes to Available unless an error occurs. If an error occurs during the start operation, the status of the volumes-clone request changes to Failed. The reason for failure is specified in the error that is returned with the start operation response. The prepared snapshot data is removed so that you can clone the same set of volumes again. If you cancel the start operation of a volumes-clone request, the status of the volumes-clone request changes to Cancelling. You can cancel a volumes-clone request when the volumes-clone request is in the Available state.

Restrictions and considerations

You must consider the following restrictions and considerations before you start the volumes-clone request:

A minimum of two volume IDs are required and at least one of them must be in the in-use state.
When a clone operation is performed on a volume that is in the in-use state, Power Virtual Server creates a consistent group snapshot and re-creates the copy of the cloned volume by using the group snapshot.
When a clone operation is in progress, you cannot modify the source or target disk attributes, such as disk size.

Executing a volumes-clone request

This step performs the remaining execution operation to create the cloned volumes from the available group snapshot.

Prerequisites

The volumes-clone request must be in the Available state.

Executing volumes-clone request by using API and CLI command

After you initiate the execute operation, the initial percentComplete will be 0% and the status is set to executing.

Use the following API and CLI command to initiate the volumes-clone request:

API: Initiate the Execute action for a volumes-clone request
CLI: ibmcloud pi volume clone execute

You must provide values for the following parameters in the API and CLI commands:

volume-clones-id: (Required) The unique identifier of a volumes-clone request. The identifier can be the volumes-clone ID or the volumes-clone name.
name: (Required) The base name of the new cloned volumes. Cloned volume names are prefixed with clone- and suffixed with -#####-N. In the suffix, ##### is a five-digit random number and N is an incremental number that starts with 1.
rollbackPrepare: (Optional) Default value is False. When the flag is set to False, the system runs the failed rolls back clone activity but the prepared snapshot is left as-is. When the flag is set to True, the system runs the failure rollback clone activity and removes the prepared snapshot.
userTags: (Optional) Provide the list of user tags to be attached to the cloned volumes.
targetReplicationEnabled: (Optional) Use this flag to enable or disable replication for the cloned volumes. By default, the flag uses the replication status of the source volumes that are getting cloned. When set to False the cloned volumes are not enabled for replication. When set to True the cloned volumes are enabled for replication.

The storage pool where the source volumes reside must be enabled for replication, if the source volumes are not enabled for replication and you are enabling replication for the cloned volumes.

targetStorageTier: Provide the name of the storage tier for the cloned volumes. Use this field to clone a set of volumes from one storage tier to a different storage tier. Cloned volumes must remain in the same storage pool as the source volumes.

Restrictions and considerations

You must consider the following restrictions and considerations before you start the volumes-clone request:

A volumes-clone request is considered complete when the status of the volumes-clone request is changed to one of the completed, failed, or cancelled state.
When the volumes-clone execute request is initiated, the initial status is set to executing.
When the execute operation is completed successfully, the volumes-clone request status changes to completed.
If an error occurs during the volume cloning process, any artifacts that are created by the cloning process are removed. The group snapshot is returned to the available state so that you can retry the execute operation.
You can cancel a volumes-clone request when it is in the executing state.
If you cancel the execute operation of a volumes-clone request, the status of the volumes-clone request is changed to cancelling.
You can control the behavior of a failed execute operation by using the rollbackPrepare option. The default value of the rollbackPrepare option is false. The default value leads the failed execute operation to roll back the clone activity and does not remove the prepared snapshot. If the rollbackPrepare option is set to true, it leads the failed execute operation to roll back the clone activity and removes the prepared snapshot.

Cancelling a volumes-clone request

The Cancel a volumes-clone request operation initiates the cleanup activity that performs the cleanup of the preparatory clones and snapshot volumes.

Prerequisites

The volumes-clone request must be in the Available state.

Cancelling volumes-clone request by using API and CLI command

After you initiate the cancel operation, the initial percentComplete will be 0% and the status is set to cancelling.

Use the following API and CLI command to cancel the volumes-clone request:

API: Cancel a volumes-clone request
CLI: ibmcloud pi volume clone cancel

You must provide values for the following parameters in the API and CLI commands:

volume-clones-id: (Required) The unique identifier of a volumes-clone request. The identifier can be the volumes-clone ID or the volumes-clone name
Force: (Optional) Default status is False. The cancel operation is allowed only if the status is set to prepared or available. When the status is set to True, the cancel operation is allowed when the status is set to NOT completed, cancelling, cancelled, or failed.

Restrictions and considerations

You must consider the following restrictions and considerations before you cancel the volumes-clone request:

If you cancel the volumes-clone request, the initial status of the volumes-clone request is set to Cancelling. The status changes to Cancelled state when all the clean-up work is completed successfully.
You can cancel a volumes-clone request when the volumes-clone request is in the executing state. The force option must be set to True in the cancel volumes-clone request.
If the volumes-clone request is in the Executing state, any artifacts that are created by the clone operation process are removed.

Deleting a volumes-clone request

When a volumes-clone request is no longer required, you can delete the request by initiating the volumes-clone delete operation.

Prerequisites

The volumes-clone request must be in one of these final statuses: Completed, Failed, or Cancelled.

Deleting a volumes-clone request by using API and CLI command

Use the following API and CLI command to delete the volumes-clone request:

API: Delete a volumes-clone request
CLI: ibmcloud pi volume clone delete

You must provide values for the following parameters in the API and CLI commands:

volume-clones-id: (Required) The unique identifier of a volumes-clone request. The identifier can be the volumes-clone ID or the volumes-clone name.
Force: (Optional) Force the cancellation of a volumes-clone request. The cancel operation is allowed only if the status is set to prepared or available. When the status is set to True, the cancel operation is allowed when the status is set to NOT completed, cancelling, cancelled, or failed.

Restrictions and considerations

If the volumes-clone request is not in one of the final statuses that is required for deletion, you can cancel the request, do any remaining cleanup, and transition the status to Cancelled. If the volumes-clone request is in the Cancelled status, the request can be deleted.

Getting the status for a volumes-clone request

This API request returns detailed information about the status of the volumes-clone request. For example, the list of source volumes that are getting cloned and the list of cloned volumes when the execute operation is successfully completed.

Prerequisites

None.

Getting the status of volumes-clone request by using API and CLI command

API: Get the status of a volumes clone request for the specified clone task ID
CLI: ibmcloud pi volume clone get

Provide a value for the volume-clones-id field. The value is the unique identifier of a volumes-clone request. The identifier can be the volumes-clone ID or the volumes-clone name.

Restrictions and considerations

None.

Getting the list of volumes-clone request

The API request provides a list of all volumes-clone requests in a workspace and the status of each request.

Prerequisites

None.

Getting a list of volumes-clone request by using API and CLI command

API: Get the list of volumes-clone request for a cloud instance
CLI: ibmcloud pi volume clone list

Provide one of the values to the filter parameter from the following list:

prepare - includes status values (preparing, prepared)
start - includes status values (starting, available)
execute - includes status values (executing, available-rollback)
cancel - includes status values (cancelling)
completed - includes status values (completed)
failed - includes status values (failed)
cancelled - includes status values (cancelled)
finalized - included status values (completed, failed, cancelled)

Restrictions and considerations

You must consider the following restrictions and considerations before you get the list of volumes-clone requests:

The detailed information about the source volumes or cloned volumes is not provided.
The list can be limited by using the filter parameter. The filter is based on the status of the ‘filter’ parameter.

Frequently asked questions

Following are some of the frequently asked questions on snapshots and clonning that are documented on the FAQ page: