Adding or Resizing Regional Persistent Disks

Beta

This is a Beta release of Google Compute Engine regional persistent disk. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

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. As a best practice, do not use regional persistent disks for boot disks. In a failover situation, they do not force-attach to another VM instance.

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

• They must be mounted in Read/Write (RW) mode. They do not support Read Only (RO) mode.
• They support force-attaching your replicated disk to another 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 traffic can be directed to another VM instance and your replicated disk can be force-attached to another VM instance in the same or a secondary zone. Force-attach time is designed to occur in less than one minute.

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.

Before you begin

• If you want to use the command-line examples in this guide:
  1. Install 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 gcloud beta 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.

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.

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

gcloud

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

1. Use the 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.

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

   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 disks are located.
     You must select two zones. Example: europe-west1-a,europe-west1-b.

2. After you create the disk, attach it to any running or stopped instance. Use the gcloud beta compute instances attach-disk command and include the --disk-scope regional flag to indicate that the disk is regional:

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

   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.
   • --disk-scope is set to regional.

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.

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.

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

   where:

   • [PROJECT_ID] is your project ID.
   • [ZONE1] is the zone where the new disk is located. This is the same zone where you will attach the disk to an instance.
   • [ZONE2] is the location of the replica disk.
   • [DISK_NAME] is the name of the new disk.

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://www.googleapis.com/compute/beta/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 zone where your instance and new disk are located.
   • [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 force-attach command.

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. There is no evidence of lost or reverted data on the regional persistent disks.

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.

gcloud

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

gcloud beta compute instances attach-disk [INSTANCE_NAME]
--disk [DISK_NAME] --disk-scope [REGIONAL] --force-attach [TRUE]

where:

• [INSTANCE_NAME] is the name of the new VM instance in the region.
• [DISK_NAME] is the name of the disk.
• --disk-scope is set to regional.

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 parameter is required to attach the disk to the new VM instance even though the primary instance still has the disk.

    POST https://www.googleapis.com/compute/beta/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.
• [REGION] is the region where your instance and new disk are located.
• [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 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

gcloud

In the gcloud tool, use the 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 beta compute disks resize [DISK_NAME] --region [DISK REGION]--size [DISK_SIZE]

where:

• [DISK_NAME] is the name of the disk that you are resizing.
• [DISK REGION] is the region where the disk is located.
• [DISK_SIZE] is the new size for 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://www.googleapis.com/compute/beta/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 for 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.

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 disks snapshot command and specify the --zone flag and --snapshot-name flag.

gcloud compute disks snapshot [DISK_NAME] --zone [DISK_ZONE]
--snapshot-name [SNAPSHOT_DISK_NAME]

where:

• [DISK_NAME] is the name of the disk you want to snapshot.
• [DISK_ZONE] is the zone where the disk resides.
• [SNAPSHOT_DISK_NAME] is the name of the newly-snapshotted disk.

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

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

where:

• [DISK_NAME] is the name of the new disk.
• [DISK_REGION] is the region where the disk will reside.
• [ZONE1,ZONE2] are the zones where the replicated 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://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/regions/[REGION]/disks/[DISK]/createSnapshot

{

}

where:

• [PROJECT_ID] is your project ID.
• [ZONE] is the zone where your disk is located.
• [DISK] 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://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/regions/[REGION]

{
 "name": "[DISK_NAME]",
 "replicaZones": "projects/[PROJECT_NAME]/zones/[ZONE1]"
                  "projects/[PROJECT_NAME]/zones/[ZONE2]"
}

where:

• [PROJECT_ID] is your project ID.
• [ZONE1] is the zone where your instance and new disk are located.
• [ZONE2] is the location of the replicated disk.
• [DISK_NAME] is the name of the new disk.

What's next

• Instance Groups.
• Building Scalable and Resilient Web Applications on Google Cloud Platform.
• GCP Disaster Recover Cookbook.