使用 gcloud Beta 版 CLI 管理配额

以下部分包含 gcloud beta quotas info 和 gcloud beta quotas preferences 命令示例。借助这些命令，您可以查看和管理 QuotaInfo 和 QuotaPreference 资源。

您可以使用 Google Cloud CLI (gcloud CLI) 获取当前配额值，并为某些 Google Cloud API 和服务指定配额偏好设置。

限制

Cloud 配额具有以下限制：

在大多数情况下，配额“增加”调整必须在项目级进行。只有少数产品支持组织级配额增加调整。如需了解某个 Google Cloud 产品是否支持组织级配额增加调整，请参阅该产品的文档。
您可以针对项目、组织和文件夹级配额请求配额减少调整。

准备工作

在使用 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。

控制台

在 Google Cloud 控制台中，依次前往 IAM 和管理 > 配额和系统限制页面：
进入“配额和系统限制”
点击 过滤条件，为您的服务过滤。
如果您没有看到限制名称列，请点击图标 列显示选项...。选择限制名称，然后点击确定。
限制名称列显示配额 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 或项目编号（该项目的 Cloud Quotas 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 或项目编号（该项目的 Cloud Quotas 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：您的组织的 ID。
BILLING_PROJECT_ID_OR_NUMBER：您要用于执行此命令的项目的 ID 或项目编号（该项目的 Cloud Quotas 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 或项目编号（该项目的 Cloud Quotas 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 或项目编号（该项目的 Cloud Quotas API 配额将用于执行此命令）。这可能与包含您要查看配额偏好设置的服务的项目不同。

如果您在设置 gcloud CLI 时已设置结算项目，则此标志是可选的。否则，省略该参数可能会导致权限遭拒错误。如需了解详情，请参阅设置配额项目。

在尚未设置配额偏好设置时申请配额增加调整

如需使用 gcloud CLI 请求调整配额，请运行以下命令：

gcloud beta quotas preferences create --project=PROJECT_ID_OR_NUMBER \
    --service=SERVICE_NAME \
    --quota-id=QUOTA_ID \
    --dimensions=DIMENSIONS \
    --preferred-value=PREFERRED_VALUE \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER \
    --email=EMAIL \
    --justification=JUSTIFICATION \
    --preference-id=PREFERENCE_ID

替换以下内容：

PROJECT_ID_OR_NUMBER：项目 ID 或项目编号。
SERVICE_NAME：包含您要调整的配额的服务名称，例如 Compute Engine 的服务名称为 compute.googleapis.com。
QUOTA_ID：配额 ID 值。如需查找此值，请参阅查找配额 ID。
DIMENSIONS：要调整的维度，以英文逗号分隔的键值对列表形式指定，例如 region=us-east4,gpu_family=NVIDIA_H100。如需详细了解配额维度，请参阅配置 Cloud 配额维度。
PREFERRED_VALUE：首选配额值。
BILLING_PROJECT_ID_OR_NUMBER：您要用于执行此命令的项目的 ID 或项目编号（该项目的 Cloud Quotas API 配额将用于执行此命令）。该项目可以不同于您申请配额调整的服务所属的项目。

如果您在设置 gcloud CLI 时已设置结算项目，则此标志是可选的。否则，省略该参数可能会导致权限遭拒错误。如需了解详情，请参阅设置配额项目。
EMAIL：可用作联系人的邮箱（如果 Google Cloud 需要更多信息才能授予额外的配额）。
JUSTIFICATION：可选字符串，用于说明您的请求。
PREFERENCE_ID：可选的偏好设置 ID；如果您未指定偏好设置 ID，该 API 会为您生成通用唯一标识符 (UUID)。

输出类似于以下内容：

{
    "createTime":"CREATE_TIME",
    "dimensions":{
        "DIMENSION_KEY_1":"DIMENSION_VALUE_1",
        "DIMENSION_KEY_2":"DIMENSION_VALUE_2"
    },
    "etag":"ETAG_VALUE",
    "name":"projects/PROJECT_ID_OR_NUMBER/locations/global/quotaPreferences/PREFERENCE_ID",
    "quotaConfig":{
        "grantedValue":"GRANTED_VALUE",
        "preferredValue":"PREFERRED_VALUE",
        "traceId":"TRACE_ID"
    },
    "quotaId":"QUOTA_ID",
    "reconciling":true,
    "service":"SERVICE_NAME",
    "updateTime":"UPDATE_TIME",
}

在设置配额偏好设置后申请配额增加调整

如需为特定区域申请配额增加调整，并且已存在偏好设置，请运行以下命令：

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 或项目编号（该项目的 Cloud Quotas API 配额将用于执行此命令）。该项目可以不同于您申请配额调整的服务所属的项目。

如果您在设置 gcloud CLI 时已设置结算项目，则此标志是可选的。否则，省略该参数可能会导致权限遭拒错误。如需了解详情，请参阅设置配额项目。
EMAIL：可用作联系人的邮箱（如果 Google Cloud 需要更多信息才能授予额外的配额）。
JUSTIFICATION：可选字符串，用于说明您的请求。

查看现有配额偏好设置

如需查看您刚刚创建的配额偏好设置的详细信息，请运行以下命令：

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 或项目编号（该项目的 Cloud Quotas 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.
```
替换以下内容：
- KEY_FILE：JSON 服务账号密钥文件的路径。
- SA_NAME@CLIENT_PROJECT_ID.：服务账号电子邮件地址。

向服务账号授予 IAM 权限：

gcloud projects add-iam-policy-binding CLIENT_PROJECT_ID \
  --member="serviceAccount:SA_NAME@CLIENT_PROJECT_ID." \
  --role="roles/serviceusage.serviceUsageConsumer"

gcloud projects add-iam-policy-binding RESOURCE_PROJECT_ID \
  --member="serviceAccount:SA_NAME@CLIENT_PROJECT_ID." \
  --role="roles/cloudquotas.admin"

替换以下内容：

CLIENT_PROJECT_ID：客户端项目的 ID。
RESOURCE_PROJECT_ID：资源项目的 ID。
SA_NAME@CLIENT_PROJECT_ID.：服务账号电子邮件地址。

使用您之前创建的服务账号密钥激活服务账号：
```
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 部分。
如需详细了解配额术语，请参阅了解配额和系统限制术语。

使用 gcloud Beta 版 CLI 管理配额 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

限制

准备工作

安装并初始化 gcloud CLI

查找配额 ID

控制台

gcloud

gcloud 配额信息命令示例

查看特定服务的配额信息

查看组织的配额信息

gcloud 配额偏好设置命令示例

检查现有偏好设置

检查是否有待处理的配额调整的现有偏好设置

在尚未设置配额偏好设置时申请配额增加调整

在设置配额偏好设置后申请配额增加调整

查看现有配额偏好设置

通过客户端项目启用配额调整工具

其他具有配额相关 gcloud CLI 命令的服务

后续步骤

使用 gcloud Beta 版 CLI 管理配额