以下部分包含 gcloud beta quotas info
和 gcloud beta quotas preferences
命令示例。借助这些命令,您可以查看和管理 QuotaInfo
和 QuotaPreference
资源。
您可以使用 Google Cloud CLI (gcloud CLI) 获取当前配额值,并为某些 Google Cloud API 和服务指定配额偏好设置。
限制
Cloud 配额具有以下限制:
在大多数情况下,配额“增加”调整必须在项目级进行。只有少数产品支持组织级配额增加调整。如需了解某个 Google Cloud 产品是否支持组织级配额增加调整,请参阅该产品的文档。
您可以针对项目、组织和文件夹级配额请求配额减少调整。
Cloud Quotas API 仅支持项目级操作。文件夹级和组织级操作不受支持。
准备工作
在使用 gcloud CLI 之前,请务必安装并初始化 gcloud CLI。
您可能还需要您的 QUOTA_ID
值。如果是,请参阅查找配额 ID 的说明。
安装并初始化 gcloud CLI
如需将 gcloud CLI 用于 Cloud Quota,请务必安装并初始化组件:
安装 gcloud CLI。
如果您使用的是 Cloud Shell,则可以跳过此步骤,因为 gcloud CLI 已预安装。
初始化 gcloud CLI。
通过运行以下命令安装 Beta 版组件:
gcloud components install beta
查找配额 ID
本页面上的多个 gcloud CLI 命令会引用您的配额 ID 值。您可以使用 Google Cloud 控制台、gcloud CLI、客户端库或 REST API 查找配额 ID。本部分介绍如何使用 Google Cloud 控制台或 gcloud CLI 查找配额 ID。
控制台
进入配额和系统限制页面:
点击
过滤条件,为您的服务过滤。如果您没有看到限制名称列,请点击图标
列显示选项...。选择限制名称,然后点击确定。限制名称列显示配额 ID。
gcloud
如需使用 gcloud CLI 查找配额 ID 值,请运行以下命令以列出指定服务的配额信息:
在终端窗口中输入以下 gcloud CLI 命令:
gcloud beta quotas info list --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \ --billing-project=BILLING_PROJECT_ID_OR_NUMBER
替换以下内容:
SERVICE_NAME
:包含您要查看的配额的服务名称,例如 Compute Engine 的服务名称为compute.googleapis.com
PROJECT_ID_OR_NUMBER
:项目 ID 或项目编号如需使用 Google Cloud 控制台查找项目 ID,请前往 Resource Manager 页面:
BILLING_PROJECT_ID_OR_NUMBER
:用于配额和结算的项目 ID 或项目编号。运行 gcloud 命令会影响配额,就像您直接通过 REST 或 RPC API 发出等效请求一样。指定您要使用的配额项目。这可能与包含您要查找配额 ID 的服务的项目不同。
如果您在设置 gcloud CLI 时已设置结算项目,则此标志是可选的。否则,省略该参数可能会导致权限遭拒错误。如需了解详情,请参阅设置配额项目。
gcloud beta quotas info list
命令的输出包含类似于以下示例的文本:... "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" ] ... } ] }, ... ] ...
查找与
quotaId
对应的值,并在后续部分指定QUOTA_ID
时使用该值。
gcloud 配额信息命令示例
本部分提供了一些示例,展示了如何使用 gcloud beta quotas info
命令查看特定服务或组织的配额信息。
QuotaInfo
是一种只读资源,用于提供与给定项目、文件夹或组织的特定配额相关的元数据和配额值信息。
查看特定服务的配额信息
如需查看特定服务的配额信息,请运行以下命令:
gcloud beta quotas info describe QUOTA_ID --service=SERVICE_NAME \
--project=PROJECT_ID_OR_NUMBER --billing-project=BILLING_PROJECT_ID_OR_NUMBER
替换以下内容:
QUOTA_ID
:配额 ID 值。如需查找此值,请参阅查找配额 ID。SERVICE_NAME
:包含您要查看的配额的服务名称,例如 Compute Engine 的服务名称为compute.googleapis.com
PROJECT_ID_OR_NUMBER
:项目 ID 或项目编号BILLING_PROJECT_ID_OR_NUMBER
:用于配额和结算的项目 ID 或项目编号。运行 gcloud 命令会影响配额,就像您直接通过 REST 或 RPC API 发出等效请求一样。指定您要使用的配额项目。这可能与包含您要查看配额信息的服务的项目不同。
如果您在设置 gcloud CLI 时已设置结算项目,则此标志是可选的。否则,省略该参数可能会导致权限遭拒错误。如需了解详情,请参阅设置配额项目。
查看组织的配额信息
如需查看组织的同一服务的配额详细信息,请运行以下命令:
gcloud beta quotas info list --service=SERVICE_NAME --organization=ORGANIZATION_ID \
--billing-project=BILLING_PROJECT_ID_OR_NUMBER
替换以下内容:
SERVICE_NAME
:包含您要查看的配额的服务名称,例如 Compute Engine 的服务名称为compute.googleapis.com
ORGANIZATION_ID
:您的组织的 IDBILLING_PROJECT_ID_OR_NUMBER
:用于配额和结算的项目 ID 或项目编号。运行 gcloud 命令会影响配额,就像您直接通过 REST 或 RPC API 发出等效请求一样。指定您要使用的配额项目。这可能与包含您要查看配额信息的服务的项目不同。
如果您在设置 gcloud CLI 时已设置结算项目,则此标志是可选的。否则,省略该参数可能会导致权限遭拒错误。如需了解详情,请参阅设置配额项目。
gcloud 配额偏好设置命令示例
本部分提供了一些示例,展示了如何使用 gcloud beta quotas preferences
命令来检查现有的配额偏好设置并调整配额值。
QuotaPreference
资源表示特定维度组合的偏好设置。维度是表示区域或可用区的属性,或特定于服务的维度(如 gpu_family
或 network_id
)。
检查现有偏好设置
如需检查现有偏好设置,请运行以下命令:
gcloud beta quotas preferences list --project=PROJECT_ID_OR_NUMBER \
--billing-project=BILLING_PROJECT_ID_OR_NUMBER
替换以下内容:
PROJECT_ID_OR_NUMBER
:项目 ID 或项目编号BILLING_PROJECT_ID_OR_NUMBER
:用于配额和结算的项目 ID 或项目编号。运行 gcloud 命令会影响配额,就像您直接通过 REST 或 RPC API 发出等效请求一样。指定您要使用的配额项目。这可能与您查看配额偏好设置的项目不同。
如果您在设置 gcloud CLI 时已设置结算项目,则此标志是可选的。否则,省略该参数可能会导致权限遭拒错误。如需了解详情,请参阅设置配额项目。
检查是否有待处理的配额调整的现有偏好设置
如需检查是否有待处理的配额调整的现有偏好设置,请添加 --reconciling-only=true
标志,如以下命令所示:
gcloud beta quotas preferences list --project=PROJECT_ID_OR_NUMBER --reconciling-only=true \
--billing-project=BILLING_PROJECT_ID_OR_NUMBER
替换以下内容:
PROJECT_ID_OR_NUMBER
:项目 ID 或项目编号BILLING_PROJECT_ID_OR_NUMBER
:用于配额和结算的项目 ID 或项目编号。运行 gcloud 命令会影响配额,就像您直接通过 REST 或 RPC API 发出等效请求一样。指定您要使用的配额项目。这可能与您查看配额偏好设置的项目不同。
如果您在设置 gcloud CLI 时已设置结算项目,则此标志是可选的。否则,省略该参数可能会导致权限遭拒错误。如需了解详情,请参阅设置配额项目。
在尚未设置配额偏好设置时申请配额增加调整
如需在尚未设置偏好设置的情况下为特定区域申请配额增加调整,请运行以下命令:
gcloud beta 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 \
--justification=JUSTIFICATION --preference-id=PREFERENCE_ID
替换以下内容:
PREFERRED_VALUE
:首选配额值QUOTA_ID
:配额 ID 值。如需查找此值,请参阅查找配额 ID。SERVICE_NAME
:包含您要查看的配额的服务名称,例如 Compute Engine 的服务名称为compute.googleapis.com
PROJECT_ID_OR_NUMBER
:项目 ID 或项目编号BILLING_PROJECT_ID_OR_NUMBER
:用于配额和结算的项目 ID 或项目编号。运行 gcloud 命令会影响配额,就像您直接通过 REST 或 RPC API 发出等效请求一样。指定您要使用的配额项目。该项目可以不同于您申请配额调整的项目。
如果您在设置 gcloud CLI 时已设置结算项目,则此标志是可选的。否则,省略该参数可能会导致权限遭拒错误。如需了解详情,请参阅设置配额项目。
EMAIL
:可用作联系人的电子邮件地址(如果 Google Cloud 需要更多信息才能授予额外的配额)。JUSTIFICATION
:可选字符串,用于说明您的请求PREFERENCE_ID
:可选的偏好设置 ID;如果您未指定偏好设置 ID,该 API 会为您生成通用唯一标识符 (UUID)
在设置配额偏好设置后申请配额增加调整
如需为特定区域申请配额增加调整,并且已存在偏好设置,请运行以下命令:
gcloud beta quotas preferences update PREFERENCE_ID --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 \
--justification=JUSTIFICATION
替换以下内容:
PREFERENCE_ID
:偏好设置 ID,在使用gcloud beta quotas preferences update
命令时,此 ID 是必需的第一个参数PREFERRED_VALUE
:首选配额值QUOTA_ID
:配额 ID 值。如需查找此值,请参阅查找配额 ID。SERVICE_NAME
:包含您要查看的配额的服务名称,例如 Compute Engine 的服务名称为compute.googleapis.com
PROJECT_ID_OR_NUMBER
:项目 ID 或项目编号BILLING_PROJECT_ID_OR_NUMBER
:用于配额和结算的项目 ID 或项目编号。运行 gcloud 命令会影响配额,就像您直接通过 REST 或 RPC API 发出等效请求一样。指定您要使用的配额项目。该项目可以不同于您申请配额调整的项目。
如果您在设置 gcloud CLI 时已设置结算项目,则此标志是可选的。否则,省略该参数可能会导致权限遭拒错误。如需了解详情,请参阅设置配额项目。
EMAIL
:可用作联系人的电子邮件地址(如果 Google Cloud 需要更多信息才能授予额外的配额)。JUSTIFICATION
:可选字符串,用于说明您的请求
使用维度申请配额增加调整
如需使用维度申请配额增加调整,请运行以下命令:
gcloud beta 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
替换以下内容:
PREFERRED_VALUE
:首选配额值QUOTA_ID
:配额 ID 值。如需查找此值,请参阅查找配额 ID。SERVICE_NAME
:包含您要查看的配额的服务名称,例如 Compute Engine 的服务名称为compute.googleapis.com
PROJECT_ID_OR_NUMBER
:项目 ID 或项目编号KEY1=VALUE1,KEY2=VALUE2,...
:可选列表,用于将维度指定为以英文逗号分隔的键值对列表。例如,您的维度可以指定以下 Compute Engine 值:KEY1=VALUE1
:region=us-east4
KEY2=VALUE2
:gpu_family=NVIDIA_H100
BILLING_PROJECT_ID_OR_NUMBER
:用于配额和结算的项目 ID 或项目编号。运行 gcloud 命令会影响配额,就像您直接通过 REST 或 RPC API 发出等效请求一样。指定您要使用的配额项目。该项目可以不同于您申请配额调整的项目。
如果您在设置 gcloud CLI 时已设置结算项目,则此标志是可选的。否则,省略该参数可能会导致权限遭拒错误。如需了解详情,请参阅设置配额项目。
EMAIL
:可用作联系人的电子邮件地址(如果 Google Cloud 需要更多信息才能授予额外的配额)。JUSTIFICATION
:可选字符串,用于说明您的请求PREFERENCE_ID
:可选的偏好设置 ID;如果您未指定偏好设置 ID,该 API 会为您生成通用唯一标识符 (UUID)
输出将包含特定于您的配置的数据,并类似于以下示例输出:
{
"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",
}
查看现有配额偏好设置
如需查看您刚刚创建的配额偏好设置的详细信息,请运行以下命令:
gcloud beta quotas preferences describe PREFERENCE_ID \
--project=PROJECT_ID_OR_NUMBER \
--billing-project=BILLING_PROJECT_ID_OR_NUMBER
替换以下内容:
PREFERENCE_ID
:偏好设置 ID,在使用gcloud beta quotas preferences describe
命令时,此 ID 是必需的第一个参数PROJECT_ID_OR_NUMBER
:项目 ID 或项目编号BILLING_PROJECT_ID_OR_NUMBER
:用于配额和结算的项目 ID 或项目编号。运行 gcloud 命令会影响配额,就像您直接通过 REST 或 RPC API 发出等效请求一样。指定您要使用的配额项目。这可能与您查看配额偏好设置的项目不同。
如果您在设置 gcloud CLI 时已设置结算项目,则此标志是可选的。否则,省略该参数可能会导致权限遭拒错误。如需了解详情,请参阅设置配额项目。
输出将包含特定于您的配置的数据,并类似于以下示例输出:
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'
通过客户端项目启用配额调整工具
客户端项目是指应用或用户用于访问和与 Google Cloud 资源进行交互的项目,而资源项目是存储和管理这些资源的底层项目。
如需使用 gcloud CLI 通过客户端项目启用配额调整器,请按以下步骤操作:
创建客户端项目:
gcloud projects create CLIENT_PROJECT_ID gcloud config set project CLIENT_PROJECT_ID
将
CLIENT_PROJECT_ID
替换为要创建的项目 ID。项目 ID 不可变,只能在项目创建期间设置。名称必须以小写字母开头,可以包含小写 ASCII 字母、数字或连字符。项目 ID 的长度必须介于 6 到 30 个字符之间。在客户端项目中启用 Cloud Quotas API:
gcloud services enable cloudquotas.googleapis.com
在白名单项目中创建一个服务账号。
gcloud iam service-accounts create SA_NAME \ --display-name SA_DISPLAY_NAME \ --project=CLIENT_PROJECT_ID
替换以下内容:
SA_NAME
:新服务账号的内部名称。用于生成 IAM_ACCOUNT(用作服务账号标识符的 IAM 内部电子邮件地址),该地址必须传递给后续命令。SA_DISPLAY_NAME
:服务账号的显示名称。CLIENT_PROJECT_ID
:客户端项目的 ID。
创建服务账号密钥:
gcloud iam service-accounts keys create KEY_FILE \ --iam-account=SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com
替换以下内容:
KEY_FILE
:JSON 服务账号密钥文件的路径。SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com
:服务账号电子邮件地址。
向服务账号授予 IAM 权限:
gcloud projects add-iam-policy-binding CLIENT_PROJECT_ID \ --member="serviceAccount:SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/serviceusage.serviceUsageConsumer" gcloud projects add-iam-policy-binding RESOURCE_PROJECT_ID \ --member="serviceAccount:SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/cloudquotas.admin"
替换以下内容:
CLIENT_PROJECT_ID
:客户端项目的 ID。RESOURCE_PROJECT_ID
:资源项目的 ID。SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com
:服务账号电子邮件地址。
使用您之前创建的服务账号密钥激活服务账号:
gcloud auth activate-service-account --key-file=KEY_FILE
通过指定项目和启用设置,为资源项目启用配额调整工具:
gcloud beta quotas adjuster settings update --project=RESOURCE_PROJECT_ID \ --enablement=enabled
使用 gcloud CLI 时,必须启用此设置,并且必须将其设置为
enabled
或disabled
。(可选)如需查看当前的配额调整器设置,请运行以下命令:
gcloud beta quotas adjuster settings describe --project=RESOURCE_PROJECT_ID
输出类似于以下示例:
enablement: ENABLED etag: 8izmJp6EI__mOfLyhkQU9 name: projects/RESOURCE_PROJECT_ID/locations/global/quotaAdjusterSettings updateTime: '2025-01-10T17:22:37.883221181Z'
如需为多个客户项目启用配额调整工具,请按照前面的第 5 步到第 8 步操作。执行此操作时,请确保满足以下条件:
- 在客户端项目中启用了 Cloud Quotas API。
- 确保该服务账号在您要启用配额调节器的所有资源项目中都具有
cloudquotas.admin
IAM 角色。
其他具有配额相关 gcloud CLI 命令的服务
除了 gcloud beta quotas
之外,某些服务还可以通过自己的命令行访问配额和资源用量信息。
例如,Compute Engine 允许您访问配额信息。如需了解详情,请参阅以下 Compute Engine 部分:
- 分配配额
- gcloud CLI 计算概览
- Google Cloud SDK 参考文档中的 gcloud CLI 计算部分。
后续步骤
如需排查
gcloud beta quotas
命令的问题,请参阅排查 gcloud CLI 错误。如需详细了解
gcloud beta quotas
命令和标志,请参阅 Google Cloud CLI 参考文档中的 gcloud beta quotas 部分。如需详细了解配额术语,请参阅了解配额值和系统限制。