このページでは、Cloud Quotas API を使用して一般的なユースケースを実装する方法について説明します。この API を使用すると、Google Cloud のプロジェクト、フォルダ、組織での割り当てをプログラムで調整し、割り当ての調整を自動化できます。
詳細については、Cloud Quotas API の概要とリファレンスをご覧ください。
制限事項
Cloud Quotas API には次の制限があります。
この API は Google Cloud CLI をサポートしていません。
この API は、プロジェクト レベルの割り当ての調整をサポートしています。割り当ての減少は、プロジェクト レベル、フォルダレベル、組織レベルの割り当てに対してリクエストできます。
この API は VPC Service Controls をサポートしていません。
使用率を追跡し、使用率が 80% を超えたら引き上げをリクエストする
この例では、Cloud Monitoring で割り当て使用率を追跡し、使用率が 80% を超えたら増加をリクエストします。
- サービスの
QuotaInfo
リソースを呼び出して、現在のquotaValue
を確認します。この例のサービスはcompute.googleapis.com
です。GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
PROJECT_NUMBER
は、プロジェクトのプロジェクト番号に置き換えます。 - プロジェクトごとの 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" ] } ] }, … ]
この出力には次の値が含まれます。PROJECT_NUMBER
: プロジェクトに対して自動的に生成される固有識別子。
- Cloud Monitoring API を呼び出して、割り当ての使用状況を確認します。次の例では、リージョン
us-central1
が指定されています。サポートされている割り当て指標は、serviceruntime
に表示されます。{ "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 } }
この出力には次の値が含まれます。PROJECT_NUMBER
: プロジェクトに対して自動的に生成される固有識別子。
- 使用率を確認するには、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 } } }
この出力には次の値が含まれます。PROJECT_ID
: 実際のプロジェクトのグローバル固有識別子。
- 割り当て設定の重複を避けるには、まず
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
は、プロジェクトのプロジェクト番号に置き換えます。 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": [ "mapField": { "key": "region", "value": "us-central1" } ], }
この出力には次の値が含まれます。PROJECT_NUMBER
: プロジェクトに対して自動的に生成される固有識別子。
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": [ "mapField": { "key": "region", "value": "us-central1" } ], "reconciling": true "createTime": "2023-01-15T01:30:15.01Z", "updateTime": "2023-01-16T02:35:16.01Z"
この出力には次の値が含まれます。PROJECT_NUMBER
: プロジェクトに対して自動的に生成される固有識別子。
reconciling
フィールドがfalse
に設定されます。grantedValue
はpreferredValue
と同じです。優先割り当てが完全に付与されます。
Google Cloud がユーザーのリクエストを拒否または部分的に承認した場合でも、付与される割り当て値が推奨値より小さくなる場合があります。
割り当てを減らす
次の例では、各リージョンの TPU の数を 10 に減らしています。
ListQuotaInfos
を呼び出して、割り当て ID と現在の割り当て値を取得します。GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
PROJECT_NUMBER
は、プロジェクトのプロジェクト番号に置き換えます。- レスポンス フィールドを調べて、
V2-TPUS-per-project-region
のQuotaInfo
エントリを見つけます。"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" ] } ] }, … ]
この出力には次の値が含まれます。PROJECT_NUMBER
: プロジェクトに対して自動的に生成される固有識別子。
V2-TPUS-per-project-region
で、現在のquotaValue
は 20 です。 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", }
この出力には次の値が含まれます。PROJECT_NUMBER
: プロジェクトに対して自動的に生成される固有識別子。
- 割り当て ID を
V2-TPUS-per-project-region
として定義するGetQuotaInfo
呼び出しで、新しい割り当て値を確認します。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" ] } ]
この出力には次の値が含まれます。PROJECT_NUMBER
: プロジェクトに対して自動的に生成される固有識別子。
割り当て設定を別のプロジェクトにコピーする
次の例では、プロジェクト間ですべての割り当て設定をコピーします。
- ソース プロジェクトでフィルタを使用せずに
ListQuotaPreferences
を呼び出します。GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
PROJECT_NUMBER1 は、ソース プロジェクトのプロジェクト番号です。レスポンスには、ソース プロジェクトのすべての割り当て設定が含まれます。 - レスポンスの割り当て設定ごとに、
UpdateQuotaPreference
を呼び出して次のフィールドを定義します。name
- 更新された名前フィールドがレスポンスから取得され、ソース プロジェクト番号(PROJECT_NUMBER1)が宛先プロジェクト番号(PROJECT_NUMBER2)に置き換えられます。service
、quotaId
、preferredValue
、dimensions
- これらのフィールドはそのままレスポンスから直接取得できます。
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); }
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": [ "map_field": { "key": "region", "value": "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" } ]
この出力には次の値が含まれます。
PROJECT_NUMBER
: プロジェクトに対して自動的に生成される固有識別子。
グループの割り当ての増加をリクエストする
新しいプロジェクトの割り当てグループの増加をリクエストするには、サービス名、割り当て ID、優先割り当て値、ディメンションの値を含む CSV ファイルに新しいプロジェクトの優先割り当てを保存します。
CSV ファイルの各行で、serviceName
、quotaId
、preferredValue
、dimensionMap
フィールドの内容を確認します。
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
メソッドを呼び出しても安全です。また、allow_missing
を true
に設定して UpdateQuotaPreference
メソッドを呼び出すこともできます。
buildYourOwnQuotaPreferenceId
メソッドは、サービス名、割り当て ID、命名規則に応じたディメンションのマップから割り当て設定 ID を作成します。また、割り当て設定 ID を設定しないようにすることもできます。割り当て設定 ID が生成されます。
サービス固有のディメンションの割り当て情報を取得する
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
キーごとに、quotaValue
と applicableLocations
が異なります。
"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": [ "mapField": { "key": "region", "value": "us-central1" }, "mapField": { "key": "gpu_family", "value": "NVIDIA_H200" } ], "details": { "quotaValue": 30, "resetValue": 30, }, "applicableLocations": [ "us-central1" ] }, { "dimensions": [ "mapField": { "key": "region", "value": "us-central1" } ], "details": { "quotaValue": 100, "resetValue": 100, }, "applicableLocations": [ "us-central1" ] }, { "dimensions": [ "mapField": { "key": "gpu_familly", "value": "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" ] } ]
この出力には次の値が含まれます。
PROJECT_NUMBER
: プロジェクトに対して自動的に生成される固有識別子。
サービス固有のディメンションの割り当て設定を作成する
次の例は、特定のリージョンと GPU ファミリーの割り当てを優先値 100 で作成する方法を示しています。ターゲット ロケーションは、キー region
を使用してディメンションのマップに指定します。ターゲット GPU ファミリーは、キー gpu_family
を使用して指定します。
次の CreateQuotaPreference
の例では、GPU ファミリーとして NVIDIA_H100
を、リージョンとして us-central1
を指定しています。PROJECT_NUMBER
は、プロジェクトのプロジェクト番号に置き換えます。
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": [ "mapField": { "key": "region", "value": "us-central1" } "mapField": { "key": "gpu_family", "value": "NVIDIA_H100" } ], }
サービス固有のディメンションの割り当て設定を更新する
次のサンプルコードでは、ディメンション {"region" : "us-central1"; gpu_family:"NVIDIA_H100"} の現在値を取得し、優先値にその 2 倍の値を設定します。PROJECT_NUMBER
は、プロジェクトのプロジェクト番号に置き換えます。
// 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);
次のステップ
Cloud Quotas API について
Cloud Quotas API リファレンス
割り当てについて学習する