Create a new Hyperdisk volume

You can use a Hyperdisk Extreme or Hyperdisk Throughput volume with your VM by completing the following tasks:

  • Create a blank, non-boot, and zonal Hyperdisk volume and attach it to your VM either as part of VM creation or as separate tasks.
  • Format and mount the volume to provide access to a data or file system.

The process is the same for Hyperdisk Balanced volumes, except that you can also create boot disks of type Hyperdisk Balanced.

For general information about Hyperdisk, see About Hyperdisk.

Before you begin

  • Review the Hyperdisk limitations before adding a Hyperdisk volume to your VM.
  • If you haven't already, then 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 by selecting one of the following options:

    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.

    Go

    To use the Go 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.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    For more information, see Set up authentication for a local development environment.

    Java

    To use the Java 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.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    For more information, see Set up authentication for a local development environment.

    Node.js

    To use the Node.js 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.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    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.

Required roles and permissions

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

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to add a Hyperdisk volume to your VM. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to add a Hyperdisk volume to your VM:

  • To create and attach a Hyperdisk volume:
    • compute.disks.create on the project
    • compute.instances.attachDisk on the VM
    • compute.disks.use on the volume 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.

Supported values for Hyperdisk volumes

The values you use when creating or modifying a Hyperdisk volume must fall within the range of maximum and minimum values described in Hyperdisk limits per disk.

If you're modifying the size of a Hyperdisk volume that's attached to a VM, then the new values can't exceed the Hyperdisk limits per VM.

The provisioned IOPS and throughput for a Hyperdisk volume must follow the rules outlined in About IOPS and throughput provisioning for Hyperdisk.

Add a Hyperdisk volume to your VM

You can create and attach a Hyperdisk volume by using the Google Cloud console, Google Cloud CLI, or REST.

The size, throughput, and IOPS that you specify when creating a Hyperdisk volume must be in the range of supported values.

When you create a Hyperdisk Balanced or Hyperdisk Balanced High Availability (Preview) volume, you can optionally allow multiple VMs to access the disk by creating the disk in multi-writer mode.

Console

  1. Go to the VM instances page.

    Go to VM instances

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

  3. On the VM instance details page, click Edit.

  4. Under the heading Additional disks, click Add new disk.

  5. Specify a name for the disk, and optionally add a description. Select Blank disk as the Disk source type.

  6. Under Disk settings, choose a disk type from the following list. The values that you specify must be in the range of supported values.

    1. Hyperdisk Balanced. You can also change the default disk Size, Provisioned IOPS, and Provisioned Throughput settings.
    2. Hyperdisk Extreme. You can also change the default disk Size and Provisioned IOPS settings.
    3. Hyperdisk ML. You can also change the default disk Size and Provisioned Throughput settings.
    4. Hyperdisk Throughput.You can also change the default disk Size and Provisioned Throughput settings.

  7. Optional: For Hyperdisk Balanced or Hyperdisk Balanced High Availability (Preview) volumes, you can enable attaching the disk to multiple VMs by creating the disk in multi-writer mode. Under Access mode, select Multiple VMs read write.

  8. Click Save.

  9. To apply your changes to the VM, click Save.

gcloud

  1. Use the gcloud compute disks create command to create the Hyperdisk volume.

    gcloud compute disks create DISK_NAME \
   --zone=ZONE \
   --size=DISK_SIZE \
   --type=DISK_TYPE \
   --provisioned-iops=IOPS_LIMIT
   --provisioned-throughput=THROUGHPUT_LIMIT
   --access-mode=DISK_ACCESS_MODE

    Replace the following:

    • DISK_NAME: the name of the new disk.
    • ZONE: the name of zone where the new disk is being created.
    • DISK_SIZE: Optional: The size of the new disk. The value must be a whole number followed by a size unit of GB for gibibyte, or TB for tebibyte. If no size unit is specified, 100  GB is used as the default value. The accepted values for the disk size are:
      • Hyperdisk Balanced: From 4 GiB to 64 TiB, inclusive, in 1 GiB increments.
      • Hyperdisk Extreme: From 64 GiB to 64 TiB, inclusive, in 1 GiB increments.
      • Hyperdisk ML: From 4 GiB to 64 TiB, inclusive, in 1 GiB increments.
      • Hyperdisk Throughput: From 2 TiB to 32 TiB, inclusive, in 1 GiB increments.
    • DISK_TYPE: the type of disk. Use one of the following values: hyperdisk-balanced, hyperdisk-extreme, hyperdisk-ml, or hyperdisk-throughput
    • IOPS_LIMIT: Optional: For Hyperdisk Balanced or Hyperdisk Extreme disks, this is the number of I/O operations per second (IOPS) that the disk can handle.
    • THROUGHPUT_LIMIT: Optional: For Hyperdisk Balanced, Hyperdisk ML, or Hyperdisk Throughput volumes, this is an integer that represents the throughput, measured in MiB per second, that the disk can handle.

    • DISK_ACCESS_MODE: Optional: How VMs can access the data on the disk. Supported values are:

      • READ_WRITE_SINGLE, for read-write access from one VM. This is the default.
      • READ_WRITE_MANY, for read-write access from multiple VMs.
      • READ_ONLY_MANY, for read-only access from multiple VMs.

      You can set the access mode for the following disk types:

      • Hyperdisk Balanced
      • Hyperdisk ML
      • Hyperdisk Balanced High Availability (Preview)

  2. Optional: Use the gcloud compute disks describe DISK_NAME command to see a description of your disk.

  3. After you create the disk, you can attach the disk to a VM.

REST

  1. Construct a POST request to create a zonal Hyperdisk by using the disks.insert method. Include the name, sizeGb, type, provisionedIops, and provisionedThroughput 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": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/diskTypes/DISK_TYPE",
   "provisionedIops": "IOPS_LIMIT",
   "provisionedThroughput": "THROUGHPUT_LIMIT",
   "accessMode": "DISK_ACCESS_MODE"
}

    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: Optional: The size of the new disk. The value must be a whole number followed by a size unit of GB for gibibytes or TB for tebibytes.
    • DISK_TYPE: the type of disk. To create a Hyperdisk volume, use one of the following values: hyperdisk-balanced, hyperdisk-extreme, hyperdisk-ml, or hyperdisk-throughput.
    • IOPS_LIMIT: Optional: For Hyperdisk Balanced and Hyperdisk Extreme, this is the number of I/O operations per second that the disk can handle.
    • THROUGHPUT_LIMIT: Optional: For Hyperdisk Balanced, Hyperdisk ML, or Hyperdisk Throughput volumes, this is an integer that represents the throughput, measured in MiB per second, that the disk can handle.

    • DISK_ACCESS_MODE: how VMs can access the data on the disk. Supported values are:

      • READ_WRITE_SINGLE, for read-write access from one VM. This is the default.
      • READ_WRITE_MANY, for read-write access from multiple VMs.
      • READ_ONLY_MANY, for read-only access from multiple VMs.

      You can set the access mode for the following disk types:

      • Hyperdisk Balanced
      • Hyperdisk ML
      • Hyperdisk Balanced High Availability (Preview)

  2. Optional: Use the compute.disks.get method to see a description of your disk.

  3. After you create the disk, you can attach the disk to any running or stopped VM.

Go 

// createHyperdisk creates a new Hyperdisk in the specified project and zone.
func createHyperdisk(w io.Writer, projectId, zone, diskName string) error {
	//   projectID := "your_project_id"
	//   zone := "europe-central2-b"
	//   diskName := "your_disk_name"

	ctx := context.Background()
	client, err := compute.NewDisksRESTClient(ctx)
	if err != nil {
		return fmt.Errorf("NewDisksRESTClient: %v", err)
	}
	defer client.Close()

	// use format "zones/{zone}/diskTypes/(hyperdisk-balanced|hyperdisk-throughput)".
	diskType := fmt.Sprintf("zones/%s/diskTypes/hyperdisk-balanced", zone)

	// Create the disk
	disk := &computepb.Disk{
		Name:   proto.String(diskName),
		Type:   proto.String(diskType),
		SizeGb: proto.Int64(10),
		Zone:   proto.String(zone),
	}

	req := &computepb.InsertDiskRequest{
		Project:      projectId,
		Zone:         zone,
		DiskResource: disk,
	}

	op, err := client.Insert(ctx, req)
	if err != nil {
		return fmt.Errorf("Insert disk request failed: %v", err)
	}

	// Wait for the insert disk operation to complete
	if err = op.Wait(ctx); err != nil {
		return fmt.Errorf("unable to wait for the operation: %w", err)
	}

	fmt.Fprintf(w, "Hyperdisk created: %v\n", diskName)
	return nil
}

Java 


import com.google.cloud.compute.v1.Disk;
import com.google.cloud.compute.v1.DisksClient;
import com.google.cloud.compute.v1.InsertDiskRequest;
import com.google.cloud.compute.v1.Operation;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateHyperdisk {
  public static void main(String[] args)
          throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Google Cloud project you want to use.
    String projectId = "YOUR_PROJECT_ID";
    // Name of the zone in which you want to create the disk.
    String zone = "europe-central2-b";
    // Name of the disk you want to create.
    String diskName = "YOUR_DISK_NAME";
    // The type of disk you want to create. This value uses the following format:
    // "zones/{zone}/diskTypes/(hyperdisk-balanced|hyperdisk-extreme|hyperdisk-throughput)".
    // For example: "zones/us-west3-b/diskTypes/hyperdisk-balanced"
    String diskType = String.format("zones/%s/diskTypes/hyperdisk-balanced", zone);
    // Size of the new disk in gigabytes.
    long diskSizeGb = 10;
    // Optional: For Hyperdisk Balanced or Hyperdisk Extreme disks,
    // this is the number of I/O operations per second (IOPS) that the disk can handle
    long provisionedIops = 3000;
    // Optional: For Hyperdisk Balanced or Hyperdisk Throughput volumes,
    // this is an integer that represents the throughput,
    // measured in MiB per second, that the disk can handle.
    long provisionedThroughput = 140;

    createHyperdisk(projectId, zone, diskName, diskType, diskSizeGb,
            provisionedIops, provisionedThroughput);
  }

  // Creates a hyperdisk in a project
  public static Disk createHyperdisk(String projectId, String zone, String diskName,
                                     String diskType, long diskSizeGb, long provisionedIops,
                                     long provisionedThroughput)
          throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (DisksClient client = DisksClient.create()) {
      // Create a disk.
      Disk disk = Disk.newBuilder()
              .setZone(zone)
              .setName(diskName)
              .setType(diskType)
              .setSizeGb(diskSizeGb)
              .setProvisionedIops(provisionedIops)
              .setProvisionedThroughput(provisionedThroughput)
              .build();

      InsertDiskRequest request = InsertDiskRequest.newBuilder()
              .setProject(projectId)
              .setZone(zone)
              .setDiskResource(disk)
              .build();

      // Wait for the insert disk operation to complete.
      Operation operation = client.insertAsync(request).get(1, TimeUnit.MINUTES);

      if (operation.hasError()) {
        System.out.println("Disk creation failed!");
        throw new Error(operation.getError().toString());
      }

      // Wait for server update
      TimeUnit.SECONDS.sleep(10);

      Disk hyperdisk = client.get(projectId, zone, diskName);

      System.out.printf("Hyperdisk '%s' has been created successfully", hyperdisk.getName());

      return hyperdisk;
    }
  }
}

Node.js 

// Import the Compute library
const computeLib = require('@google-cloud/compute');
const compute = computeLib.protos.google.cloud.compute.v1;

// Instantiate a diskClient
const disksClient = new computeLib.DisksClient();
// Instantiate a zoneOperationsClient
const zoneOperationsClient = new computeLib.ZoneOperationsClient();

/**
 * TODO(developer): Update/uncomment these variables before running the sample.
 */
// Project ID or project number of the Google Cloud project you want to use.
const projectId = await disksClient.getProjectId();

// The zone where your VM and new disk are located.
// zone = 'europe-central2-b';

// The name of the new disk
// diskName = 'disk-name';

// The type of disk. This value uses the following format:
// "zones/{zone}/diskTypes/(hyperdisk-balanced|hyperdisk-extreme|hyperdisk-ml|hyperdisk-throughput)".
// For example: "zones/us-west3-b/diskTypes/hyperdisk-balanced"
const diskType = `zones/${zone}/diskTypes/hyperdisk-balanced`;
// Size of the new disk in gigabytes.
const diskSizeGb = 10;
// Optional: For Hyperdisk Balanced or Hyperdisk Extreme disks,
// this is the number of I/O operations per second (IOPS) that the disk can handle.
const provisionedIops = 3000;
// Optional: For Hyperdisk Balanced or Hyperdisk Throughput volumes,
// this is an integer that represents the throughput,
// measured in MiB per second, that the disk can handle.
const provisionedThroughput = 140;

async function callCreateComputeHyperdisk() {
  // Create a disk
  const disk = new compute.Disk({
    sizeGb: diskSizeGb,
    name: diskName,
    zone,
    type: diskType,
    provisionedIops,
    provisionedThroughput,
  });

  const [response] = await disksClient.insert({
    project: projectId,
    zone,
    diskResource: disk,
  });

  let operation = response.latestResponse;

  // Wait for the create disk operation to complete.
  while (operation.status !== 'DONE') {
    [operation] = await zoneOperationsClient.wait({
      operation: operation.name,
      project: projectId,
      zone: operation.zone.split('/').pop(),
    });
  }

  console.log(`Disk: ${diskName} created.`);
}

await callCreateComputeHyperdisk();

After you create the disk, you can attach the disk to any running or stopped VM.

Format and mount the disk

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

What's next