The Cloud Quotas API lets you programmatically adjust quotas and automate quota adjustments at the project level. The Cloud Quotas API can be used for the following:
- 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 request a quota increase. All quota increases are subject to Google Cloud 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 configurations as code and store configurations in your own version controlled system for history and rollback.
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.
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_PREFERENCE_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:
A quota preference configuration with all location and service-specific dimensions specified takes precedence over any other configuration.
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:
The configuration may contain both location dimensions and service-specific dimensions. This is the highest order in precedence.
The configuration may only contain location dimensions. This configuration applies to all service-specific dimensions, except the ones explicitly configured with method 1.
The configuration may only contain service-specific dimensions. This configuration applies to all locations except those explicitly configured with method 1 or 2.
If the configuration contains any service-specific dimensions, it must contain all service-specific dimensions.
You can have configurations without any dimensions. Such configurations apply to all locations and all service-specific dimensions, except the ones explicitly configured.