Create and manage regional Persistent Disk volumes


Regional Persistent Disk is a storage option that lets you implement high availability (HA) services in Compute Engine. Regional Persistent Disk synchronously replicates data between two zones in the same region and ensures HA for disk data for up to one zonal failure. You can use regional Persistent Disk with your virtual machine (VM) in one of the following ways:

This document explains how to do the following tasks for regional Persistent Disk:

  • Create and manage regional Persistent Disk volumes.
  • Add a regional Persistent Disk volume to your VMs.

Before you begin

  • Review the differences between different types of Persistent Disk.
  • Review the basics of regional Persistent Disk.
  • Read about regional Persistent Disk failover.
  • If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine as follows.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init
    2. Set a default region and zone.

    Terraform

    To use the Terraform samples on this page from a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

    1. Install the Google Cloud CLI.
    2. To initialize the gcloud CLI, run the following command:

      gcloud init
    3. Create local authentication credentials for your Google Account:

      gcloud auth application-default login

    For more information, see Set up authentication for a local development environment.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init

Limitations

  • You can attach regional Persistent Disk only to VMs that use E2, N1, N2, and N2D machine types.
  • You cannot create a regional Persistent Disk from an image.
  • When using read-only mode, you can attach a regional balanced Persistent Disk to a maximum of 10 VM instances.
  • The minimum size of a regional standard Persistent Disk is 200 GiB.
  • You can only increase the size of a regional Persistent Disk volume; you can't decrease its size.
  • Regional Persistent Disk volumes have different performance characteristics than zonal Persistent Disk volumes. For more information, see Block storage performance.
  • If you create a regional Persistent Disk by cloning a zonal disk, then the two zonal replicas aren't fully in sync at the time of creation. After creation, you can use the regional disk clone within 3 minutes, on average. However, you might need to wait for tens of minutes before the disk reaches a fully replicated state and the recovery point objective (RPO) is close to zero. Learn how to check if your regional Persistent Disk is fully replicated.

Create a new VM with regional Persistent Disk

When creating a VM, you can optionally include regional Persistent Disk volumes as additional disks.

To create and attach a regional Persistent Disk volume to a VM during VM creation, see Create a VM instance with additional non-boot disks or Create a new instance template.

Add a regional Persistent Disk volume to your VM

Create a regional Persistent Disk volume and attach it to a VM. The VM must be in the same region as your disks.

If you create a disk in the Google Cloud console, the default disk type is pd-balanced. If you create a disk using the gcloud CLI or REST, the default disk type is pd-standard.

Console

You must first create the regional Persistent Disk volume and then attach it to an existing VM instance. You can't create regional Persistent Disk volumes as boot disks because they can't be force-attached during a failover.

Create a regional Persistent Disk volume

  1. In the Google Cloud console, go to the Disks page.

    Go to Disks

  2. Select the required project.

  3. Click Create disk.

  4. Specify a Name for your disk.

  5. For the Location, choose Regional.

  6. Select the Region and Zone. You must select the same region when you create your VM.

  7. Select the Replica zone in the same region. Make a note of the zones that you select because you must attach the disk to your VM in one of those zones.

  8. Select the Disk source type.

  9. Select the Disk type and Size. The default is a 100 GiB balanced Persistent Disk.

  10. Click Create to finish creating your disk.

Attach your regional Persistent Disk volume to your VM

  1. To attach a disk to a VM, go to the VM instances page.

    Go to VM instances

  2. In the Name column, click the name of the VM.

  3. Click Edit .

  4. Click +Attach existing disk.

  5. Choose the regional Persistent Disk to add to your VM.

  6. If you see a warning that indicates the selected disk is already attached to another instance, select the Force-attach disk box to force-attach the disk to the VM that you are currently editing.

    For more information on use cases for force-attaching regional Persistent Disk volumes, see Regional Persistent Disk failover.

  7. Click Save.

  8. On the Edit VM page, click Save.

gcloud

Create and attach a regional Persistent Disk volume by using the Google Cloud CLI:

  1. Create a regional Persistent Disk volume by using the compute disks create command. If you need a regional SSD Persistent Disk for additional throughput or IOPS, include the --type flag and specify pd-ssd.

    gcloud compute disks create DISK_NAME \
        --size=DISK_SIZE \
        --type=DISK_TYPE \
        --region=REGION \
        --replica-zones=ZONE1,ZONE2
    

    Replace the following:

    • DISK_NAME: the name of the new disk
    • DISK_SIZE: the size, in GiB, of the new disk
    • DISK_TYPE: the type of the Persistent Disk. The default value is pd-standard.
    • REGION: the region for the regional disk to reside in, for example: europe-west1
    • ZONE1,ZONE2: the zones within the region where the two disk replicas are located, for example: europe-west1-b,europe-west1-c
  2. Attach the disk to a running or stopped VM by using the compute instances attach-disk command with the --disk-scope flag set to regional.

    gcloud compute instances attach-disk VM_NAME \
        --disk=DISK_NAME \
        --disk-scope=regional
    

    Replace the following:

    • VM_NAME: the name of the VM to which you're adding the new regional Persistent Disk volumes
    • DISK_NAME: the name of the new disk that you're attaching to the VM

Terraform

To create a regional Persistent Disk volume, you can use the google_compute_region_disk resource.

resource "google_compute_region_disk" "regiondisk" {
  name                      = "region-disk-name"
  snapshot                  = google_compute_snapshot.snapdisk.id
  type                      = "pd-ssd"
  region                    = "us-central1"
  physical_block_size_bytes = 4096
  size                      = 11

  replica_zones = ["us-central1-a", "us-central1-f"]
}

REST

  1. To create a regional Persistent Disk volume, construct a POST request to the compute.regionDisks.insert method. To create a blank disk, don't specify any image or snapshot sources.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/disks
    {
     "name": "DISK_NAME",
     "region": "projects/PROJECT_ID/regions/REGION",
     "replicaZones": [
       "projects/PROJECT_ID/zones/ZONE1",
       "projects/PROJECT_ID/zones/ZONE2"
     ],
     "sizeGb": "DISK_SIZE",
     "type": "projects/PROJECT_ID/regions/REGION/diskTypes/DISK_TYPE"
    }
    

    Replace the following:

    • PROJECT_ID: your project ID
    • REGION: the region for the regional disk to reside in, for example: europe-west1
    • DISK_NAME: the name of the new disk
    • ZONE1,ZONE2: the zones where replicas of the new disk should be located
    • DISK_SIZE: the size, in GiB, of the new disk
    • DISK_TYPE: the type of the Persistent Disk. The default value is pd-standard.
  2. To attach the disk, construct a POST request to the compute.instances.attachDisk method and include the URL to the Persistent Disk volume that you created.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/attachDisk
    {
     "source": "/projects/PROJECT_ID/regions/REGION/disks/DISK_NAME"
    }
    

    Replace the following:

    • PROJECT_ID: your project ID
    • ZONE: the location of your VM
    • VM_NAME: the name of the VM to which you're adding the new Persistent Disk volume
    • REGION: the region where the regional disk is located
    • DISK_NAME: the name of the new disk

After you create and attach a new disk to a VM, you must format and mount the disk, so that the operating system can use the available storage space.

Use regional Persistent Disk as a VM boot disk

Attach a regional Persistent Disk as a boot disk for stateful workloads that are provisioned ahead of time, before you provision a production workload. Regional Persistent Disk is not intended for hot standbys, because regional boot disks cannot be attached simultaneously to two VMs.

You can only create regional Persistent Disk from snapshots; it is not possible to create a regional Persistent Disk from an image.

To use a regional Persistent Disk as a VM boot disk:

  1. Create a regional disk from a snapshot.
  2. Attach the disk as a boot disk using the following instructions.

Create a new VM with regional Persistent Disk boot disks

When setting up a highly available VM, you can create the primary VM with regional Persistent Disk boot disks. This lets you restart the VM in case of a zonal outage.

In a high availability setup, where the boot device is a regional Persistent Disk, Google recommends that you don't pre-create and pre-run the standby instance. Instead, at the failover stage, attach the existing regional disk when you create the standby instance by using the forceAttach option.

To create a VM with a boot disk that is a regional Persistent Disk:

gcloud

gcloud compute instances create PRIMARY_INSTANCE_NAME  \
 --zone=ZONE  \
 --create-disk=^:^name=REPD_DISK_NAME:scope=regional:boot=true:source-snapshot=SNAPSHOT_NAME:replica-zones=ZONE,REMOTE_ZONE

When specifying the disk parameters, the characters ^:^ specify that the separation character between parameters is a colon (:). This lets you use a comma (,) when specifying the replica-zones parameter.

Replace the following:

  • PRIMARY_INSTANCE_NAME with a name for the VM
  • ZONE with the name of the zone where you want to create the VM
  • REPD_DISK_NAME with a name for the regional Persistent Disk
  • SNAPSHOT_NAME with the name of the snapshot you created for the boot disk
  • REMOTE_ZONE with the alternate zone for the regional Persistent Disk

REST

To create a new VM with regional disk during VM creation, specify boot: 'true' and replicaZones. For example:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances
{
 "name": "VM_NAME",
 "disks": [{
    "boot": true,
    "initializeParams": {
      "sourceSnapshot": "global/snapshots/BOOT_SNAPSHOT_NAME",
      "replicaZones": [
           "projects/PROJECT_ID/zones/ZONE",
           "projects/PROJECT_ID/zones/REMOTE_ZONE"]
   }
  }],
}

Replace the following:

  • PROJECT_ID: your project ID
  • ZONE: the name of the zone where you want to create the VM
  • VM_NAME: a name for the VM
  • BOOT_SNAPSHOT_NAME: the name of the boot disk snapshot
  • REMOTE_ZONE: the remote zone for the regional Persistent Disk

To create a second VM in the failover zone to recover a primary VM that uses regional Persistent Disk for the boot disk:

gcloud

gcloud compute instances create STANDBY_VM_NAME  \
 --zone=ZONE  \
 --disk=boot=yes,name=DISK_NAME,scope=regional,force-attach=true

Replace the following:

  • STANDBY_VM_NAME with the name of the standby VM
  • ZONE with the name of the zone where the regional Persistent Disk is replicated to
  • DISK_NAME with the name of the regional Persistent Disk that you want to attach.

Optional: If you can't successfully detach the regional Persistent Disk boot disk from the VM that it was originally attached to due to an outage or failure, include force-attach=true.

Attach a regional Persistent Disk as a boot disk to an existing VM

Use the following steps to failover to a secondary VM that is running in the backup zone, by attaching the regional Persistent Disk to the VM as the boot disk. These steps assume you have already created the regional Persistent Disk from a standard snapshot.

gcloud

  1. Stop the VM.
    gcloud compute instances stop STANDBY_VM_NAME  --zone=ZONE
    
  2. Detach the current boot disk from the VM.
    gcloud compute instances detach-disk STANDBY_VM_NAME  
    --zone=ZONE --disk=CURRENT_BOOT_DEVICE_NAME
  3. Attach the regional Persistent Disk to the VM.
    gcloud compute instances attach-disk STANDBY_VM_NAME  
    --zone=ZONE
    --disk=REPD_DISK_NAME
    --disk-scope=regional --force-attach
  4. Restart the VM.

    gcloud compute instances start STANDBY_VM_NAME
    

Replace the variables in the previous commands with the following:

  • STANDBY_VM_NAME: the name of the VM to which you want to attach the regional Persistent Disk
  • ZONE: the zone in which the VM is located
  • CURRENT_BOOT_DEVICE_NAME: the name of the boot disk being used by the VM. This is usually the same as the name of the VM.
  • REPD_DISK_NAME: the name of the regional Persistent Disk that you want to attach to the VM as a boot disk

Optional: If you can't successfully detach the regional Persistent Disk boot disk from the VM that was originally attached to due to an outage or failure, include the flag --force-attach.

REST

  1. Stop the VM.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/STANDBY_VM_NAME/stop
    
  2. Detach the current boot disk from the VM.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/STANDBY_VM_NAME/detachDisk?deviceName=CURRENT_BOOT_DEVICE_NAME
    
  3. Attach the regional Persistent Disk to the VM.

    Construct a POST request to the compute.instances.attachDisk method, and include the URL to the regional Persistent Disk volume:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/STANDBY_VM_NAME/attachDisk
    {
    "source": "compute/v1/projects/PROJECT_ID/regions/REGION/disks/REPD_DISK_NAME",
    "boot": true
    }
  4. Restart the VM.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/STANDBY_VM_NAME/start
    

Replace the variables in the previous commands with the following:

  • PROJECT_ID: your project ID
  • STANDBY_VM_NAME: the name of the VM to which you want to attach the regional Persistent Disk
  • ZONE: the zone in which the VM is located
  • CURRENT_BOOT_DEVICE_NAME: the name of the boot disk being used by the VM. This is usually the same as the name of the VM.
  • REGION: the region in which the regional Persistent Disk is located
  • REPD_DISK_NAME: the name of the regional Persistent Disk that you want to attach to the VM as a boot disk

Optional: If you can't successfully detach the regional Persistent Disk boot disk from the VM that was originally attached to due to an outage or failure, include "forceAttach": true in the request body.

List and describe your regional Persistent Disk volumes

You can view a list of all your configured regional Persistent Disk volumes, and information about their properties, including the following:

  • Disk ID
  • Disk name
  • Size
  • Disk type
  • Region
  • Zonal replicas

To view detailed information about your regional Persistent Disk volumes, use one of the following: REST and the gcloud CLI.

Resize a regional Persistent Disk

If VMs with regional Persistent Disks require additional storage space, IOPS, or throughput, you can resize the disks. If you need to separate your data into unique volumes, create multiple secondary disks for the VM. You can resize disks at any time, regardless of whether the disk is attached to a running VM.

The command for resizing a regional Persistent Disk is identical to that for resizing a standard Persistent Disk. However, there is an additional flag for the region.

You can only increase, and not decrease, the size of a disk. To decrease the disk size, you must create a new disk with a smaller size. Until you delete the original, larger disk, you are charged for both disks.

Console

Resize a regional Persistent Disk.

  1. In the Google Cloud console, go to the Disks page.

    Go to Disks

  2. Select the disk you want to resize.

  3. Click Edit at the top of the page.

  4. Enter the size, in GiB, for the disk.

  5. Click Save to finish resizing the disk.

The new disk size is displayed in the list of disks.

gcloud

In the gcloud CLI, resize the regional Persistent Disk by using the compute disks resize command.

gcloud compute disks resize DISK_NAME \
    --region=REGION  \
    --size=DISK_SIZE

Replace the following:

  • DISK_NAME: the name of the disk that you're resizing
  • REGION: the region where the disk is located
  • DISK_SIZE: the new size, in GiB, of the disk.

Terraform

To change the size of a regional Persistent Disk, you can use the google_compute_region_disk resource and use the size parameter.

resource "google_compute_region_disk" "regiondisk" {
  name                      = "region-disk-name"
  snapshot                  = google_compute_snapshot.snapdisk.id
  type                      = "pd-ssd"
  region                    = "us-central1"
  physical_block_size_bytes = 4096
  size                      = 11

  replica_zones = ["us-central1-a", "us-central1-f"]
}

If you include the size parameter along with the image or snapshot parameter, the size value must be equal to or greater than the size of the image or snapshot.

If you omit the image and snapshot parameters, you can set the size parameter to less than the existing disk size. If you do this, Terraform destroys the disk and creates a new empty Persistent Disk. During the re-creation, Terraform doesn't copy over other data that isn't also included in the Terraform configuration, such as labels or snapshot schedules. To prevent Terraform from destroying and re-creating a disk, you can add the lifecycle.prevent_destroy = true setting to the Terraform configuration.

REST

To resize the regional Persistent Disk, construct a POST request to the compute.regionDisks.resize method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/disks/DISK_NAME/resize

{
  "sizeGb": "DISK_SIZE"
}

Replace the following:

  • PROJECT_ID: your project ID
  • REGION: the region where your disk is located
  • DISK_NAME: the name of the disk that you're resizing
  • DISK_SIZE: the new size, in GiB, of the disk.

After you resize the disk, you must resize the file system so that the operating system can access the additional space.

Share a read-only Persistent Disk between multiple VMs

You can attach a non-boot Persistent Disk to more than one VM in read-only mode, which lets you share static data between multiple VMs. Sharing static data between multiple VMs from one Persistent Disk is cheaper than replicating your data to unique disks for individual VMs.

If you need to share dynamic storage space between multiple VMs, you can use one of the following options:

If you have a Persistent Disk with data that you want to share between multiple VMs, detach it from any read/write VMs and attach it to one or more VMs in read-only mode.

Console

Share a read-only Persistent Disk between multiple VMs.

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. Click the name of the VM to which you want to attach the disk. The VM instance details page opens.

  3. At the top of the page, click Edit.

  4. In the Additional disks section, click Attach existing disk.

  5. Select the regional Persistent Disk from the list.

  6. In the Mode section, select Read only.

  7. Click Done.

  8. At the bottom of page, click Save to apply your changes to the VM.

gcloud

In the gcloud CLI, share a read-only Persistent Disk between multiple VMs by using the compute instances attach-disk command with the --disk-scope flag set to regional and the --mode flag set to ro.

gcloud beta compute instances attach-disk /VM_NAME \
    --disk=DISK_NAME \
    --disk-scope=regional \
    --mode=ro

Replace the following:

  • VM_NAME: the name of the VM to which you want to attach the Persistent Disk
  • DISK_NAME: the name of the disk that you want to attach

REST

To share a read-only Persistent Disk between multiple VMs, construct a POST request to the compute.instances.attachDisk method. In the request body, specify the mode parameter as READ_ONLY.

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/attachDisk

{
  "source": "regions/REGION/disks/DISK_NAME",
  "mode": "READ_ONLY"
}

Replace the following:

  • PROJECT_ID: your project ID
  • ZONE: the zone of the VM
  • VM_NAME: the name of the VM to which you want to attach the Persistent Disk.
  • REGION: the region where your disk is located
  • DISK_NAME: the name of the disk that you're attaching

After you attach the disk, connect to each VM to which you want to attach this disk in read-only mode and then mount the disk.

Migrate a zonal Persistent Disk to a regional Persistent Disk

To convert an existing zonal Persistent Disk to a regional Persistent Disk, create a new regional disk by cloning an existing zonal disk. For more information, see Creating a regional disk clone from a zonal disk.

What's next