このページでは、Cloud Quotas API を使用して一般的なユースケースを実装する方法について説明します。この API を使用すると、Google Cloud のプロジェクト、フォルダ、組織での割り当てをプログラムで調整し、割り当ての調整を自動化できます。
詳細については、Cloud Quotas API の概要とリファレンスをご覧ください。
制限事項
Cloud Quotas には次の制限があります。
割り当ての引き上げ調整はプロジェクト レベルで行う必要があり、Google Cloud での承認が必要です。
Cloud Quotas API は、プロジェクト レベルのオペレーションのみをサポートしています。フォルダレベルと組織レベルのオペレーションはサポートされていません。
使用率を追跡し、使用率が 80% を超えたら引き上げをリクエストする
この例では、Cloud Monitoring で割り当て使用率を追跡し、使用率が 80% を超えたら増加をリクエストします。
- サービスの
QuotaInfoリソースを呼び出して、現在のquotaValueを確認します。この例のサービスはcompute.googleapis.comです。GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfosPROJECT_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" ] } ] }, ... ]
- 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" } }
- 使用率を確認するには、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 } } }
- 割り当て設定の重複を避けるには、まず
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": { "region": "us-central1" }, "justification": "JUSTIFICATION", "contactEmail": "EMAIL" }
次のように置き換えます。
PROJECT_NUMBER: プロジェクトの固有識別子。JUSTIFICATION: リクエストを説明する文字列（省略可）。EMAIL: 連絡先として使用できるメールアドレス。Google Cloud が、追加の割り当てを付与する前に追加情報が必要な場合に使用されます。
GetQuotaPreferenceを呼び出して、割り当て設定の変更ステータスを確認します。GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1PROJECT_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フィールドがfalseに設定されます。grantedValueはpreferredValueと同じです。優先割り当てが完全に付与されます。
Google Cloud がユーザーのリクエストを拒否または部分的に承認した場合でも、付与される割り当て値が推奨値より小さくなる場合があります。
割り当てを減らす
次の例では、各リージョンの TPU の数を 10 に減らしています。
ListQuotaInfosを呼び出して、割り当て ID と現在の割り当て値を取得します。GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfosPROJECT_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" ] } ] }, ... ]
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", "justification": "JUSTIFICATION", "contactEmail": "EMAIL" }
次のように置き換えます。
PROJECT_NUMBER: プロジェクトの固有識別子。JUSTIFICATION: リクエストを説明する文字列（省略可）。EMAIL: 連絡先として使用できるメールアドレス。Google Cloud が、追加の割り当てを付与する前に追加情報が必要な場合に使用されます。
- 割り当て ID を
V2-TPUS-per-project-regionとして定義するGetQuotaInfo呼び出しで、新しい割り当て値を確認します。GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-regionPROJECT_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 で記述されていますが、任意のプログラミング言語を使用できます。
- ソース プロジェクトでフィルタを使用せずに
ListQuotaPreferencesを呼び出します。GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences - レスポンスの割り当て設定ごとに、
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()) .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); }
ListQuotaPreferencesを呼び出して、宛先プロジェクトの割り当て設定のステータスを確認します。GET projects/PROJECT_NUMBER2/locations/global/quotaPreferencesPROJECT_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" } ]
グループの割り当ての増加をリクエストする
新しいプロジェクトの割り当てグループの増加をリクエストするには、サービス名、割り当て 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) .setJustification(justification) .setContactEmail(contactEmail) .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue)) .putAllDimensions(dimensionMap)) .build(); cloudQuotas.createQuotaPreference(request);
PROJECT_NUMBER は、プロジェクトのプロジェクト番号に置き換えます。
ターゲット プロジェクトは新しいため、フィールドの読み取りと割り当てを行うときに CreateQuotaPreference メソッドを呼び出しても安全です。また、allow_missing を true に設定して UpdateQuotaPreference メソッドを呼び出すこともできます。
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" },
"justification": "JUSTIFICATION",
"contactEmail": "EMAIL"
}
次のように置き換えます。
PROJECT_NUMBER: プロジェクトの固有識別子。JUSTIFICATION: リクエストを説明する文字列（省略可）。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-regionPROJECT_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": { "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 ファミリーは、キー gpu_family を使用して指定します。
次の CreateQuotaPreference の例では、GPU ファミリーとして NVIDIA_H100 を、リージョンとして 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: 連絡先として使用できるメールアドレス。Google Cloud が、追加の割り当てを付与する前に追加情報が必要な場合に使用されます。
サービス固有のディメンションの割り当て設定を更新する
次のサンプルコードでは、ディメンション {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, の現在の値を取得し、優先値にその 2 倍の値を設定します。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 は、プロジェクトの固有識別子に置き換えます。
次のステップ
Cloud Quotas API について
Cloud Quotas API リファレンス
割り当てについて学習する