Add a persistent disk to your VM


You can either create a blank persistent disk, or create a disk from a data source. You can use a persistent disk as a boot disk for a virtual machine (VM) instance, or as a data disk that you attach to a VM.

This document explains how to:

  • Create a blank, non-boot zonal persistent disk and attach it to your VM.

If you want to create a boot disk that you can later use to create a VM, see Create a customized boot disk.

If you want to add a Google Cloud Hyperdisk disk to your VM, see Add Hyperdisk storage to a VM.

If you need to format or mount a persistent disk on your VM, see:

For general information about Persistent Disk and the types of disks that are available, read the Persistent Disk overview.

Before you begin

  • 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

Restrictions

  • During VM creation, you can attach up to 127 secondary non-boot zonal persistent disks.
  • You can have a total attached capacity of 257 TB per VM. For information about how to ensure maximum performance with large volumes, see Logical volume size.

Adding a non-boot disk to your VM

Create and attach a non-boot zonal disk by using the Google Cloud console, the Google Cloud CLI, or REST.

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.

You should specify a custom device name when attaching the disk to a VM. The name you specify is used to generate a symlink for the disk in the guest OS, making identification easier.

Console

  1. Go to the VM instances page.

    Go to the VM instances page

  2. Click the name of the VM where you want to add a disk.

  3. On the details page, click Edit.

  4. Under Additional disks, click Add new disk.

  5. Specify a name for the disk, configure the disk's properties, and select Blank as the Source type.

  6. Optional: Under the heading Device name, select the option Use a custom device name. The name you enter is used to generate a symlink for the disk, which makes disk identification easier.

  7. Click Done to complete the disk's configuration.

  8. Click Save to apply your changes to the VM and add the new disk.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Use the gcloud compute disks create command to create the zonal persistent disk.

    gcloud compute disks create DISK_NAME \
      --size DISK_SIZE \
      --type DISK_TYPE
    

    Replace the following:

    • DISK_NAME: the name of the new disk.
    • DISK_SIZE: the size, in gigabytes, of the new disk. Acceptable sizes range, in 1 GB increments, from 10 GB to 65,536 GB inclusive.
    • DISK_TYPE: full or partial URL for the type of the persistent disk. For example, https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/diskTypes/pd-ssd.
  3. After you create the disk, attach it to any running or stopped VM. Use the gcloud compute instances attach-disk command:

    gcloud compute instances attach-disk VM_NAME \
      --disk DISK_NAME --device-name=DEVICE_NAME
    

    Replace the following:

    • VM_NAME: the name of the VM where you are adding the new zonal persistent disk
    • DISK_NAME: the name of the new disk that you are attaching to the VM.
    • DEVICE_NAME: Optional: a name that the guest OS uses to identify the disk.
  4. Use the gcloud compute disks describe command to see a description of your disk.

Terraform

To create a disk, use the google_compute_disk resource.

# Using pd-standard because it's the default for Compute Engine

resource "google_compute_disk" "default" {
  name = "disk-data"
  type = "pd-standard"
  zone = "us-west1-a"
  size = "5"
}

To attach the disk to a VM, use the google_compute_instance resource.

resource "google_compute_instance" "test_node" {
  name         = "test-node"
  machine_type = "f1-micro"
  zone         = "us-west1-a"

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-11"
    }
  }
  attached_disk {
    source      = google_compute_disk.default.id
    device_name = google_compute_disk.default.name
  }

  network_interface {
    network = "default"
    access_config {
      # Ephemeral IP
    }
  }

  # Ignore changes for persistent disk attachments
  lifecycle {
    ignore_changes = [attached_disk]
  }


}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

REST

  1. Construct a POST request to create a zonal Persistent Disk by using the disks.insert method. Include the name, sizeGb, and type properties. To create this disk as an empty and unformatted non-boot disk, don't specify a source image or a source snapshot.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks
    
    {
     "name": "DISK_NAME",
     "sizeGb": "DISK_SIZE",
     "type": "DISK_TYPE"
    }
    

    Replace the following:

    • PROJECT_ID: your project ID.
    • ZONE: the zone where your VM and new disk are located.
    • DISK_NAME: the name of the new disk.
    • DISK_SIZE: the size, in gigabytes, of the new disk. Acceptable sizes range, in 1 GB increments, from 10 GB to 65,536 GB inclusive.
    • DISK_TYPE: full or partial URL for the type of the persistent disk. For example, https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/diskTypes/pd-ssd.
  2. Construct a POST request to the compute.instances.attachDisk method, and include the URL to the zonal persistent disk that you just created:

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

    Replace the following:

    • PROJECT_ID: your project ID
    • ZONE: the zone where your VM and new disk are located
    • VM_NAME: the name of the VM where you are adding the new persistent disk
    • DISK_NAME: the name of the new disk
    • DEVICE_NAME: Optional: a name that the guest OS uses to identify the disk.

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

What's next