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:
- Create a new VM with regional Persistent Disk.
- Create regional Persistent Disk volumes and attach them to existing VMs.
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
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
Terraform
To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
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
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
-
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
In the Google Cloud console, go to the Disks page.
Select the required project.
Click Create disk.
Specify a Name for your disk.
For the Location, choose Regional.
Select the Region and Zone. You must select the same region when you create your VM.
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.
Select the Disk source type.
Select the Disk type and Size. The default is a 100 GiB balanced Persistent Disk.
Click Create to finish creating your disk.
Attach your regional Persistent Disk volume to your VM
To attach a disk to a VM, go to the VM instances page.
In the Name column, click the name of the VM.
Click Edit
.Click +Attach existing disk.
Choose the regional Persistent Disk to add to your VM.
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.
Click Save.
On the Edit VM page, click Save.
gcloud
Create and attach a regional Persistent Disk volume by using the Google Cloud CLI:
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 specifypd-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 diskDISK_SIZE
: the size, in GiB, of the new diskDISK_TYPE
: the type of the Persistent Disk. The default value ispd-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
Attach the disk to a running or stopped VM by using the
compute instances attach-disk
command with the--disk-scope
flag set toregional
.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 volumesDISK_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.
REST
To create a regional Persistent Disk volume, construct a
POST
request to thecompute.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 IDREGION
: the region for the regional disk to reside in, for example:europe-west1
DISK_NAME
: the name of the new diskZONE1
,ZONE2
: the zones where replicas of the new disk should be locatedDISK_SIZE
: the size, in GiB, of the new diskDISK_TYPE
: the type of the Persistent Disk. The default value ispd-standard
.
To attach the disk, construct a
POST
request to thecompute.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 IDZONE
: the location of your VMVM_NAME
: the name of the VM to which you're adding the new Persistent Disk volumeREGION
: the region where the regional disk is locatedDISK_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:
- Create a regional disk from a snapshot.
- 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 IDZONE
: the name of the zone where you want to create the VMVM_NAME
: a name for the VMBOOT_SNAPSHOT_NAME
: the name of the boot disk snapshotREMOTE_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 VMZONE
with the name of the zone where the regional Persistent Disk is replicated toDISK_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
- Stop the VM.
gcloud compute instances stop STANDBY_VM_NAME --zone=ZONE
- Detach the current boot disk from the VM.
gcloud compute instances detach-disk STANDBY_VM_NAME
--zone=ZONE --disk=CURRENT_BOOT_DEVICE_NAME - 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 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 DiskZONE
: the zone in which the VM is locatedCURRENT_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
Stop the VM.
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/STANDBY_VM_NAME/stop
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
Attach the regional Persistent Disk to the VM.
Construct a
POST
request to thecompute.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 }
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 IDSTANDBY_VM_NAME
: the name of the VM to which you want to attach the regional Persistent DiskZONE
: the zone in which the VM is locatedCURRENT_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 locatedREPD_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.
- To view the details of all regional Persistent Disk volumes in
a specific region and project, use the
compute.regionDisks.list
method. - To view the details of a specific regional Persistent Disk volume, run the
gcloud compute disks describe
command with the--region
flag, and specify the name of your disk and its region.
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.
In the Google Cloud console, go to the Disks page.
Select the disk you want to resize.
Click Edit at the top of the page.
Enter the size, in GiB, for the disk.
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 resizingREGION
: the region where the disk is locatedDISK_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.
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 IDREGION
: the region where your disk is locatedDISK_NAME
: the name of the disk that you're resizingDISK_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:
- 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.
Console
Share a read-only Persistent Disk between multiple VMs.
In the Google Cloud console, go to the VM instances page.
Click the name of the VM to which you want to attach the disk. The VM instance details page opens.
At the top of the page, click Edit.
In the Additional disks section, click Attach existing disk.
Select the regional Persistent Disk from the list.
In the Mode section, select Read only.
Click Done.
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 DiskDISK_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 IDZONE
: the zone of the VMVM_NAME
: the name of the VM to which you want to attach the Persistent Disk.REGION
: the region where your disk is locatedDISK_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
- 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.
- Learn how to monitor the replica states of regional Persistent Disk volumes.
- Learn how to determine the replication state of regional Persistent Disk.