实现常见使用场景

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

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

限制

Cloud 配额具有以下限制:

  • 在大多数情况下,配额“增加”调整必须在项目级进行。只有少数产品支持组织级配额增加调整。如需了解某个 Trusted Cloud by S3NS 产品是否支持组织级配额增加调整,请参阅该产品的文档。

  • 您可以针对项目、组织和文件夹级配额请求配额减少调整。

跟踪用量,并在用量超过 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" },
    "justification": "JUSTIFICATION",
    "contactEmail": "EMAIL"
    }

    替换以下内容:

    • PROJECT_NUMBER:您的项目的唯一标识符。
    • JUSTIFICATION:可选字符串,用于说明您的请求。
    • EMAIL:可用作联系人的电子邮件地址(如果 Trusted Cloud by S3NS 需要更多信息才能授予额外的配额)。
  7. 调用 GetQuotaPreference 以检查配额偏好设置更改的状态:

    GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1

    PROJECT_NUMBER 替换为您的项目编号。

    当 Trusted Cloud by S3NS 评估请求的配额值时,您的配额的正在调整状态会设置为 true

    有时, Trusted Cloud by S3NS 会批准您增加请求中的一部分,而不是批准全部增加。如果请求获得部分批准,配额偏好设置会包含 stateDetail 字段。stateDetail 字段描述部分获批的状态。grantedValue 字段显示为部分满足您的请求而进行的调整。

    如需查看授予的值是否为最终批准的值,请查看 reconciling 字段。如果您的请求仍在评估中,则 reconciling 字段会设置为 true。如果 reconciling 字段设置为 false 或已省略,则授予的值为最终批准的值。

    在以下示例中,请求的配额值为 100,且 reconciling 字段表示相应请求正在接受审核。

    "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 相同。首选配额已完整授予。

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

减少配额

以下示例将每个区域中的 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",
      "justification": "JUSTIFICATION",
      "contactEmail": "EMAIL"
    }

    替换以下内容:

    • PROJECT_NUMBER:您的项目的唯一标识符。
    • JUSTIFICATION:可选字符串,用于说明您的请求。
    • EMAIL:可用作联系人的电子邮件地址(如果 Trusted Cloud by S3NS 需要更多信息才能授予额外的配额)。
  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"
          ]
      }
    ]

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

以下示例将所有配额偏好设置从一个项目复制到另一个项目。 该示例是使用 Java 编写的,但您可以使用任何编程语言。

  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())
          .setJustification(srcPreference.getJustification())
          .setContactEmail(srcPreference.getContactEmail())
          .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)
            .setJustification(justification)
            .setContactEmail(contactEmail)
            .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)的配额,这些配额可能无法显示在 Trusted Cloud 控制台中。您可能需要改用 Cloud Quotas API。

例如,您可以克隆项目并提前知道需要增加 compute.googleapis.com/gpus_per_gpu_family 的值。此值仅会针对您已使用的 GPU 系列显示在 Trusted 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" },
    "justification": "JUSTIFICATION",
    "contactEmail": "EMAIL"
}

替换以下内容:

  • PROJECT_NUMBER:您的项目的唯一标识符。
  • JUSTIFICATION:可选字符串,用于说明您的请求。
  • EMAIL:可用作联系人的电子邮件地址(如果 Trusted Cloud by S3NS 需要更多信息才能授予额外的配额)。

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

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

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"},
    "justification": "JUSTIFICATION",
    "contactEmail": ""EMAIL"
}

替换以下内容:

  • PROJECT_NUMBER:您的项目的唯一标识符。
  • JUSTIFICATION:可选字符串,用于说明您的请求。
  • EMAIL:可用作联系人的电子邮件地址(如果 Trusted Cloud by S3NS 需要更多信息才能授予额外的配额)。

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

以下示例代码获取维度 {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, 的当前值,然后将首选值设为该值的两倍。该示例是使用 Java 编写的,但您可以使用任何编程语言。

// 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)
        .setJustification(justification)
        .setContactEmail(contactEmail)
        .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2))
        .putAllDimensions(targetDimensions));
UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
 cloudQuotas.updateQuotaPreference(updateRequest);

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

后续步骤