View and manage quotas using the gcloud alpha CLI

The following sections contain example gcloud alpha quotas info and gcloud alpha quotas preferences commands. These commands allow you to view and manage QuotaInfo and QuotaPreference resources.

You can use the Google Cloud CLI (gcloud CLI) to get current quotas values and specify quota preferences for some Google Cloud APIs and services.

Limitations

Cloud Quotas has the following limitations:

  • All quota increase adjustments are subject to Google Cloud approval.

  • You can request both quota increase and decrease adjustments for project-level quotas.

  • You can request quota decrease adjustments for project-, folder-, and organization-level quotas.

Before you begin

Before you begin, make sure that you install and initialize the gcloud CLI.

You may also need your QUOTA_ID value. If so, see the instructions for finding your quota ID.

Install and initialize the gcloud CLI

To use the gcloud CLI, make sure you have installed and initialized the latest version of the gcloud CLI, including the alpha commands component. If you're using Cloud Shell to interact with Google Cloud, the gcloud CLI is installed for you.

Find your quota ID

Several gcloud CLI commands on this page refer to your quota ID value.

To find the quota ID value, use the following gcloud CLI command to list your quota information for the specified service:

  1. Enter the following gcloud CLI command in a terminal window:

    gcloud alpha quotas info list --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \
--billing-project=BILLING_PROJECT_ID_OR_NUMBER

    Replace the following:

    • SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com

    • PROJECT_ID_OR_NUMBER: the project ID or project number

      To find your project ID using the Google Cloud console, navigate to the Resource Manager page:

      Go to Resource Manager

    • BILLING_PROJECT_ID_OR_NUMBER: the billing project ID or number

      If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

  2. The output from the gcloud alpha quotas info list command contains text similar to the following sample:

    ...
"quotaInfos": [
     ...
     {
        "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/CPUS-per-project-region",
        "quotaId": "CPUS-per-project-region",
        "metric": "compute.googleapis.com/cpus",
        "containerType": "PROJECT",
        "dimensions": [
            "region"
        ],
        "dimensionsInfo": [
            {
                "details": {
                    "value": 20
                },
                "applicableLocations": [
                    "us-central1",
                    "us-central2",
                    "us-west1",
                    "us-east1"
                ]
                ...
            }
        ]
    },
    ...
]
...

  3. Look for the value that corresponds to quotaId and use it when specifying QUOTA_ID in the following sections.

Example gcloud quota information commands

This section provides examples that show how to use gcloud alpha quotas info commands to view quota information for a particular service or for an organization.

QuotaInfo is a read-only resource that provides metadata and quota value information about a particular quota for a given project, folder or organization.

View quota information for a particular service

To view quota information for a particular service, run the following command:

gcloud alpha quotas info describe QUOTA_ID --service=SERVICE_NAME \
    --project=PROJECT_ID_OR_NUMBER --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

  • QUOTA_ID: the quota ID value. To find this value, see Find your quota ID.
  • SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
  • PROJECT_ID_OR_NUMBER: the project ID or project number

  • BILLING_PROJECT_ID_OR_NUMBER: the billing project ID or number

    If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

View quota information for an organization

To view the same service's quota details for an organization, run the following command:

gcloud alpha quotas info list --service=SERVICE_NAME --organization=ORGANIZATION_ID \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

  • SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
  • ORGANIZATION_ID: the ID of your organization

  • BILLING_PROJECT_ID_OR_NUMBER: the billing project ID or number

    If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

Example gcloud quota preferences commands

This section provides examples that show how to use gcloud alpha quotas preferences commands to check existing quota preferences and adjust the quota value.

The QuotaPreference resource represents your preference for a particular dimension combination. A dimension is an attribute that represents a region or a zone, or a service-specific dimension, such as gpu_family or network_id.

Check for existing preferences

To check for existing preferences, run the following command:

gcloud alpha quotas preferences list --project=PROJECT_ID_OR_NUMBER \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

Check for existing preferences with pending quota adjustments

To check for existing preferences with pending quota adjustments, add the --reconciling-only=true flag as shown in the following command:

gcloud alpha quotas preferences list --project=PROJECT_ID_OR_NUMBER --reconciling-only=true \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

Request a quota increase adjustment when a quota preference hasn't been set yet

To request a quota increase adjustment for a specific region when a preference hasn't yet been set, run the following command:

gcloud alpha quotas preferences create --preferred-value=PREFERRED_VALUE \
    --quota-id=QUOTA_ID --service=SERVICE_NAME  --project=PROJECT_ID_OR_NUMBER \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER --email=EMAIL --preference-id=PREFERENCE_ID

Replace the following:

  • PREFERRED_VALUE: the preferred quota value
  • QUOTA_ID: the quota ID value. To find this value, see Find your quota ID.
  • SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
  • PROJECT_ID_OR_NUMBER: the project ID or project number

  • BILLING_PROJECT_ID_OR_NUMBER: the billing project ID or number

    If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

  • EMAIL: an email address that can be used as a contact, in case Google Cloud needs more information to make a decision before additional quota can be granted

  • PREFERENCE_ID: an optional preference ID; if you don't specify a preference ID, the API generates a Universally Unique Identifier (UUID) for you

Request a quota increase adjustment when a quota preference has been set

To request a quota increase adjustment for a specific region and there is already a preference, run the following command:

gcloud alpha quotas preferences update PREFERENCE_ID --preferred-value=PREFERRED_VALUE \
    --quota-id=QUOTA_ID --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \
    --email=EMAIL --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

  • PREFERENCE_ID: the preference ID, which is required as the first argument when using the gcloud alpha quotas preferences update command
  • PREFERRED_VALUE: the preferred quota value
  • QUOTA_ID: the quota ID value. To find this value, see Find your quota ID.
  • SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
  • PROJECT_ID_OR_NUMBER: the project ID or project number
  • EMAIL: an email address that can be used as a contact, in case Google Cloud needs more information to make a decision before additional quota can be granted

  • BILLING_PROJECT_ID_OR_NUMBER: the billing project ID or number

    If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

Request a quota increase adjustment using a dimension

To request a quota increase adjustment using a dimension, run the following command:

gcloud alpha quotas preferences create --preferred-value=PREFERRED_VALUE \
    --quota-id=QUOTA_ID --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \
    --dimensions=KEY1=VALUE1,KEY2=VALUE2,... --billing-project=BILLING_PROJECT_ID_OR_NUMBER \
    --email=EMAIL --justification=JUSTIFICATION --preference-id=PREFERENCE_ID

Replace the following:

  • PREFERRED_VALUE: the preferred quota value
  • QUOTA_ID: the quota ID value. To find this value, see Find your quota ID.
  • SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
  • PROJECT_ID_OR_NUMBER: the project ID or project number
  • KEY1=VALUE1,KEY2=VALUE2,...: an optional list that specifies your dimension as a comma-separated list of key-value pairs. For example, your dimension might specify the following Compute Engine values:
    • KEY1=VALUE1: region=us-east4
    • KEY2=VALUE2: gpu_family=NVIDIA_H100

  • BILLING_PROJECT_ID_OR_NUMBER: the billing project ID or number

    If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

  • EMAIL: an email address that can be used as a contact, in case Google Cloud needs more information to make a decision before additional quota can be granted

  • JUSTIFICATION: an optional string that explains your request

  • PREFERENCE_ID: an optional preference ID; if you don't specify a preference ID, the API generates a Universally Unique Identifier (UUID) for you

The output would contain data specific to your configuration and look similar to the following example output:

{
    "createTime":"CREATE_TIME",
    "dimensions":{
        "gpu_family":"NVIDIA_H100",
        "region":"us-east4"
    },
    "etag":"ETAG_VALUE",
    "name":"projects/12345/locations/global/quotaPreferences/PREFERENCE_ID",
    "quotaConfig":{
        "grantedValue":"0",
        "preferredValue":"128",
        "traceId":"TRACE_ID"
    },
    "quotaId":"GPUS-PER-GPU-FAMILY-per-project-region",
    "reconciling":true,
    "service":"compute.googleapis.com",
    "updateTime":"UPDATE_TIME",
}

View an existing quota preference

To view the details of the quota preference that you just created, run the following command:

gcloud alpha quotas preferences describe PREFERENCE_ID \
    --project=PROJECT_ID_OR_NUMBER \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

  • PREFERENCE_ID: the preference ID, which is required as the first argument when using the gcloud alpha quotas preferences describe command
  • PROJECT_ID_OR_NUMBER: the project ID or project number

  • BILLING_PROJECT_ID_OR_NUMBER: the billing project ID or number

    If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

The output would contain data specific to your configuration and look similar to the following example output:

createTime: 'CREATE_TIME'
dimensions:
  gpu_family: NVIDIA_H100
  region: us-east4
etag: ETAG_VALUE
name: projects/12345/locations/global/quotaPreferences/PREFERENCE_ID
quotaConfig:
  grantedValue: '0'
  preferredValue: '128'
  traceId: TRACE_ID
quotaId: GPUS-PER-GPU-FAMILY-per-project-region
reconciling: true
service: compute.googleapis.com
updateTime: 'UPDATE_TIME'

Other services with quota-related gcloud CLI commands

In addition to gcloud alpha quotas, some services have their own command-line access to quota and resource usage information.

For example, Compute Engine lets you access quota information. For details, see the following Compute Engine sections:

What's next

For more information about gcloud alpha quotas commands and flags, see the gcloud alpha quotas section of the Google Cloud CLI reference.

For more information about quotas terminology, see Understand quota values and system limits.