Working with regional persistent disks

This page explains how to add and manage regional persistent disk storage resources.

Before you begin

• If you want to use the command-line examples in this guide, do the following:
  1. Install or update to the latest version of the Google Cloud CLI.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.
• Understand the differences between different types of persistent disks.
• Read about regional persistent disk failover.

Restrictions

• You can't use a regional persistent disk with a memory-optimized, compute-optimized, or accelerator-optimized machine type VM.
• You cannot use regional persistent disks as boot disks.
• You can attach a regional balanced persistent disk to at most 10 VM instances in read-only mode.
• You can create a regional persistent disk from a snapshot but not an image.
• The minimum size of a regional standard persistent disk is 200 GB.
• When resizing a regional persistent disk, you can only increase its size.
• Regional persistent disks perform differently from zonal persistent disks. For more information, see Block storage performance.

Check the status of your regional disks

You can check the status of your regional disks by using either of these options:

• the compute.regionDisks.list method
• the compute.disks.describe command with a disk name and the --region flag

Add a regional persistent disk to your VM

Create a regional persistent disk and attach it to a VM. If you don't have any VMs, you must first create and start a new VM. The VM must be in the same region as your disks.

If you create a disk in the console, the default disk type is pd-balanced. If you create a disk using the gcloud CLI or the Compute Engine API, the default disk type is pd-standard.

Permissions required for this task

To perform this task, you must have the following permissions:

• compute.disks.create on the project, to be able to create a new disk
• compute.instances.attachDisk on the VM
• compute.disks.use on the disk to attach

Console

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

Create a regional persistent disk.

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. Select the Region and Zone. You must select the same region when you create your VM.

6. Select the Enable regional disk replication box.

7. Select the Replicate zone. 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.

10. Click Create to finish creating your disk.

After you create your regional persistent disk, attach it to your instance.

When attaching a disk to a VM, if the disk is already attached to another VM, you can force-attach the disk to the VM by selecting the Force-attach disk box on the Attach existing disk page. For more information on use cases for force-attaching regional persistent disks, see Regional persistent disk failover.

gcloud

Create and attach a regional persistent disk by using the Google Cloud CLI:

1. In the gcloud CLI, create a regional persistent disk 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 GB, of the new disk
   • DISK_TYPE: the type of the persistent disk, for example, pd-ssd
   • 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 INSTANCE_NAME \
       --disk=DISK_NAME \
       --disk-scope=regional
   

   Replace the following:

   • INSTANCE_NAME: the name of the VM to which you're adding the new regional persistent disks
   • DISK_NAME: the name of the new disk that you're attaching to the VM

API

1. In the API, to create a regional persistent disk, 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",
    "replicaZones": [
      "projects/PROJECT_ID/zones/ZONE1",
      "projects/PROJECT_ID/zones/ZONE2"
    ],
   }
   

   Replace the following:

   • PROJECT_ID: your project ID
   • DISK_NAME: the name of the new disk
   • ZONE1,ZONE2: the zones where replicas of the new disk should be located

2. To attach the disk, construct a POST request to the compute.instances.attachDisk method and include the URL to the persistent disk that you created.

   POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_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
   • INSTANCE_NAME: the name of the VM to which you're adding the new persistent disk
   • 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.

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.

Permissions required for this task

To perform this task, you must have the following permissions:

• compute.disks.update on the disk

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 GB, for the disk.

   You can only increase, and not decrease, the size of 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 GB, of the disk.

API

In the API, 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 GB, 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

Preview

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA features might have limited support, and changes to pre-GA features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

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:

• Connect your VMs to Cloud Storage.
• Connect your VMs to Filestore.
• Create a network file server on Compute Engine.

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.

Note: Regional disks are replicated across two zones in one region. So, any VM that attaches these disks must belong to one of these two zones.

Permissions required for this task

To perform this task, you must have the following permissions:

• compute.disks.create on the project to be able to create a new disk
• compute.instances.attachDisk on the VM
• compute.disks.use permission on the disk to attach

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 INSTANCE_NAME \
    --disk=DISK_NAME \
    --disk-scope=regional \
    --mode=ro

Replace the following:

• INSTANCE_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

API

In the API, 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/INSTANCE_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
• INSTANCE_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 add this disk in read-only mode and mount the disk.

Migrate a zonal persistent disk to a regional persistent disk

To convert your 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

• Learn about persistent disk pricing.
• Create a snapshot of a persistent disk.
• Learn about instance groups or groups of VM instances.
• Build scalable and resilient web applications on Google Cloud.
• See the Google Cloud disaster recovery cookbook.