Attach a non-boot disk to a VM

This document explains how to attach a non-boot zonal disk to your VM.

When configuring disks for your virtual machine (VM) instance, you can create the non-boot disks in the following ways:

  • Create and attach the disks while creating the VM
  • Create the disks, create the VM, and then attach the disks to the VM.

This page explains how to attach disks that were created separately to a VM.

For boot disks, you can create a boot disk from an OS image or a disk snapshot, and use that disk to create a VM. For more information, see Create a customized boot disk.

Required roles and permissions

To get the permissions that you need to attach a disk to a VM, ask your administrator to grant you the following IAM roles on the project:

  • Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
  • To connect to a VM instance that can run as a service account: Service Account User (v1) (roles/iam.serviceAccountUser role)

For more information about granting roles, see Manage access.

These predefined roles contain the permissions required to attach a disk to a VM. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to attach a disk to a VM:

  • To attach a disk to a VM:
    • compute.instances.attachDisk on the VM
    • compute.instances.attachDisk on the VM
    • compute.disks.use on the disk that you want to attach to the VM
  • To format and mount the attached volume: compute.instances.setMetadata on the VM

You might also be able to get these permissions with custom roles or other predefined roles.

Limitations

When attaching a disk to a VM, be aware of the following limitations:

  • You can attach up to 127 secondary, non-boot, zonal disks to a VM.
  • You can't attach a disk to a VM if doing so will exceed the maximum disk capacity for the VM.

Attach a non-boot disk to your VM

You can attach a non-boot zonal disk to a VM by using the Google Cloud console, the Google Cloud CLI, or REST.

You should specify a custom device name when attaching a disk to a VM. The name you specify is used to generate a symlink for the disk in the guest OS, which makes it easier to identify and manage disks on the VM.

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. In the Storage section, under Additional disks, click + Attach existing disk.

  5. Select the disk name.

  6. Choose the attachment mode and deletion rule for the disk.

  7. 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.

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

gcloud

To attach a disk to a 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.

Terraform

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

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

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 the VM and disk are located
  • VM_NAME: the name of the VM that you want to attach the disk to
  • DISK_NAME: the name of the disk to attach
  • DEVICE_NAME: Optional: a name that the guest OS uses to create a symlink, which helps identify the disk.

After you attach a disk to a VM, you must format and mount the disk before the guest operating system on the VM can use the available storage space.

What's next