The Cloud Quotas API lets you programmatically adjust project-level quotas and automate project-level quota adjustment requests. For example, you can use the Cloud Quotas API to:
Automate quota adjustments: You can use the Cloud Quotas API to request quota adjustments based on your own criteria. For example, to avoid quota exceeded errors, you can use the API to programmatically request a quota adjustment when Compute Engine resources reach 80% of the available quota.
Reuse 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 use the Cloud Quotas API to automate this in the creation logic of your project. Quota adjustment requests are subject to Google Cloud approval.
Serve customer quota requests: If you are a SaaS provider integrated with Google Cloud, you might receive quota increase requests through a customer-facing portal other than the 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:
Quota increase adjustments must be made at the project-level and are subject to Google Cloud approval.
You can request quota decrease adjustments for project-, folder-, and organization-level quotas.
The Cloud Quotas API only supports project-level operations. Folder-level and organization-level operations are not supported.
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 to projects, folders, and organizations.
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