Creating snapshot consistency groups

Creating a consistency group snapshot in the UI

In the console, you can create a consistency group snapshot of Block Storage for VPC volumes that are attached to a running virtual server instance.

1. Click the Navigation Menu icon > VPC Infrastructure > Storage > Block Storage snapshots.

2. From the list of consistency groups that is initially empty, click Create.

3. Enter the required information to define your snapshot group and select the virtual server instance that has the volumes that you want to include in your snapshot consistency group.

   Table 1. Selections for creating a snapshot

   Field	Value
   Location	Specify the geography and region for this snapshot set.
   Snapshot type	Select Multiple volumes.
   Virtual Server instance	From the list, select the server instance.
   Consistency group name	Provide a unique name for the consistency group. The name cannot exceed 64 characters. If you leave this field empty, the system auto-generates a name for you. The snapshots in the consistency group are named by using the first 16 characters of the group name and 3-4 auto-generated characters.
   Resource group	Select a Resource group for the snapshot, or use the default. You can't change the resource group after the snapshot is created.
   Tags	Specify any user tags that you want to identify this resource.
   Access management tags	Specify any access management tags for this resource.
   Volumes	Select the volumes that you want to include in the group from the list.

4. Click Create. You're returned to the screen that you started from. Messages are displayed while the snapshots and the consistency group are being created and when they are ready. The snapshots and the consistency group are displayed on the Block Storage snapshots for VPC page, on their respective tabs. For more information, see View snapshot details in the UI.

Creating a consistency group snapshot from the CLI

Before you can use the CLI, you must install the IBM Cloud CLI and the VPC CLI plug-in. For more information, see the CLI prerequisites.

1. Log in to IBM Cloud®.

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

   This command returns a URL and prompts for a passcode. Go to that URL in your browser and log in. If successful, you get a one-time passcode. Copy this passcode and paste it as a response on the prompt. After successful authentication, you are prompted to choose your account. If you have access to multiple accounts, select the account that you want to log in as. Respond to any remaining prompts to finish logging in.

2. Select the current generation of VPC.

   ibmcloud is target --gen 2
   

3. List the volumes that are attached to the instance that you want to capture in a snapshot consistency group. Note the volume IDs in the output.

   ibmcloud is instance INSTANCE
   

4. Use the snapshot-consistency-group-create command to create a consistency group. Provide the new snapshot's name and the ID of the source volume for each snapshot that is going to be part of the consistency group.

   If the source volume has user_managed encryption, you must provide the --encryption_key. The --encryption_key property must not be specified otherwise.

   ibmcloud is snapshot-consistency-group-create --snapshots '[{
        "name": "snapshot-no-1",
        "source_volume": {"id": "r106-bf595773-9922-4dd4-9a3c-998b10022e0c"},
        "user_tags": ["env:dev", "env:test"]
   }, {
        "name": "snapshot-no-2",
        "source_volume": {"id": "r106-aeb2bbe6-1d3c-4186-82ce-abddb03e243e"},
        "user_tags": ["env:dev", "env:test"]
   }]' --delete-snapshot-on-delete false --name multiple-snapshots-consistency-group-1 
   
   Creating snapshot consistency group under account Test Account as user test.user@ibm.com...
                               
   ID                          r006-4625d29b-3ac9-4bee-aca8-9366c4fd0c44   
   Name                        multiple-snapshots-consistency-group-1   
   CRN                         crn:v1:bluemix:public:is:us-south:a/a1234567::snapshot-consistency-group:r006-4625d29b-3ac9-4bee-aca8-9366c4fd0c44   
   Href                        https://us-south.iaas.cloud.ibm.com/v1/snapshots/r006-4625d29b-3ac9-4bee-aca8-9366c4fd0c44   
   Status                      pending   
   Backup policy plan          -   
   Delete snapshot on delete   false   
   Source Snapshot             -   
   Resource group              ID                                 Name      
                               11caaa983d9c4beb82690daab08717e9   Default      
                               
   Created                     2023-12-05T17:32:53+05:30   
   Service Tags                - 
   

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

Creating a consistency group snapshot with the API

Before you begin, retrieve the instance details of the virtual server instance that you want to capture in the snapshot consistency group. Note the CRNs or IDs of the volume_attachments and the boot_volume_attachment.

You can programmatically create a consistency group by calling the /snapshot_consistency_groups method in the VPC API as shown in the following sample request.

curl -X POST \
"$vpc_api_endpoint/v1/snapshot_consistency_groups?version=2023-12-05&generation=2"\
 -H "Authorization: $iam_token" \
 -d '{
   "delete_snapshots_on_delete":true,
   "name": "my-snapshot-consistency-group",
   "resource_group":{"id": "2d1bb5a8-40a8-447a-acf7-0eadc8aeb054"},
   "snapshots": {
    {
     "name": "my-snapshot-1",
     "source_volume": {"crn": "crn:[...]"},
     "encryption_key"; "crn:[...]"
    },
    {
     "name": "my-snapshot-2",
     "source_volume": {"crn": "crn:[...]"},
     "encryption_key"; "crn:[...]"
    },
   }"

If the source volume has user_managed encryption, you must provide the encryption_key. The encryption_key property must not be specified otherwise.

A successful response looks like the following example.

{
  "created_at": "2023-12-05T20:18:18Z",
  "crn": "crn:[...]",
  "delete_snapshots_on_delete": true,
  "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r006-f6bfa329-0e36-433f-a3bb-0df632e79263",
  "id": "r006-f6bfa329-0e36-433f-a3bb-0df632e79263",
  "lifecycle_state": "pending",
  "name": "my-snapshot-consistency-group",
  "resource_group": {
    "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956",
    "id": "2d1bb5a8-40a8-447a-acf7-0eadc8aeb054",
    "name": "Default"
  },
  "resource_type": "snapshot_consistency_group",
  "service_tags": [],
  "snapshots": [
    {
      "crn": "crn:[...]",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r006-076191ba-49c2-4763-94fd-c70de73ee2e6",
      "id": "r006-076191ba-49c2-4763-94fd-c70de73ee2e6",
      "name": "my-snapshot-1",
      "resource_type": "snapshot"
    },
    {
      "crn": "crn:[...]",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r006-07e34f34-49c2-4763-94fd-c70de73ae342",
      "id": "r006-07e34f34-49c2-4763-94fd-c70de73ae342",
      "name": "my-snapshot-2",
      "resource_type": "snapshot"
    }
  ]
}

Creating a consistency group 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 regional specific 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"
}

1. Import the details of the virtual server instance as a read-only data source. After the data source is created, you can access the attribute references for boot_volume and volume_attachments.

data "ibm_is_instance" "example" {
  name        = ibm_is_instance.example.name
  private_key = file("~/.ssh/id_rsa")
  passphrase  = ""
}

1. To create a consistency group of snapshots, use the ibm_is_snapshot_consistency_group resource. The following example creates a consistency group of two volumes.

resource "ibm_is_snapshot_consistency_group" "is_snapshot_consistency_group" {
  name = "my-data-consistency-group"
  snapshots {
    [ 
      name = "snapshot-1"
      source_volume = {id = "r016-0a74c6af-f9f5-4671-9025-c4efd41ac6da"}
      user_tags = ["my-tag"]
    ].
    [ 
      name = "snapshot-2"
      source_volume = {id = "r016-0a74c6af-f9f5-4671-9025-c4efd41ac6db"}
      user_tags = ["my-tag"]
    ]
  }
}

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