Cloud Quotas API overview

The Cloud Quotas API lets you programmatically adjust quotas and automate quota adjustments in your Google Cloud projects, folders, or organizations. Adjustments can be made to increase or decrease quota values. All requests to increase quota values are subject to Google Cloud review and approval.

The Cloud Quotas API can be used to:

Automate quota adjustments
You can use the Cloud Quotas API to request quota increases when certain conditions are met. For example, to avoid quota exceeded errors, you can use the API to programmatically request a quota increase when Compute Engine resources reach 80% of the available quota.
Scale quota configurations across projects
The Cloud Quotas API can clone your quota configurations from project to project. If there is a known set of quotas that need to be increased for every new Google Cloud project, you can integrate the API into the creation logic of your project to automatically issue a QIR. All quota increases are subject to Google Cloud review and approval.
Serve customer quota requests
If you are a SaaS provider integrated with Google Cloud, you may receive quota increase requests through a customer-facing portal other than Google Cloud console. These requests must be forwarded to Google Cloud for processing. The Cloud Quotas API can automatically forward customer requests.
Enable client configuration version control
The Cloud Quotas API is declarative, you can treat quota configs as code and store configurations in your own version controlled system for history and rollback.

Limitations

The Cloud Quotas API has the following limitations:

  • The API doesn't support the Google Cloud CLI.

  • The API doesn't support quota increase requests for folder-level and organization-level quotas.

Service endpoint

The service endpoint is a base URL that specifies the network address of an API service. One service might have multiple endpoints. The Cloud Quotas API service has the following endpoint and all URIs are relative to it:

https://cloudquotas.googleapis.com

Required roles

To get the permissions that you need to access the cloudquotas_quotaPreferences and cloudquotas_quotaInfos resources, ask your administrator to grant you the Cloud Quotas Admin (cloudquotas.admin) IAM role on the project. For more information about granting roles, see Manage access.

This predefined role contains the permissions required to access the cloudquotas_quotaPreferences and cloudquotas_quotaInfos resources. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to access the cloudquotas_quotaPreferences and cloudquotas_quotaInfos resources:

  • cloudquotas.quotas.update
  • cloudquotas.quotas.get
  • monitoring.timeSeries.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list

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

API resource model

The Cloud Quotas API resource model consists of two resources: QuotaPreference and QuotaInfo.

Quota preference

The QuotaPreference resource represents your quota preference for a particular dimension combination. Use this resource to adjust the quotas in your projects, folders, or organizations.

Set a preferred value for a region

The following example shows a QuotaPreference resource in a CreateQuotaPreference method.

{
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": {
        "region": "us-central1"
    }
}

The preferredValue of 100 indicates that the requester wants the GPUS-PER-GPU-FAMILY-per-project-region quota to be set to that value. The dimensions field indicates the preference only applies to region us-central1.

Verify the granted value

The following example shows a QuotaPreference resource in a GetQuotaPreference method.

{
    "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1",
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100,
        "grantedValue": 100,
        "traceId": "123acd-345df23",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
    },
    "dimensions": {
        "region": "us-central1"
    },
    "createTime": "2023-01-15T01:30:15.01Z",
    "updateTime": "2023-01-16T02:35:16.01Z"
}

This output includes the following values:

  • PROJECT_NUMBER: An automatically generated unique identifier for your project.

The response shows a grantedValue of 100, meaning the preferredValue from the previous example has been approved and fulfilled. Preferences for different dimensions are different QuotaPreference resources. For example, QuotaPreference for CPU in regions us-central1 and us-east1 are two distinct resources.

Quota preference is required

QuotaPreference resources are used to indicate your preferred value for a particular quota. The current value for a particular quota is based on:

  • QuotaPreference requests made by you.

  • Approved quota increase requests by Google Cloud.

  • Changes to quotas initiated by Google Cloud.

The ability to delete a QuotaPreference is not supported. However, you can set a preferred quota value lower than the Google Cloud approved value to add further guardrails.

For more information on the QuotaPreference resource, see the Cloud Quotas API Reference.

For more information on the QuotaPreference queries, see Implement common use cases.

Quota info

QuotaInfo is a read-only resource that provides information about a particular quota for a given project, folder, or organizations. It displays information from the quotas defined by Google Cloud services and any fulfilled quota adjustments initiated by customers. The QuotaInfo resource contains information such as the metadata, container type, and dimension.

Set different quota values by region

The following QuotaInfo resource example shows that the CPU quota for the project is 200 for region us-central1 and 100 for all other regions.

{
    "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"
    ],
    "isPrecise": true,
    "quotaDisplayName": "CPUs per project per region",
    "metricDisplayName": "CPUs",
    "dimensionsInfo": [
        {
            "dimensions": {
                "region": "us-central1"
            },
            "details": {
                "quotaValue": 200,
                "resetValue": 200
            },
            "applicableLocations": [
                "us-central1",
            ]
        },
        {
            "details": {
                "quotaValue": 100,
                "resetValue": 100
            },
            "applicableLocations": [
                "us-central2",
                "us-west1",
                "us-east1"
            ]
        }
    ]
}

This output includes the following values:

  • PROJECT_NUMBER: An automatically generated unique identifier for your project.

Set a global quota

The following QuotaInfo resource example shows a rate quota with a per minute refresh interval. The dimensions are blank, which indicates that this is a global quota. All quotas without a region or zone dimension are global.

{
    "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/ReadRequestsPerMinutePerProject",
    "quotaId": "ReadRequestsPerMinutePerProject",
    "metric": "compute.googleapis.com/read_requests",
    "refreshInterval": "minute",
    "containerType": "PROJECT",
    "dimensions": [],
    "isPrecise": false,
    "quotaDisplayName": "Read Requests per Minute",
    "metricDisplayName": "Read Requests",
    "dimensionsInfo": [
        {
            "details": {
                "quotaValue": 100,
                "resetValue": 200
            },
            "applicableLocations": [
                "global"
            ]
        }
    ]
}

This output includes the following values:

  • PROJECT_NUMBER: An automatically generated unique identifier for your project.

For more details on the QuotaInfo resource, see the Cloud Quotas API Reference.

For more details on the QuotaPreference queries, see Implement common use cases.

Resource names

Resources are named entities and are identified by resource names. Resource names are used in all requests and responses, and each resource must have its own unique resource name. Each resource name is encoded by a set of fields.

Quota preference resource

The naming convention for a QuotaPreference resource uses the following pattern:

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFENCE_ID

You can set the quotaPreferenceId when creating a quota preference, otherwise an ID is generated. It is recommended that a quotaPreferenceId naming scheme encodes the service name, quota ID, location and other dimensions. The quotaPreferenceId must be unique for the project, folder, or organizations.

As an example quotaPreference One pattern to encode your quota preference ID is the following: 

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

The following example demonstrates this pattern: 

compute_us-central1_nvidia-200

With a resource name, you should use the GET method to retrieve a QuotaPreference. You can also call the UPDATE method with the allow_missing option enabled to create or update a QuotaPreference.

Quota info resource

The naming convention for a QuotaInfo resource uses the following pattern:

projects/PROJECT_NUMBER/locations/global/services/SERVICE_NAME/quotaInfos/QUOTA_ID

Dimension precedence

Some use cases for the Cloud Quotas API have complex dimension setups. Quotas can be configured at a more granular level than just regions and zones. You can accomplish this granularity when you use service-specific dimensions. For example, the gpu_family and network_id are service-specific dimensions in the Compute Engine service. Dimensions are defined by each individual service and each service might have a different set of service-specific dimensions.

When working with either location dimensions or service-specific dimensions, the following precedence is applied:

  1. A quota preference configuration with all location and service-specific dimensions specified takes precedence over any other configuration.

  2. Configurations that specify location dimensions only take precedence over configurations containing only service-specific dimensions.

Combining dimensions

In a quota preference configuration, you can combine dimensions in the following ways:

  1. The configuration may contain both location dimensions and service-specific dimensions. This is the highest order in precedence.

  2. The configuration may only contain location dimensions. This configuration applies to all service-specific dimensions, except the ones explicitly configured with method 1.

  3. The configuration may only contain service-specific dimensions. This configuration applies to all locations except those explicitly configured with method 1 or 2.

  4. If the configuration contains any service-specific dimensions, it must contain all service-specific dimensions.

  5. You can have configurations without any dimensions. Such configurations apply to all locations and all service-specific dimensions, except the ones explicitly configured.

What's next?