Managing Block Storage for VPC snapshots

Renaming a snapshot in the console

Use the following steps to rename a snapshot in the console.

1. Go to the list of snapshots. In the IBM Cloud console, go to the menu > Infrastructure > Storage > Snapshots.
2. Click the name of a snapshot from the list.
3. Click the Edit icon .
4. Provide a new name for the snapshot, save, and confirm your changes.

Renaming a snapshot from the CLI

ibmcloud login --sso -a cloud.ibm.com

ibmcloud is snapshot-update SNAPSHOT_ID --name SNAPSHOT_NAME

cloudshell:~$ ibmcloud is snapshot-update r138-e6664842-b370-496a-9ae7-da3fb647707c --name snappy-snap-snap
Updating snapshot r138-e6664842-b370-496a-9ae7-da3fb647707c under account Test Account as user test.user@ibm.com...

ID                     r138-e6664842-b370-496a-9ae7-da3fb647707c
Name                   snappy-snap-snap
CRN                    crn:v1:bluemix:public:is:eu-de:a/a1234567::snapshot:r138-e6664842-b370-496a-9ae7-da3fb647707c
Status                 stable
Clones                 Zone      Available   Created
                       eu-de-3   true        2023-02-17T20:28:53+00:00
                       eu-de-1   true        2023-02-17T18:53:57+00:00

Source volume          ID                                          Name
                       r010-df8ffd90-f2e5-470b-83d7-76e64995a1aa   vicky-block-test1

Bootable               false
Encryption             provider_managed
Encryption key         -
Minimum capacity(GB)   20
Size(GB)               1
Resource group         ID                                 Name
                       a0eb5d9062af485fa5bb2c6999c74eac   test-snap

Created                2023-02-17T18:53:57+00:00
Captured at            2023-02-17T18:53:57+00:00
Tags                   -

Renaming a snapshot with the API

You can rename a snapshot by using the API.

Make a PATCH /snapshots call and specify the snapshot ID and new name of the snapshot.

curl -X PATCH \
"$vpc_api_endpoint/v1/snapshots/7528eb61-bc01-4763-a67a-a414a103f96d?version=2022-01-12&generation=2" \
   -H "Authorization: Bearer ${API_TOKEN}" \
   -d '{
     "name": "my-snapshot-renamed"
   }'

You can use the same call to rename a cross-regional copy. The cross-regional copy is independent from the source snapshot and source volume, and can be managed like any other snapshot.

Updating a snapshot with Terraform

To use Terraform, download the Terraform CLI and configure the IBM Cloud Provider plug-in. For more information, see Getting started with Terraform.

VPC infrastructure services use a specific regional endpoint, which targets to us-south by default. If your VPC is created in another region, make sure to target the appropriate region in the provider block in the provider.tf file.

See the following example of targeting a region other than the default us-south.

provider "ibm" {
  region = "eu-de"
}

To update a snapshot, use the ibm_is_snapshot resource. You can change the name of the snapshot, the fast restore zones, and tags. However, changing resource_group and source_volume values forces Terraform to destroy the snapshot and create a different snapshot.

resource "ibm_is_snapshot" "example" {
  name          = "my-snapshot"
  source_volume = ibm_is_volume.example.id
  }

For more information about the arguments and attributes, see ibm_is_snapshot.

Sharing a snapshot with another account in the console

You can share a snapshot with another account in the console.

1. Go to the list of snapshots. In the IBM Cloud console, go to the menu > Infrastructure > Storage > Snapshots.
2. From the Actions menu , select Share snapshot.
3. Enter the account ID of the account that you want to share the snapshot with.
4. Click Create a custom IAM authorization.

Alternatively, you can create a service-to-service authorization through the Manage > Access (IAM) > Authorizations menu. For more information, see Creating service-to-service authorization for cross-account restore in the console.

Managing sharing permissions for a snapshot in the console.

1. Go to the list of snapshots. In the IBM Cloud console, go to the menu > Infrastructure > Storage > Snapshots.

2. From the Actions menu , select Manage share permission.

3. The side-panel displays the list of accounts that you shared your snapshot with.

   The list shows all the authorization that were setup for the snapshot. For example, if an account has an authorization for this specific snapshot and an authorization for all snapshots in your account, that account is listed twice.

4. Click Manage IAM Authorization to go to the Authorization page to modify or revoke the authorization.

Alternatively, you can manage a service-to-service authorization policy directly through the Manage > Access (IAM) > Authorizations menu. For more information, see Using authorizations to grant access between services.

Sharing a snapshot with another account from the CLI

You can create a service-to-service authorization for a specific snapshot from the CLI by using the ibmcloud iam authorization-policy-create command. For more information, see Creating service-to-service authorization for cross-account restore from the CLI.

Managing sharing permissions for a snapshot from the CLI

You can remove a service-to-service authorization for a specific snapshot from the CLI by using the authorization-policy-delete command. For more information, see Removing an authorization by using the CLI.

Sharing a snapshot with another account with the API

You can programmatically create a service-to-service authorization for a specific snapshot by calling the policies method in the IAM Policy Management API. For more information, see Creating service-to-service authorization for cross-account restore with the API.

Managing sharing permissions for a snapshot with the API

You can programmatically revoke a service-to-service authorization for a specific snapshot by calling the policies method in the IAM Policy Management API. For more information, see Removing an authorization by using the API.

Adding tags to a snapshot in the console

You can add user tags and access management tags to your Block Storage for VPC snapshots. You can add user tags to an existing snapshot or when you create a snapshot. The tags can be used by a backup policy to create backups of the snapshot.

Adding tags to a snapshot from the CLI

You can add tags to a snapshot from the CLI.

Specify a snapshot-update command with the --tags option to add user tags to a volume.

Use the same option to add tags to a volume when you create a snapshot by using ibmcloud is snapshot-create.

The following example adds user tags env:test and env:prod to a volume that is identified by its ID.

cloudshell:~$ ibmcloud is snapshot-update r138-e6664842-b370-496a-9ae7-da3fb647707c --name snappy-snap-snap --tags env:test,env:prod
Updating snapshot r138-e6664842-b370-496a-9ae7-da3fb647707c under account Test Account as user test.user@ibm.com...

ID                     r138-e6664842-b370-496a-9ae7-da3fb647707c
Name                   snappy-snap-snap
CRN                    crn:v1:bluemix:public:is:eu-de:a/a1234567::snapshot:r138-e6664842-b370-496a-9ae7-da3fb647707c
Status                 stable
Clones                 Zone      Available   Created
                       eu-de-3   true        2023-02-17T20:28:53+00:00
                       eu-de-1   true        2023-02-17T18:53:57+00:00

Source volume          ID                                          Name
                       r010-df8ffd90-f2e5-470b-83d7-76e64995a1aa   vicky-block-test1

Bootable               false
Encryption             provider_managed
Encryption key         -
Minimum capacity(GB)   20
Size(GB)               1
Resource group         ID                                 Name
                       a0eb5d9062af485fa5bb2c6999c74eac   test-snap

Created                2023-02-17T18:53:57+00:00
Captured at            2023-02-17T18:53:57+00:00
Tags                   env:test,env:prod

When the user tags are matched with a backup policy, a backup is triggered based on the backup plan schedule. For more information, see Creating a backup policy.

Adding user tags to a snapshot with the API

You can add user tags to a snapshot by using the API.

Make a PATCH /snapshots call and specify the snapshot ID and user tags. The following example adds user tags env:test and env:prod to the snapshot.

curl -X PATCH \
"$vpc_api_endpoint/v1/snapshots/7528eb61-bc01-4763-a67a-a414a103f96d?version=2022-01-12&generation=2" \
    -H "Authorization: Bearer ${API_TOKEN}" \
    -d `{
       "user_tags": [
         "env:test",
         "env:prod"
       ]
    }'

When the user tags are matched with a backup policy, a backup is triggered based on the backup plan schedule. For more information, see Creating a backup policy.

Editing fast restore zones in the console

Use the following steps to edit the zones where fast restore clones are stored in the console. You can add or remove zones as needed.

1. Select a snapshot from the list of snapshots.
2. From the Actions menu , select Edit fast restore.
3. From the side panel, select or deselect the zones for fast restore in your region. Review the billing update based on your selection.
4. Click Save. You're returned to the snapshots details page. The Fast restore section shows the new zone initially with a pending status.

Fast restore information is updated when you refresh. Zone information is updated to show enabled or disabled, depending on your changes.

Creating a snapshot clone for fast restore from the CLI

To create a zonal copy of a snapshot, issue the ibmcloud is snapshot-clone-create command with the snapshot ID and the zone or zones where you want to create copies. The following command example creates the fast restore clone of r138-4463eb2c-4913-43b1-b9bf-62a94f74c146 in the eu-de-3 zone.

cloudshell:~$ ibmcloud is snapshot-clone-create r138-4463eb2c-4913-43b1-b9bf-62a94f74c146  --zone eu-de-3
Creating zonal clone of snapshot r138-4463eb2c-4913-43b1-b9bf-62a94f74c146 under account Test Account as user test.user@ibm.com...

Zone        eu-de-3
Available   false
Created     2023-02-17T20:29:21+00:00
Href        https://eu-de.iaas.cloud.ibm.com/v1/regions/eu-de/zones/eu-de-3

The snapshot clone appears to be unavailable while the snapshot clone is created. It takes only a few seconds. Issue the ibmcloud is snapshot-cl command with the snapshot ID and the clone target zone to see the new snapshot clone as available.

cloudshell:~$ ibmcloud is snapshot-cl r138-4463eb2c-4913-43b1-b9bf-62a94f74c146 eu-de-3
Getting zonal clone eu-de-3 of snapshot r138-4463eb2c-4913-43b1-b9bf-62a94f74c146 under account Test Account as user test.user@ibm.com...

Zone        eu-de-3
Available   true
Created     2023-02-17T20:29:21+00:00

For more information about available command options, see ibmcloud is snapshot-clone-create.

Deleting a snapshot clone from the CLI

To delete a snapshot clone, issue the ibmcloud is snapshot-clone-delete command with the Snapshot ID and the zone where you want the snapshot copy removed. The following command example deletes the fast restore copy of the snapshot r138-4463eb2c-4913-43b1-b9bf-62a94f74c146 in the eu-de-3 zone.

@cloudshell:~$ ibmcloud is snapshot-clone-delete r138-4463eb2c-4913-43b1-b9bf-62a94f74c146 eu-de-3
This will delete zonal clone eu-de-3 for snapshot r138-4463eb2c-4913-43b1-b9bf-62a94f74c146 and cannot be undone. Continue [y/N] ?> y
Deleting zonal clone eu-de-3 for snapshot r138-4463eb2c-4913-43b1-b9bf-62a94f74c146 under account Test Account as user test.user@ibm.com...
OK
Deletion request for zonal snapshot clone eu-de-3 has been accepted.

For more information about available command options, see ibmcloud is snapshot-clone-delete.

Creating a snapshot clone for fast restore with the API

To create fast restore snapshots, you create a clone of the snapshot in a different zone. You then restore a volume from that clone.

In the API, you create a clone for an existing snapshot by making a PUT /snapshots/{id}/clones/{zone_name} call to clone the snapshot to the specified zone. See the following example.

curl -X PUT \
"$vpc_api_endpoint/v1/snapshots/5e160469-0837-48a7-8973-e44c8d5fd85a/clones/us-south-1&version=2022-12-22&generation=2" \
     -H "Authorization: Bearer ${API_TOKEN}"

A successful response looks like the following example.

{
  "available": true,
  "created_at": "2022-12-22T20:35:38.600Z",
  "zone": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1",
    "name": "us-south-1"
  }
}

You can also specify the clone property when you create a snapshot of a volume. See the following example.

curl -X POST \
"$vpc_api_endpoint/v1/snapshots?version=2022-12-12&generation=2" \
-H "Authorization: $iam_token" \
-d '{
    "clones": [
        {
        "zone": {
            "name": "us-south-1"
        }
        }
    ],
    "name": "my-snapshot2",
    "resource_group": {
        "id": "a342dbfb-3ea7-48d1-96e8-2825ec5feab4"
    },
    "source_volume": {
        "id": "8948ad59-bc0f-7510-812f-5dc64f59fab8"
    },
    "user_tags": [
        "env:test",
        "env:prod"
    ]
}'

A successful response looks like the following example.

{
  "bootable": false,
  "clones": [
      "available": true,
      "created_at": "2022-12-12T20:18:38.600Z",
      "zone": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1",
        "name": "us-south-1"
     }
  ],
  "created_at": "2021-12-12T20:18:18Z",
  "crn": "crn:[...]",
  "deletable": false,
  "encryption": "user_managed",
  "encryption_key": {
    "crn": "crn:[...]"
  },
}

Deleting a snapshot clone with the API

Make a DELETE /v1/snapshots/{id}/clones/{zone-name} call to delete a snapshot clone in the specified zone. You can't undo the delete when the snapshot clone is deleted.

See the following example.

curl -X DELETE \
"$vpc_api_endpoint/v1/snapshots/fde0b8d5-2d75-4c28-af7d-12ffc3ae2a55/clones/us-south-1&version=2022-12-22&generation=2" \
     -H "Authorization: Bearer ${API_TOKEN}"

Creating a remote copy in the console

Use the following steps to create cross-regional copies of snapshots from the Snapshots for VPC list or from the snapshot details page.

1. In the console, click the Navigation menu icon > Infrastructure > Storage > Block Storage snapshots.

2. In the list of snapshots, find the snapshot that you want to duplicate in another region. Make sure the snapshot is in Stable status.

3. click the Actions menu () and select Copy snapshot.

4. Select the region where you want to create the copy.

   You can have only one copy per region. If no regions are available for copies, the option Copy Snapshot is disabled.

5. Click Create.

Alternatively, click the snapshot's name to view its details. You can either access the Copy Snapshot option from the Actions menu or you can scroll to the remote copies card and click Create copy. The same provisioning panel opens where you can make the region selection.

Deleting remote region copy in the console

Snapshot copies in a remote region are independent from the parent snapshot and the parent volume. You can delete them anytime by using the Snapshots for VPC list.

Use the following steps to delete a remote region copy in the console.

1. In the IBM Cloud console, go to the menu > Infrastructure > Storage > Snapshots.
2. Click the Actions icon in the row of the snapshot that you want to delete.
3. Select Delete.
4. Confirm the deletion and click Delete.

Creating a remote region copy from the CLI

You can create a cross-regional copy of a snapshot by using the snapshot-create command with the --source-snapshot-crn option and the source snapshot CRN, which creates a snapshot in the target region by using the CRN of a snapshot from the source region. The created snapshot uses the customer-defined encryption key if the CRN of an encryption key was also specified. The source snapshot must in Stable status for the copy to be created successfully.

ibmcloud is snapshot-create --name my-cli-snapshot-crc --source-snapshot-crn crn:v1:bluemix:public:is:us-south:a/a1234567::snapshot:r006-b9590a48-63a3-445e-b819-3f2c0b82daf8

Creating snapshot my-cli-snapshot-crc under account Test Account as user test.user@ibm.com...

ID                     r142-bd4532c0-e73c-44f9-a017-89e5368c521a
Name                   my-cli-snapshot-crc
CRN                    crn:v1:bluemix:public:is:us-east:a/a1234567::snapshot:r142-bd4532c0-e73c-44f9-a017-89e5368c521a
Status                 pending
Clones                 Zone   Available   Created

Source volume          ID                                          Name                   Remote Region
                       r006-be21061a-4dc6-4c9f-b17d-421838fde399   -remote-421838fde399   us-south

Snapshot Copies        ID   Name   Remote Region   CRN   Resource type

Bootable               true
Encryption             provider_managed
Encryption key         -
Source Snapshot        ID                                          Name                   Remote Region   CRN                                                                                                                        Resource type
                       r006-b9590a48-63a3-445e-b819-3f2c0b82daf8   cli-snap-crc-test-sn   us-south        crn:v1:bluemix:public:is:us-south:a/a1234567::snapshot:r006-b9590a48-63a3-445e-b819-3f2c0b82daf8   snapshot

Minimum capacity(GB)   100
Size(GB)               1
Source Image           ID                                          Name                   Remote Region
                       r006-24d856e2-6aec-41c2-8f36-5a8a3766f0d6   -remote-5a8a3766f0d6   us-south

Operating system       Name             Vendor   Version                 Family   Architecture   Display name
                       centos-7-amd64   CentOS   7.x - Minimal Install   CentOS   amd64          CentOS 7.x - Minimal Install (amd64)

Resource group         ID                                 Name
                       cdc21b72d4e647b195de988b175e3d82   Default

Created                2023-04-24T18:54:29+05:30
Captured at            2023-04-24T09:48:03+05:30
Tags                   -
Service Tags           -

For more information about available command options, see ibmcloud is snapshot-create.

Deleting a remote region copy from the CLI

You can delete a cross-regional copy of a snapshot by using the ibmcloud is snapshot-delete command with the snapshot ID.

cloudshell:~$ ibmcloud is snapshot-delete r142-bd4532c0-e73c-44f9-a017-89e5368c521a
This will delete snapshot r142-bd4532c0-e73c-44f9-a017-89e5368c521a and cannot be undone. Continue [y/N] ?> y
Deleting snapshot r142-bd4532c0-e73c-44f9-a017-89e5368c521a under account Test Account as user test.user@ibm.com...
    OK
Snapshot r142-bd4532c0-e73c-44f9-a017-89e5368c521a is deleted.

For more information about available command options, see ibmcloud is snapshot-delete.

Creating a remote region copy with the API

You can create a cross-regional copy of a snapshot by making an API call in the target region. Specify the CRN of the source snapshot to create a copy in the target region. The created snapshot uses the customer-defined encryption key if the CRN of an encryption key was also specified. The source snapshot must in Stable status for the copy to be created successfully. See the following example, where the target region is us-east and the original snapshot is in us-south.

POST https://us-east.iaas.cloud.ibm.com/v1/snapshots
{
     "name": "my-snapshot",    // required
     "source_snapshot": {      // required
      	"crn": "crn:[...]"
     },
     "resource_group": {       // optional
       "id": "2d1bb5a8-40a8-447a-acf7-0eadc8aeb054"
     },
     "encryption_key"; "crn:[...]"     // optional
}

A successful response looks like the following example:

{
  "created_at": "2023-05-18T20:18:18Z",
  "deletable": false,
  "encryption": "user_managed",
  "encryption_key": {
    "crn": "crn:[...]"
  },
  "href": "https://us-east.iaas.cloud.ibm.com/v1/snapshots/r139-f6bfa329-0e36-433f-a3bb-0df632e79263",
  "id": "r139-f6bfa329-0e36-433f-a3bb-0df632e79263",
  "lifecycle_state": "pending",
  "minimum_capacity": 100,
  "name": "my-snapshot",
  "operating_system": {
    "architecture": "amd64",
    "dedicated_host_only": false,
    "display_name": "Ubuntu Linux 20.04 LTS Focal Fossa Minimal Install (amd64)",
    "family": "Ubuntu Linux",
    "gpu_supported": [],
    "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-20-04-amd64",
    "name": "ubuntu-20-04-amd64",
    "vendor": "Canonical",
    "version": "20.04 LTS Focal Fossa Minimal Install"
  },
  "resource_group": {
    "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956",
    "id": "678523bcbe2b4eada913d32640909956",
    "name": "Default"
  },
  "resource_type": "snapshot",
  "service_tags": [],
  "size": 1,
  "source_image": {
    "crn": "crn:[...]",
    "remote": {
    	"region": {
    	   "name": "us-south",
    	   "hfef": "https://us-east.iaas.cloud.ibm.com/v1/regions/us-south"
    	}
    },
    "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-32045dc2-b463-4cda-b424-bc3dcf51dfbb",
    "id": "r006-32045dc2-b463-4cda-b424-bc3dcf51dfbb",
    "name": "ibm-ubuntu-20-04-minimal-amd64-1"
  },
  "source_snapshot": {
    "crn": "crn:[...]",
    "remote": {
    	"region": {
    	   "name": "us-south",
    	   "hfef": "https://us-east.iaas.cloud.ibm.com/v1/regions/us-south"
    	}
    },
    "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r006-511a798c-5816-4082-8ecb-554a440f83de",
    "id": "r006-511a798c-5816-4082-8ecb-554a440f83de",
    "name": "my-snapshot-data"
  },
  "source_volume": {
    "crn": "crn:[...]",
    "remote": {
    	"region": {
    	   "name": "us-south",
    	   "hfef": "https://us-east.iaas.cloud.ibm.com/v1/regions/us-south"
    	}
    },
    "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-411a798c-5816-4082-8ecb-554a440f83de",
    "id": "r006-411a798c-5816-4082-8ecb-554a440f83de",
    "name": "my-instance-data"
  },
  "user_tags": []
}

Deleting a remote-region copy of a snapshot with the API

Make a DELETE /snapshots/{id}in the target region where the remote copy is located.

curl -X DELETE https://us-east.iaas.cloud.ibm.com/v1/snapshots/{id}

Creating a cross-regional copy with Terraform

To create a copy of the snapshot in a remote region, use the ibm_is_snapshot resource. The source snapshot must in Stable status for the copy to be created successfully. The created snapshot uses the customer-defined encryption key if the CRN of an encryption key was also specified. The following example creates a copy in the target region by using the ID of the source snapshot. The copy is going to be encrypted by the encryption key that is specified by its CRN.

resource "ibm_is_snapshot" "snapshot" {
  name 		      = "my-cross-regional-snapshot"
  source_snapshot = "r138-4463eb2c-4913-43b1-b9bf-62a94f74c146"
  encryption_key  = "crn:bluemix:public:kms:us-south:a/df0564dd126042ebb03e0224728ce939:4957299d-0ba0-487f-a1a0-c724a729b8b4:key:0cb88b98-9261-4d07-8329-8f594b6641b5"
}

For more information about the arguments and attributes, see ibm_is_snapshot.

Deleting a remote region copy with Terraform

Use the terraform destroy command to conveniently destroy a remote object such as a cross-regional copy of a snapshot. The following example shows the syntax for deleting a snapshot. Substitute the actual ID of the snapshot in for ibm_is_snapshot.example.id.

terraform destroy --target ibm_is_snapshot.example.id

For more information, see terraform destroy.

Deleting snapshots in the console

You can delete any snapshot for a volume or all snapshots for a volume. To be able to delete a snapshot, it must meet to the following prerequisites:

• Be in a stable or pending state.
• Not be actively restoring a volume.

An easy way to determine whether you can delete a snapshot is to look in the console for the list of snapshots and check its status. You can delete all snapshots for a volume. Deleting all snapshots requires further confirmation in the console.

Deleting snapshots from the CLI

You can delete any snapshot for a volume or all snapshots for a volume. To be able to delete a snapshot, it must meet to the following prerequisites:

• Be in a stable or pending state.
• Not be actively restoring a volume.

Deleting snapshots with the API

You can delete any snapshot for a volume or all snapshots for a volume. To be able to delete a snapshot, it must meet to the following prerequisites:

• Be in a stable or pending state.
• Not be actively restoring a volume.

curl -X DELETE \
"$vpc_api_endpoint/v1/snapshots/7528eb61-bc01-4763-a67a-a414a103f96d?version=2022-12-22&generation=2" \
     -H "Authorization: Bearer ${API_TOKEN}"

curl -X DELETE \
"$vpc_api_endpoint/v1/snapshots?source_volume.id=_volume-id_&version=2022-12-22&generation=2" \
     -H "Authorization: Bearer ${API_TOKEN}"

Deleting snapshots with Terraform

You can delete any snapshot for a volume or all snapshots for a volume. To be able to delete a snapshot, it must meet to the following prerequisites:

• Be in a stable or pending state.
• Not be actively restoring a volume.

terraform destroy --target ibm_is_snapshot.my-snapshot

resource "ibm_is_volume" "storage" {
  name                 = "example-volume"
  profile              = "general-purpose"
  zone                 = "us-south-1"
  delete_all_snapshots = true
}