Manage Hyperdisk Storage Pool

This document explains how to list, describe, modify, and delete storage pools.

Before you begin

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
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.
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.
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 manage a storage pool, 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 manage a storage pool. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to manage a storage pool:

To list the storage pools for a project and zone: compute.storagePools.list
To list the disks within a storage pool: compute.storagePools.get
To view the properties of a storage pool: compute.storagePools.get
To update the provisioned capacity or performance of a storage pool:
- compute.storagePools.get
- compute.storagePools.update
To delete a storage pool: compute.storagePools.delete

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

Limitations

Take note of the following limitations when managing Hyperdisk Storage Pools:

You can change the provisioned capacity or performance of a storage pool at most two times in a 24 hour period.
You can't change the provisioning model for a pool; you can't change a Standard capacity storage pool to an Advanced capacity storage pool or an Advanced performance storage pool to a Standard performance storage pool.
Moving disks in or out of a storage pool is not permitted. To move a disk in or out of a storage pool, you have to recreate the disk from a snapshot. For more information, see Change the disk type.
You can't clone, create instant snapshots of, or configure Persistent Disk Asynchronous Replication for disks in a storage pool.
You can delete at most 5 storage pools per hour.
The storage pool management command either succeeds or fails immediately, but it can take up to 5 minutes to complete the action, and up to 30 minutes for the changes to appear.

For the full list of Hyperdisk Storage Pool limitations, see Limitations of storage pools.

Value ranges when modifying storage pools

When creating a storage pool, the new values for size, IOPS, and throughput must be within the limits for the type of storage pool you are modifying. Also, you can only specify new values using supported incremental values.

For detailed performance provisioning limits, refer to Limits for storage pools.

List the storage pools for a project

To see the storage pools that were created in a project, use the Google Cloud console, Google Cloud CLI, or REST.

Console

Go to the Storage pools page in the Google Cloud console.
Go to the Storage pools page

The page displays the storage pools created within the selected project.
Optional: Use the Filter bar to display only the storage pools that match the filter parameters, such as Location, Type, Name, and Pool capacity remaining.

gcloud

To list all the storage pools created within the current project, use the gcloud compute storage-pools list command.

gcloud compute storage-pools list

To limit the results to a specific region or zone you can use the --filter flag, for example:

--filter="zone ~ us
--filter="zone=us-east4-c"

REST

To show the storage pools created within a project and zone, construct a GET request using the storagePools.list method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/storagePools

Replace the following:

PROJECT_ID: the ID of the project that contains the storage pool
ZONE: the zone where the storage pool is located, for example, us-central1-a.

List the disks in a storage pool

To get a list of the disks created in a storage pool, use the Google Cloud console, Google Cloud CLI, or REST.

Console

Go to the Storage pools page in the Google Cloud console.
Go to the Storage pools page

The page displays the storage pools created within the selected project.
In the Name field, click the name of the storage pool you want to view.

The Manage storage pool page opens.
In the Storage pool disks section, you can see the disks that were created in the storage pool.

gcloud

To list the disks that were created in a storage pool, use the gcloud compute storage-pools list-disks command.

gcloud compute storage-pools list-disks STORAGE_POOL_NAME  \
    [--zone=ZONE]

Replace the following:

STORAGE_POOL_NAME: the name of the storage pool.
ZONE: Optional. The zone in which the storage pool is located, for example, us-central1-a.

REST

To list the disks that are using a storage pool, construct a GET request using the storagePools.listDisks method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/storagePools/STORAGE_POOL_NAME/listDisks

Replace the following:

PROJECT_ID: the ID of the project that contains the storage pool
ZONE: the zone where the storage pool is located, for example, us-central1-a.
STORAGE_POOL_NAME: the name of the storage pool.

Describe a storage pool

To view the details of a storage pool, you can use the Google Cloud console, Google Cloud CLI, or REST.

Console

Go to the Storage pools page in the Google Cloud console.
Go to the Storage pools page
For each storage pool listed on the page, you can view the following information:
- Status
- Name
- Location
- Pool type
- Pool capacity
- Pool capacity remaining
- Pool IOPS
- Pool IOPS remaining
- Number of disks created in the pool
In the Name field, click the name of the storage pool that you want to view.

The Manage storage pool page opens.
In the tiles at the top of the page you can view the provisioned and used capacity, and the provisioned and used throughput and IOPS for the storage pool.
In the Storage pool settings section, you can view additional properties of the storage pool, such as the creation time, capacity provisioning type, performance provisioning type, the total number of disks in the storage pool, and the utilization percentages for capacity, throughput, and IOPS.
In the Storage pool disks section, you can view information about the disks created in the storage pool.

gcloud

Use the gcloud compute storage-pools describe command to view the details for a storage pool.

gcloud compute storage-pools describe STORAGE_POOL_NAME  \
    [--zone=ZONE]

Replace the following:

STORAGE_POOL_NAME: the unique storage pool name.
ZONE: Optional. The zone in which the storage pool is located, for example, us-central1-a.

REST

To retrieve details about a storage pool, construct a GET request using the storagePools.get method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/storagePools/STORAGE_POOL_NAME

Replace the following:

PROJECT_ID: the ID of the project that contains the storage pool
ZONE: the zone where the storage pool is located, for example, us-central1-a
STORAGE_POOL_NAME: the name of the storage pool

Update the provisioned capacity, IOPS or throughput of a storage pool

You can increase or decrease the provisioned capacity, IOPS, or throughput of a storage pool. To increase the capacity, IOPS, or throughput of a storage pool, you must have quota available for the project and region.

Console

Go to the Storage pools page in the Google Cloud console.
Go to the Storage pools page
In the Name field, click the name of the storage pool that you want to modify.

The Manage storage pool page opens.
Click Edit.

The Edit storage pool page opens.
Optional: In the Storage pool capacity field, enter the new value for pool provisioned capacity. The new value must at least 1 TiB and at most 100 TiB more or less than the current value. The minimum size can't be less than 10 TiB and the maximum size can't be more than 1,024 TiB.
Optional: In the Provisioned throughput field, enter the new value for provisioned throughput.
Optional: For storage pools of type Hyperdisk Balanced, in the Provisioned IOPS field, enter the new value for the provisioned IOPS.
Click Save to update the storage pool.

gcloud

Use the gcloud compute storage-pools update command to modify a storage pool.

gcloud compute storage-pools update STORAGE_POOL_NAME  \
    --zone=ZONE   \
    --provisioned-capacity=POOL_SIZETiB   \
    --provisioned-iops=IOPS   \
    --provisioned-throughput=THROUGHPUT   \
    --description=DESCRIPTION

Replace the following:

STORAGE_POOL_NAME: the name of the storage pool.
ZONE: Optional: the zone that the storage pool is located in, for example, us-central1-a.
POOL_SIZE: Optional: the storage pool provisioned capacity, in TiB.
IOPS: Optional: the storage pool provisioned IOPS. You can use this flag only with Hyperdisk Balanced Storage Pools.
THROUGHPUT: Optional: the storage pool provisioned throughput, in MBps.
DESCRIPTION: Optional: a descriptive string for the storage pool.

REST

To update a storage pool, construct a PATCH request by using the storagePools.update method.

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/storagePools/STORAGE_POOL_NAME

{
    "description": "DESCRIPTION",
    "poolProvisionedCapacityGb": "SIZE",
    "poolProvisionedIops": "IOPS",
    "poolProvisionedThroughput": "THROUGHPUT"
}

Replace the following:

PROJECT_ID: the project ID
ZONE: the zone where the storage pool is located, for example, us-central1-a.
STORAGE_POOL_NAME: the name of the storage pool.
DESCRIPTION: Optional: a text field to describe the storage pool.
SIZE: Optional: the new storage pool provisioned capacity, in GiB.
IOPS: Optional: the new value for storage pool provisioned IOPS. You can only specify this property when the storage pool contains disks of type hyperdisk-balanced.
THROUGHPUT: Optional: the new value for storage pool provisioned throughput, specified in MBps.

Delete a storage pool

To delete or remove a storage pool, you must first delete all the disks within the storage pool. Then you can use the Google Cloud console, Google Cloud CLI, or REST to delete the storage pool.

Deleting a storage pool is irreversible. However, deleting a storage pool does not delete any snapshots made from disks that were created in the storage pool. You must delete the snapshots separately.

Console

Go to the Storage Pool page in the Google Cloud console.
Go to the Storage Pool page
In the Name field, click the name of the storage pool that you want to remove.

The Manage storage pool page opens.
In the Storage pool disks section, verify there are no disks listed for the storage pool.
Click Delete pool.

gcloud

Use the gcloud compute storage-pools delete command to delete a storage pool.

gcloud compute storage-pools delete STORAGE_POOL_NAME  \
    --zone=ZONE   \

Replace the following:

STORAGE_POOL_NAME: the unique storage pool name.
ZONE: Optional: the zone in which the storage pool is located, for example, us-central1-a.

REST

To remove a storage pool, construct a DELETE request for the storagePools.delete method.

DELETE https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/storagePools/STORAGE_POOL_NAME

Replace the following:

PROJECT_ID: the project ID
ZONE: the zone where the storage pool is located, for example, us-central1-a.
STORAGE_POOL_NAME: the unique storage pool name.

What's next?

Learn more about storage pools.