Adding or resizing regional persistent disks

This page explains how to add and manage regional persistent disk storage resources. When resizing a regional persistent disk, you can only increase its size. You cannot reduce the size of a persistent disk.

Regional persistent disks have similar qualities to zonal persistent disks but differ in several ways:

• They cannot be used as boot disks.
• They support force-attachment to another virtual machine (VM) instance in the event of a zone failure.
• You can create a regional persistent disk from a snapshot, but not an image.
• There are performance differences, which are described in the storage options document.

Regional persistent disk provides synchronous replication of data between two zones in one region. In the unlikely event of a zone failure, your workload can fail over to another VM instance in the same or a secondary zone. You can then force-attach your regional persistent disk to that instance. Force-attach time is estimated at less than one minute.

It is a best practice to back up your regional persistent disks using snapshots to prevent unintended data loss.

Regional persistent disk is a suitable option to consider when designing robust systems and for stateful database services like MySQL and Postgres that require high availability.

Read Compute Engine Storage Options to compare resources and their performance.

Beta

This is a Beta release of Compute Engine 16 KB physical block size selection. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

Every persistent disk you create has a default physical block size of 4 KB. If your database app requires an increased physical block size, you can select 16 KB when creating your disk. This feature is not supported for boot disks. If you want to change the size of an existing disk's physical block, you must snapshot the disk, then create a new disk. You cannot directly edit the disk's physical block size.

Before you begin

• If you want to use the command-line examples in this guide:
  1. Install or update to the latest version of the gcloud command-line tool.
  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.

Note: Use compute disks describe [DISK_NAME] and include the --region [NEW_DISK_REGION] flag, or use the API compute.regionDisks.list to check the status of your disks.

Limitations

Regional persistent disk have the following limitations:

• They can't be used as boot disks.
• 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.
• You can't use a regional persistent disk with a memory-optimized machine type.

Adding a regional persistent disk to your instance

Create a regional standard persistent disk or a regional SSD persistent disk and attach it to an instance. If you do not have any instances, you must first create and start a new instance. You must create your instance in the same region as your disks.

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 instance
• compute.disks.use permission 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. Go to the Disks page.

   Go to the Disks page

2. Select your project.
3. Click Create Disk.
4. Specify a Name for your disk.
5. Choose a disk Type.
6. Check the Replicate this disk within region box.
7. Select the region.

   Make a note of the region because you must select the same region when you create your instance.

8. Select two zones in that region, and click OK.

   You must select two zones. Note the zones that you select because you must attach the disk to your instance in one of those zones.

9. Choose the Source Type.
10. Optionally, choose your Physical block size (KB). The disk default size is 4 KB. However, you can select 16 KB from the drop-down menu to increase the physical block size of the disk. This feature is in beta.
11. Select the Encryption.
12. Click Create to finish creating your disk.

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

When attaching a disk to an instance, you might receive an error message if the disk is already attached to another instance. You might have to force-attach the disk to the instance by checking the Force-attach disk box after you click Attach existing disk.

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

gcloud

Create and attach a regional persistent disk with the gcloud tool:

1. Use the compute disks create command to create new regional persistent disks. If you need a regional SSD persistent disk for additional throughput or IOPS, include the --type flag and specify pd-ssd. Optionally, add the --physical-block-size flag to set the physical block size. If you include this flag, you must use the beta compute disks create command. This feature is in beta.

   gcloud beta compute disks create [DISK_NAME] \
       --size [DISK_SIZE] \
       --type [DISK_TYPE] \
       --region [REGION] \
       --replica-zones [ZONE1],[ZONE2] \
       --physical-block-size [BLOCK_SIZE]
   

   where:

   • [DISK_NAME] is the name of the new disk.
   • [DISK_SIZE] is the size of the new disk in GB.
   • [DISK_TYPE] is the type of persistent disk. Either pd-standard or pd-ssd.
   • [REGION] is the region where the regional disk will reside. Example: europe-west1.
   • [ZONE1],[ZONE2] are the zones within the region where the two disk replicas are located.
     You must select two zones. Example: europe-west1-a,europe-west1-b.
   • [BLOCK_SIZE] is either 4096 (4 KB) or 16384 (16 KB). 4 KB is the default physical block size. 16 KB is an increased physical block size. Use the beta compute disks create command with this flag. This feature is in beta.

2. After you create the disk, attach it to any running or stopped instance. Use the compute instances attach-disk command and include the --disk flag.

   gcloud compute instances attach-disk [INSTANCE_NAME] \
       --disk [DISK_NAME]
   

   where:

   • [INSTANCE_NAME] is the name of the instance where you are adding the new regional persistent disks.
   • [DISK_NAME] is the name of the new disk that you are attaching to the instance.

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

3. Use the compute disks describe command to see a description of your disk. The response includes the disk's physical block size.

API

1. In the API, construct a POST request to create a regional persistent disk. In the compute.regionDisks.insert request body, initialize a new disk with a disk name and replicaZones properties. To create a blank disk, do not specify any image or snapshot sources. Optionally, include the physicalBlockSizeBytes property to set the physical block storage size. Use the beta API method compute.regionDisks.insert for this property. This feature is in beta.

   POST https://compute.googleapis.com/compute/beta/projects/[PROJECT_ID]/regions/[REGION]
   
   {
    "name": "[DISK_NAME]",
    "physicalBlockSizeBytes": "[BLOCK_SIZE]",
    "replicaZones": [
      "projects/[PROJECT_ID]/zones/[ZONE1]",
      "projects/[PROJECT_ID]/zones/[ZONE2]"
      ],
    }
   

   where:

   • [PROJECT_ID] is your project ID.

   • [DISK_NAME] is the name of the new disk.

   • [BLOCK_SIZE] is either 4096 (4 KB) or 16384 (16 KB). 4 KB is the default physical block size. 16 KB is an increased physical block size. Use the beta API method compute.regionDisks.insert for this property. This feature is in beta.

   • [ZONE1],[ZONE2] are the zones where replicas of the new disk should be located.

2. In the API, construct a POST request to the compute.instances.attachDisk method, and include the URL to the persistent disk that you just 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]"
   }
   

   where:

   • [PROJECT_ID] is your project ID.
   • [ZONE] is the location of your instance.
   • [INSTANCE_NAME] is the name of the instance where you are adding the new persistent disk.
   • [DISK_NAME] is the name of the new disk.

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

Accessing a regional persistent disk during a zone failure

In the unlikely event of a zonal outage, your regional persistent disk can be failed over to a VM instance in another zone via the force-attach command.

If a zone where your VM instance is running becomes unavailable, it might be impossible to detach a disk from the instance because the instance can't be reached to perform the detach operation. Force-attach allows you to attach a regional persistent disk to a VM instance even if that disk is currently attached to another instance.

After you complete the force-attach operation, Compute Engine prevents the original VM from writing to the disk. Using force-attach lets you safely regain access to your data and recover your service.

A write is acknowledged back to a VM only when it is durably persisted in both replicas. If one of the replicas is unavailable, Compute Engine writes only to the healthy replica. When the unhealthy replica is back up as determined by Compute Engine, then it is transparently brought in sync with the healthy replica and the fully synchronous mode of operation resumes. This operation is transparent to a VM.

In the rare event both replicas become unavailable at the same time, or the healthy replica becomes unavailable while another one is being brought into sync, the corresponding disk becomes unavailable.

You also have the option to manually shut down the instance after you perform the force-attach step.

Intra-zone failure

It is also possible to force-attach your regional persistent disk to a VM instance in the same zone. This intra-zone failover option is available to handle outages caused by VM misconfiguration, a bad OS upgrade, or other failure modes.

Console

Create a standby VM instance and force-attach a disk to an instance.

1. Go to the VM instances page.

   Go to the VM instances page

2. Select your project.
3. Click Create instance.
4. Specify a Name for your instance.
5. Select the region where your regional persistent disk resides.
6. Select the alternate zone of the original VM instance where your disk was attached.

   Your disks are listed on the Disks page.

7. Click Management, disks, networking, SSH keys.
8. Click Disks.
9. In the Additional Disks section, click Attach existing disk.
10. Select the regional persistent disk from the drop-down list.
11. Check the box to force-attach the disk.
12. Click Done.
13. Click Create to finish creating this instance.

    The new VM instance appears on the VM instances page.
    Perform the same steps to force-attach a disk to the original instance after the zone recovers from its outage.

gcloud

In the gcloud tool, use the instances attach-disk command to attach the replica disk to a VM instance. Include the --disk-scope flag and set it to regional.

gcloud compute instances attach-disk [INSTANCE_NAME]  \
    --disk [DISK_NAME] \
    --disk-scope regional \
    --force-attach

where:

• [INSTANCE_NAME] is the name of the new VM instance in the region.
• [DISK_NAME] is the name of the disk.

After you force-attach the disk, mount the file systems on the disk, if necessary. The instance can use the force-attached disk to continue read and write operations.

API

Construct a POST request to the compute.instances.attachDisk method, and include the URL to the persistent disk that you just created. The forceAttach=true query parameter is required to attach the disk to the new VM instance even though the primary instance still has the disk.

POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/attachDisk?forceAttach=true

{
 "source": "projects/[PROJECT_ID]/regions/[REGION]/disks/[DISK_NAME]"
}

where:

• [PROJECT_ID] is your project ID.
• [ZONE] is the location of your instance.
• [INSTANCE_NAME] is the name of the instance where you are adding the new persistent disk.
• [REGION] is the region where your new regional persistent disk is located.
• [DISK_NAME] is the name of the new disk.

After you attach the replica disk, mount the file systems on the disks if necessary. The instance can use the replica disk to continue read and write operations.

Resizing a regional persistent disk

If instances 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 instance. You can resize disks at any time, regardless of whether the disk is attached to a running instance.

The command for resizing a regional persistent disk is identical to that of 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

Resizing a regional persistent disk.

1. Go to the Disks page.

   Go to the Disks page

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 the size of the disk. You cannot decrease a disk's size.

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

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

gcloud

In the gcloud tool, use the compute disks resize command. Specify the --size flag with the desired disk size in GB and the --region flag with the region where the disk is located.

gcloud compute disks resize [DISK_NAME] \
    --region [REGION]  \
    --size [DISK_SIZE]

where:

• [DISK_NAME] is the name of the disk that you are resizing.
• [REGION] is the region where the disk is located.
• [DISK_SIZE] is the new size of the disk in GB.

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

API

In the API, construct a POST request to the compute.regionDisks.resize method. In the request body, specify the sizeGb parameter and set it to the desired disk size in GB.

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

{
 "sizeGb": "[DISK_SIZE]"
}

where:

• [PROJECT_ID] is your project ID.
• [REGION] is the region where your disk is located.
• [DISK_NAME] is the name of the disk that you are resizing.
• [DISK_SIZE] is the new size of the disk in GB.

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

Sharing a regional persistent disk between multiple instances

Beta

This feature is in a pre-release state and might change or have limited support. For more information, see the product launch stages.

You can attach a non-boot persistent disk to more than one virtual machine instance in read-only mode, which allows you to share static data between multiple instances. Sharing static data between multiple instances from one persistent disk is cheaper than replicating your data to unique disks for individual instances.

If you attach a persistent disk to multiple instances, all of those instances must attach the persistent disk in read-only mode. It is not possible to attach the persistent disk to multiple instances in read-write mode. If you need to share dynamic storage space between multiple instances, you can use one of the following options:

• Connect your instances to Cloud Storage
• Connect your instances 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 instances, detach it from any read-write instances and attach it to one or more instances in read-only mode.

Note: Regional disks are replicated across two zones in one region so any instance 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 instance
• compute.disks.use permission on the disk to attach

Console

1. Go to the Instances page to see the list of instances in your project.

   Go to the Instances page

2. Click the name of the instance where you want to attach the disk. The instance details page opens.
3. At the top of the instance details page, click Edit.
4. In the Additional Disks section, click Attach existing disk.
5. Select the regional persistent disk from the drop-down list.
6. In the Mode section, select Read only.
7. Click Done.
8. At the bottom of the instance details page, click Save to apply your changes to the instance.
9. Connect to the instance and mount the disk.
10. Repeat this process to add the disk to other instances in read-only mode.

gcloud

In the gcloud tool, use the compute instances attach-disk command and specify the --mode flag with the ro option.

gcloud beta compute instances attach-disk [INSTANCE_NAME] --disk [DISK_NAME] \
    --disk-scope regional --mode ro

where:

• [INSTANCE_NAME] is the name of the instance where you want to attach the persistent disk.
• [DISK_NAME] is the name of the disk that you want to attach.

After you attach the disk, connect to the instance and mount the disk.

Repeat this command for each instance where you want to add this disk in read-only mode.

API

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

where:

• [PROJECT_ID] is your project ID.
• [ZONE] is is the zone of the instance.
• [INSTANCE_NAME] is the name of the instance where you want to attach the persistent disk.
• [REGION] is the region where your disk is located.
• [DISK_NAME] is the name of the disk that you are attaching.

After you attach the disk, connect to the instance and mount the disk.

Repeat this request for each instance where you want to add this disk in read-only mode.

Migrate a zonal persistent disk to a regional persistent disk

To convert your existing zonal persistent disks to regional persistent disks, snapshot the current persistent disk and create a regional persistent disk from the snapshot.

gcloud

In the gcloud tool, use the compute disks snapshot command and specify the --zone flag and --snapshot-name flag.

gcloud compute disks snapshot [DISK_NAME] \
    --zone [ZONE] \
    --snapshot-name [SNAPSHOT_DISK_NAME]

where:

• [DISK_NAME] is the name of the disk you want to snapshot.
• [ZONE] is where your source zonal disk is located.
• [SNAPSHOT_DISK_NAME] is the name of the newly-snapshotted disk.

Create a regional disk from a snapshot of the zonal disk using compute disks create. Specify the disk name, the --region --replica-zones, and --source-snapshot flags.

gcloud compute disks create [DISK_NAME] \
    --region [REGION] \
    --replica-zones [ZONE1],[ZONE2] \
    --source-snapshot [SNAPSHOT_DISK_NAME]

where:

• [DISK_NAME] is the name of the new disk.
• [REGION] is the region where the disk will reside.
• [ZONE1],[ZONE2] are the zones where the replicas of the new regional persistent disks will reside.
• [SNAPSHOT_DISK_NAME] is the name of the source snapshot disk.

You can use the same method to migrate regional disks to zonal disks.

API

In the API, construct a POST request to the compute.disk.createSnapshot method to create a snapshot of a disk. In the request body, specify the zone where the disk resides, the name of the disk you are snapshotting, and createSnapshot.

POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/disks/[DISK_NAME]/createSnapshot

where:

• [PROJECT_ID] is your project ID.
• [ZONE] is the zone where your disk is located.
• [DISK_NAME] is the name of the disk that you are snapshotting.

In the API, construct a POST request to create a regional persistent disk. In the compute.regionDisks.insert request body, initialize a new disk and specify the disk name and replica-zones properties. Because this is a data disk, do not include the sourceImage property, which creates a blank disk:

POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/disks

{
 "name": "[DISK_NAME]",
 "sourceSnapshot": "global/snapshots/[SNAPSHOT_NAME]",
 "replicaZones": [
 "projects/[PROJECT_ID]/zones/[ZONE1]",
 "projects/[PROJECT_ID]/zones/[ZONE2]"
 ],
}

where:

• [PROJECT_ID] is your project ID.
• [REGION] is the region where the disk will reside.
• [DISK_NAME] is the name of the new disk.
• [SNAPSHOT_NAME] is the snapshot to restore.
• [ZONE1],[ZONE2] are the zones where the replicas of the new regional persistent disks will reside. ## What's next

• Learn about persistent disk pricing.

• Learn how to create a snapshot of a persistent disk.

• Use instance groups to create your instances.

• Build scalable and resilient web applications on Google Cloud.

• See the Google Cloud disaster recovery cookbook.