实现常见使用场景

本页面介绍如何使用 Cloud Quotas API 实现常见应用场景。借助此 API,您能够在 Google Cloud 项目、文件夹或组织中以编程方式调整配额并自动执行配额调整

如需了解详情,请参阅 Cloud Quotas API 概览参考文档

限制

Cloud 配额具有以下限制:

  • 配额“增加”调整必须在项目级进行,并需要获得 Google Cloud 批准。

  • 您可以针对project-folder-组织级配额请求配额减少调整。

  • Cloud Quotas API 仅支持项目级操作。文件夹级和组织级操作不受支持。

跟踪用量,并在用量超过 80% 时请求增加配额

此示例通过 Cloud Monitoring 跟踪配额用量,然后在用量超过 80% 时请求增加配额。

  1. 调用服务的 QuotaInfo 资源以确定当前 quotaValue。此示例中的服务为 compute.googleapis.com
    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
    PROJECT_NUMBER 替换为您的项目编号。
  2. 如需了解每个项目的 CPU 数量以及适用的位置,请在 QuotaInfo 响应中查找 CPUS-per-project-region 配额 ID。quotaValue 为 20。
    "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": [
                {
                    "dimensions": [],
                    "details": {
                        "quotaValue": 20,
                        "resetValue": 20
                    },
                    "applicableLocations": [
                        "us-central1",
                        "us-central2",
                        "us-west1",
                        "us-east1"
                    ]
                }
            ]
        },
        ...
    ]
    
  3. 调用 Cloud Monitoring API 以了解配额用量。在以下示例中,指定了区域 us-central1serviceruntime 下列出了支持的配额指标。
    {
    "name": "projects/PROJECT_NUMBER"
        "filter": "metric.type=\"serviceruntime.googleapis.com/quota/allocation/usage\" AND
        metric.labels.quota_metric=\"compute.googleapis.com/cpus\" AND resource.type=\"consumer_quota\" AND
        resource.label.location=\"us-central1\" ",
        "interval": {
        "startTime": "2023-11-10T18:18:18.0000Z",
        "endTime": "2023-11-17T18:18:18.0000Z"
        },
        "aggregation": {
        "alignmentPeriod": "604800s", // 7 days
        "perSeriesAligner": "ALIGN_MAX",
        "crossSeriesReducer": "REDUCE_MAX"
        }
    }
    
  4. 如需确定您的用量,请处理来自 Cloud Monitoring API 的响应。 将来自 Cloud Monitoring 的值与前面步骤中的 quotaValue 进行比较以确定用量。

    在以下示例响应中,Cloud Monitoring 中的用量值在 us-central1 区域中 为 19。所有区域的 quotaValue 为 20。用量超过配额的 80%,您可以发起配额偏好设置更新。
    time_series {
     metric {
      labels {
       key: "quota_metric"
       value: "compute.googleapis.com/cpus"
      }
         type: "serviceruntime.googleapis.com/quota/allocation/usage"
      }
      resource {
        type: "consumer_quota"
        labels {
          key: "project_id"
          value: "PROJECT_ID"
        }
        labels {
          key: "location"
          value: "us-central1"
        }
      }
      metric_kind: GAUGE
      value_type: INT64
      points {
        interval {
          start_time {
            seconds: "2023-11-10T18:18:18.0000Z"
          }
          end_time {
            seconds: "2023-11-17T18:18:18.0000Z"
          }
        }
        value {
          int64_value: 19
        }
      }
    }
    
  5. 如需避免重复的配额偏好设置,请先调用 ListQuotaPreferences 来检查是否存在任何待处理的请求。reconciling=true 标志会调用待处理的请求。
    GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true
    PROJECT_NUMBER 替换为您的项目编号。
  6. 调用 UpdateQuotaPreference 以增加区域 us-central1 的配额值。在以下示例中,指定了新的首选值 100。

    字段 allow_missing 设置为 true。这会指示系统使用所提供的名称创建其中不存在任何内容的 QuotaPreference 资源。
    PATCH projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1?allowMissing=true {
      "service": "compute.googleapis.com",
      "quotaId": "CPUS-per-project-region",
      "quotaConfig": { "preferredValue": 100 },
      "dimensions": { "region": "us-central1" }
    }
    
  7. 调用 GetQuotaPreference 以检查配额偏好设置更改的状态:
    GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1
    PROJECT_NUMBER 替换为您的项目编号。 Google Cloud 评估请求的配额值时,正在调整状态会设置为 true
    "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1",
    "service": "compute.googleapis.com",
    "quotaId": "CPUS-per-project-region",
    "quotaConfig": {
        "preferredValue": 100,
        "grantedValue": 50,
        "traceId": "123acd-345df23",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
    },
    "dimensions": { "region": "us-central1" },
    "reconciling": true,
    "createTime": "2023-01-15T01:30:15.01Z",
    "updateTime": "2023-01-16T02:35:16.01Z"
    
    配额偏好设置处理完成后,将 reconciling 字段设置为 falsegrantedValuepreferredValue 相同。首选配额已完整授予。

    如果 Google Cloud 拒绝或部分批准客户请求,则授予的配额值仍然可能小于首选值。

减少配额

以下示例将每个区域中的 TPU 数量减少到 10。

  1. 使用 ListQuotaInfos 调用获取配额 ID 和当前配额值:
    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
    PROJECT_NUMBER 替换为您的项目编号。
  2. 浏览响应字段以查找 V2-TPUS-per-project-regionQuotaInfo 条目。
    "quotaInfos": [
        ...
         {
            "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region",
            "quotaId": "V2-TPUS-per-project-region",
            "metric": "compute.googleapis.com/Tpus",
            "containerType": "PROJECT",
            "dimensions": [
                "region"
            ],
            "dimensionsInfo": [
                {
                    "dimensions": [],
                    "details": {
                        "quotaValue": 20,
                        "resetValue": 20
                    },
                    "applicableLocations": [
                        "us-central1",
                        "us-central2",
                        "us-west1",
                        "us-east1"
                    ]
                }
            ]
        },
        ...
    ]
    
    在此响应中,配额 ID 为 V2-TPUS-per-project-region,当前 quotaValue 为 20。
  3. 使用 CreateQuotaPreferenceRequest 将每个区域中的 TPU 配额减少到 10。 将 preferredValue 设置为 10。
    POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-Tpu-all-regions {
        "quotaConfig": {
            "preferredValue": 10
        },
        "dimensions": [],
        "service": "compute.googleapis.com",
        "quotaId": "V2-TPUS-per-project-region",
        "contactEmail": EMAIL
    }
    
  4. 使用将配额 ID 定义为 V2-TPUS-per-project-regionGetQuotaInfo 调用确认新的配额值。
    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region
    PROJECT_NUMBER 替换为您的项目编号。 以下是示例响应,value 为 10,适用于所有区域。
    "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region",
    "quotaId": "V2-TPUS-per-project-region",
    "metric": "compute.googleapis.com/v2_tpus",
    "containerType": "PROJECT",
    "dimensions": [
        "region"
    ],
    "dimensionsInfo": [
        {
            "dimensions": [],
            "details": {
                "value": 10,
            },
            "applicableLocations": [
                "us-central1",
                "us-central2",
                "us-west1",
                "us-east1"
            ]
        }
    ]
    

将配额偏好设置复制到另一个项目

以下示例将所有配额偏好设置从一个项目复制到另一个项目。

  1. 在不使用过滤条件的情况下对源项目调用 ListQuotaPreferences
    GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
    PROJECT_NUMBER1 是源项目的项目编号。响应包含源项目的所有配额偏好设置。
  2. 对于响应中的每个配额偏好设置,请调用 UpdateQuotaPreference 并定义以下字段:
    • name - 更新后的名称字段从响应中获取,源项目编号 (PROJECT_NUMBER1) 会替换为目标项目编号 (PROJECT_NUMBER2)。
    • servicequotaIdpreferredValuedimensions - 这些字段可以直接从响应中按原样获取。
    for (QuotaPreference srcPreference : listResponse.getQuotaPreferences()) {
        QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
            .setName(srcPreference.getName().replace("PROJECT_NUMBER1", "PROJECT_NUMBER2"))
            .setService(srcPreference.getService())
            .setQuotaId(srcPreference.getQuotaId())
            .setQuotaConfig(
                QuotaConfig.newBuilder().setPreferredValue(srcPreference.getQuotaConfig().getPreferredValue()))
            .putAllDimensions(srcPreference.getDimensionsMap());
        UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
            .setQuotaPreference(targetPreference)
            .setAllowMissing(true)
            .build();
        cloudQuotas.updateQuotaPreference(updateRequest);
    }
    
  3. 调用 ListQuotaPreferences 以验证目标项目的配额偏好设置的状态:
    GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences
    PROJECT_NUMBER2 替换为目标项目的项目编号。

列出待处理的配额请求

如需列出项目的所有待处理配额偏好设置请求,请使用过滤条件 reconciling=true 调用 ListQuotaPreferences

Get projects/PROJECT_NUMBER/locations/global/quotaPreferences?reconciling=true

PROJECT_NUMBER 替换为您的项目编号。

此请求的响应会返回最新的待处理配额偏好设置。由于 Cloud Quotas API 是声明式 API,因此最新的配额偏好设置是系统尝试实现的目标。

示例响应类似于以下内容:

  "quotaPreferences": [
    {
      "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1",
      "service": "compute.googleapis.com",
      "quotaId": "CPUS-per-project-region",
      "quotaConfig": {
        "preferredValue": 100,
        "grantedValue": 30,
        "traceId": "123acd-345df23",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
      },
      "dimensions": {
        "region": "us-central1"
      },
      "reconciling": true,
      "createTime": "2023-01-15T01:30:15.01Z",
      "updateTime": "2023-01-16T02:35:16.01Z"
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-cross-regions",
      "service": "compute.googleapis.com",
      "quotaId": "CPUS-per-project-region",
      "quotaConfig": {
        "preferredValue": 10,
        "grantedValue": 5,
        "traceId": "456asd-678df43",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
      },
      "reconciling": true,
      "createTime": "2023-01-15T01:35:15.01Z",
      "updateTime": "2023-01-15T01:35:15.01Z"
    }
  ]

请求增加群组配额

如需请求增加新项目中的一组配额,请通过以下值将新项目的首选配额存储在 CSV 文件中:服务名称、配额 ID、首选配额值、维度。

对于 CSV 文件中的每一行,请将内容读取到字段 serviceNamequotaIdpreferredValuedimensionMap 中。

CreateQuotaPreferenceRequest request =
  CreateQuotaPreferenceRequest.newBuilder()
     .setParent("projects/PROJECT_NUMBER/locations/global")
     .setQuotaPreferenceId(buildYourOwnQuotaPreferenceId(serviceName, quotaId, dimensionMap))
     .setQuotaPreference(
        QuotaPreference.newBuilder()
            .setService(serviceName)
            .setQuotaId(quotaId)
            .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue))
            .putAllDimensions(dimensionMap))
  .build();
cloudQuotas.createQuotaPreference(request);

PROJECT_NUMBER 替换为您的项目编号。

由于目标项目是新项目,因此在读取和分配字段时,可以安全地调用 CreateQuotaPreference 方法。或者,您可以调用 UpdateQuotaPreference 方法,其中将 allow_missing 设置为 true

buildYourOwnQuotaPreferenceId 方法会根据命名方案,通过服务名称、配额 ID 和维度映射构建配额偏好设置 ID。或者,您可以选择不设置配额偏好设置 ID。系统会为您生成配额偏好设置 ID。

请求调整无用量配额

对于尚未有配额用量且具有服务专属维度(例如 vm_family)的配额,这些配额可能无法显示在 Google Cloud 控制台中。您可能需要改用 Cloud Quotas API。

例如,您可以克隆项目并提前知道需要增加 compute.googleapis.com/gpus_per_gpu_family 的值。此值仅会针对您已使用的 GPU 系列显示在 Google Cloud 控制台中。如需使用 Cloud Quotas API 请求增加 us-central1 中的 NVIDIA_H100 GPU,您可以发送如下请求:

POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-gpus-us-central1-NVIDIA_H100 {
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": { "preferredValue": 100 },
    "dimensions": { "region": "us-central1", "gpu_family": "NVIDIA_H100" },
    "contactEmail": EMAIL
}

替换以下内容:

  • PROJECT_NUMBER:您的项目的唯一标识符。
  • EMAIL:可用作联系人的电子邮件地址(如果 Google Cloud 需要更多信息来做出决定,然后才能授予额外的配额)。

如需了解详情,另请参阅维度优先级组合维度的说明。

获取特定于服务的维度的配额信息

GPU 系列是特定于服务的维度。以下示例请求使用 GPUS-PER-GPU-FAMILY-per-project-region 配额 ID 获取 QuotaInfo 资源。

GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GPUS-PER-GPU-FAMILY-per-project-region

PROJECT_NUMBER 替换为您的项目编号。

这是一个示例响应。对于每个唯一的 gpu_family 键,quotaValueapplicableLocations 是不同的:

"name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GpusPerProjectPerRegion",
"quotatName": "CPUS-per-project-region",
"metric": "compute.googleapis.com/gpus_per_gpu_family",
"isPrecise": true,
"quotaDisplayName": "GPUs per GPU family",
"metricDisplayName": "GPUs",
"dimensions": [
    "region",
    "gpu_family"
],
"dimensionsInfo": [
    {
        "dimensions": {
            "region": "us-central1",
            "gpu_family": "NVIDIA_H200"
        },
        "details": {
            "quotaValue": 30,
            "resetValue": 30,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": {
            "region": "us-central1"
            }
        "details": {
            "quotaValue": 100,
            "resetValue": 100,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": {
            "gpu_familly": "NVIDIA_H100"
            }
        "details": {
            "quotaValue": 10,
        },
        "applicableLocations": [
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
      {
        "dimensions": [],
        "details": {
            "quotaValue": 50,
            "resetValue": 50,
        },
        "applicableLocations": [
            "us-central1",
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
]

为特定于服务的维度创建配额偏好设置

以下示例演示了如何为给定区域和 GPU 系列创建首选值为 100 的配额。目标位置在具有键 region 的维度映射以及具有键 gpu_family 的目标 GPU 系列中指定。

以下 CreateQuotaPreference 示例指定了 NVIDIA_H100 GPU 系列和 us-central1 区域。

POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-gpus-us-central1-NVIDIA_H100 {
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": {"region": "us-central1", "gpu_family": "NVIDIA_H100"},
    "contactEmail": EMAIL"
}

替换以下内容:

  • PROJECT_NUMBER:您的项目的唯一标识符。
  • EMAIL:可用作联系人的电子邮件地址(如果 Google Cloud 需要更多信息来做出决定,然后才能授予额外的配额)。

为特定于服务的维度更新配额偏好设置

以下示例代码获取维度 {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, 的当前值,然后将首选值设为该值的两倍。

// Get the current quota value for the target dimensions
Map<String, String> targetDimensions = Maps.createHashMap("region", "us-central1", "gpu_family", "NVIDIA_H100");
long currentQuotaValue = 0;
QuotaInfo quotaInfo = cloudQuotas.GetQuotaInfo(
    "projects/PROJECT_NUMBER/locations/global/services/" + serviceName + "quotaInfos/" + quotaId;
for (dimensionsInfo : quotaInfo.getDimensionsInfoList()) {
    If (targetDimensions.entrySet().containsAll(dimensionsInfo.getDimensionsMap().entrySet()) {
       currentQuotaValue = dimensionsInfo.getDetails().getValue();
       break;
    })
}

// Set the preferred quota value to double the current value for the target dimensions
QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
        .setName(buildYourOwnQuotaPreferenceId(serviceName, quotaId, targetDimensions))
        .setService(serviceName)
        .setQuotaId(quotaId)
        .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2))
        .putAllDimensions(targetDimensions));
UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
 cloudQuotas.updateQuotaPreference(updateRequest);

PROJECT_NUMBER 替换为您的项目的唯一标识符。

后续步骤