Attach a non-boot disk to a VM

To create or change a VM's boot disk, see Create a boot disk and Detach and reattach a boot disk, respectively.

To create a new disk, see Create a new Persistent Disk volume and Create a new Hyperdisk volume.

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 to projects, folders, and organizations.

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:

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

Disk attachment mode

When you attach a disk to a VM, you indicate how the VM can access the data on the disk by specifying the disk attachment mode. You can choose read-only or read-write mode.

The default mode is read-write.

Share a disk between VMs

You can share the same disk between VMs so that each VM can simultaneously access the disk by attaching the disk to each VM. You can attach a disk to multiple VMs if the disk's type and the VM's machine type support it.

To attach a disk to multiple VMs, follow the procedure in Attach a non-boot disk to your VM for each VM.

You must use the same disk attachment mode for all VMs that you attach the disk to. For example, you can't attach a disk to one VM in read-write mode and attach it at the same time to another VM in read-only mode.

For information about attaching a disk to multiple VMs, including the supported disk types, see Share a disk between VMs.

Attaching a Hyperdisk volume to multiple VMs

To attach a Hyperdisk volume to multiple VMs, make sure the disk's access mode is set to an appropriate value for your use case. For instructions on setting the access mode, see set the disk's access mode.

When you attach a Hyperdisk volume to a VM, you must choose a disk attachment mode that doesn't conflict with the disk's access mode. For example, you can't use read-only attachment mode with a disk that's in single-writer or multi-writer mode.

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.

• The following disk types don't support read-only mode:

  • Hyperdisk Balanced
  • Hyperdisk Throughput
  • Hyperdisk Balanced High Availability
  • Hyperdisk Extreme

• When you attach a disk to multiple VMs, you must use the same disk attachment mode for all the VMs.

• When you attach a disk to multiple VMs, additional restrictions apply. See the restrictions for sharing a disk between VMs in read-only mode and multi-writer mode.

• Disks attached to multiple VMs don't support auto-delete, that is, they can't be automatically deleted when the VM is deleted.

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.

When attaching a disk to a VM, keep the following points in mind:

• Use a custom device name: Google recommends that you 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.

• Attaching a disk to multiple VMs: To attach a disk to multiple VMs, repeat the procedure in this section for each VM. You must use the same disk attachment mode for all VMs that you attach the disk to.

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

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]
  }


}

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,
   "mode" : "DISK_ATTACHMENT_MODE"
}

After you attach a disk to a VM, connect to the VM and enable the VM's operating system (OS) to use the disk:

• If you attached a blank disk, format and mount the disk
• If you attached a non-empty disk, mount the disk

Learn how to format and mount your new disks on Linux or Windows VMs.

What's next

• Prevent data loss by regularly backing up your disks with snapshots
• Use regional persistent disks for synchronous replication between two zones.