Cloud Quotas API を使用すると、プロジェクト レベルで割り当てをプログラムで調整し、割り当ての調整を自動化できます。Cloud Quotas API は、次の目的で使用できます。
- 割り当ての調整を自動化する
- Cloud Quotas API を使用して、特定の条件が満たされたときに割り当ての増加をリクエストできます。たとえば、割り当て超過エラーを回避するため、Compute Engine リソースが使用可能な割り当ての 80% に達したときに、API を使用して割り当ての増加をプログラムでリクエストします。
- プロジェクト間で割り当て構成をスケーリングする
- Cloud Quotas API を使用すると、プロジェクト間で割り当て構成のクローンを作成できます。新しい Google Cloud プロジェクトごとに割り当てを増やす必要がある既知の割り当てセットがある場合は、API をプロジェクトの作成ロジックに統合して、割り当て量増加のリクエストを自動化できます。割り当ての増加はすべて Google Cloud の承認の対象となります。
- 顧客の割り当てリクエストに対応する
- Google Cloud と統合された SaaS プロバイダの場合、Google Cloud コンソール以外の顧客向けポータルから割り当て増加リクエストが届くことがあります。これらのリクエストは、処理のために Google Cloud に転送する必要があります。Cloud Quotas API を使用すると、このような顧客のリクエストを自動的に転送できます。
- クライアント構成のバージョン管理を有効にする
- Cloud Quotas API は宣言型です。割り当ての構成をコードとして扱い、履歴とロールバックのために独自のバージョン管理システムに構成を保存できます。
制限事項
Cloud Quotas API には次の制限があります。
この API は Google Cloud CLI をサポートしていません。
この API は、フォルダレベルと組織レベルの割り当てに対する割り当て増加リクエストをサポートしていません。
サービス エンドポイント
サービス エンドポイントは、API サービスのネットワーク アドレスを指定するベース URL です。1 つのサービスに複数のエンドポイントが存在する場合があります。Cloud Quotas API サービスには次のエンドポイントがあり、すべての URI はこのエンドポイントを基準とします。
https://cloudquotas.googleapis.com
必要なロール
cloudquotas_quotaPreferences リソースと cloudquotas_quotaInfos リソースにアクセスするための権限を取得するには、プロジェクトに対する Cloud Quotas 管理者（cloudquotas.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与の詳細については、アクセス権の管理をご覧ください。
この事前定義ロールには、cloudquotas_quotaPreferences リソースと cloudquotas_quotaInfos リソースにアクセスするために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
cloudquotas_quotaPreferences リソースと cloudquotas_quotaInfos リソースにアクセスするには、次の権限が必要です。
-
cloudquotas.quotas.update -
cloudquotas.quotas.get -
monitoring.timeSeries.list -
resourcemanager.projects.get -
resourcemanager.projects.list
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
API リソースモデル
Cloud Quotas API リソースモデルは、QuotaPreference と QuotaInfo の 2 つのリソースで構成されています。
割り当ての設定
QuotaPreference リソースは、特定のディメンションの組み合わせに対する割り当ての設定を表します。このリソースを使用して、プロジェクト、フォルダ、または組織の割り当てを調整します。
リージョンの優先値を設定する
次の例は、CreateQuotaPreference メソッドの QuotaPreference リソースを示しています。
{
"service": "compute.googleapis.com",
"quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
"quotaConfig": {
"preferredValue": 100
},
"dimensions": {
"region": "us-central1"
}
}
preferredValue が 100 の場合、リクエスト元は、GPUS-PER-GPU-FAMILY-per-project-region の割り当てをその値に設定することを求めています。ディメンション フィールドは、設定がリージョン us-central1 にのみ適用されることを示しています。
付与された値を確認する
次の例は、GetQuotaPreference メソッドの QuotaPreference リソースを示しています。
{
"name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1",
"service": "compute.googleapis.com",
"quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
"quotaConfig": {
"preferredValue": 100,
"grantedValue": 100,
"traceId": "123acd-345df23",
"requestOrigin": "ORIGIN_UNSPECIFIED"
},
"dimensions": {
"region": "us-central1"
},
"createTime": "2023-01-15T01:30:15.01Z",
"updateTime": "2023-01-16T02:35:16.01Z"
}
この出力には次の値が含まれます。
PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。
レスポンスで grantedValue が 100 になっています。これは、前の例の preferredValue が承認され、履行されたことを意味します。ディメンションごとに異なる QuotaPreference リソースが設定されています。たとえば、リージョン us-central1 と us-east1 の CPU の QuotaPreference は 2 つの異なるリソースです。
割り当ての設定は必須
QuotaPreference リソースは、特定の割り当ての望ましい値を示すために使用されます。特定の割り当ての現在の値は、以下に基づいています。
自身で送信した
QuotaPreferenceリクエスト。Google Cloud によって承認された割り当て増加リクエスト。
Google Cloud によって開始される割り当ての変更。
QuotaPreference を削除する機能はサポートされていません。ただし、Google Cloud で承認された値よりも低い優先度の割り当て値を設定してガードレールを追加できます。
QuotaPreference リソースの詳細については、Cloud Quotas API リファレンスをご覧ください。
QuotaPreference クエリの詳細については、一般的なユースケースの実装をご覧ください。
割り当て情報
QuotaInfo は、特定のプロジェクト、フォルダ、または組織の特定の割り当てに関する情報を提供する読み取り専用リソースです。Google Cloud サービスで定義された割り当てと、ユーザーが開始した割り当て調整の情報が表示されます。QuotaInfo リソースには、メタデータ、コンテナタイプ、ディメンションなどの情報が含まれます。
リージョンごとに異なる割り当て値を設定する
次の QuotaInfo リソースの例は、プロジェクトの CPU 割り当てが、リージョン us-central1 では 200、それ以外のリージョンでは 100 であることを示しています。
{
"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"
],
"isPrecise": true,
"quotaDisplayName": "CPUs per project per region",
"metricDisplayName": "CPUs",
"dimensionsInfo": [
{
"dimensions": {
"region": "us-central1"
},
"details": {
"quotaValue": 200,
"resetValue": 200
},
"applicableLocations": [
"us-central1",
]
},
{
"details": {
"quotaValue": 100,
"resetValue": 100
},
"applicableLocations": [
"us-central2",
"us-west1",
"us-east1"
]
}
]
}
この出力には次の値が含まれます。
PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。
グローバル割り当てを設定する
次の QuotaInfo リソースの例は、1 分あたりの更新間隔が設定された、レートに基づく割り当てを示しています。ディメンションは空白です。これは、グローバル割り当てであることを示します。リージョンまたはゾーンのディメンションがない割り当てはすべてグローバルです。
{
"name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/ReadRequestsPerMinutePerProject",
"quotaId": "ReadRequestsPerMinutePerProject",
"metric": "compute.googleapis.com/read_requests",
"refreshInterval": "minute",
"containerType": "PROJECT",
"dimensions": [],
"isPrecise": false,
"quotaDisplayName": "Read Requests per Minute",
"metricDisplayName": "Read Requests",
"dimensionsInfo": [
{
"details": {
"quotaValue": 100,
"resetValue": 200
},
"applicableLocations": [
"global"
]
}
]
}
この出力には次の値が含まれます。
PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。
QuotaInfo リソースの詳細については、Cloud Quotas API リファレンスをご覧ください。
QuotaPreference クエリの詳細については、一般的なユースケースの実装をご覧ください。
リソース名
リソースは名前付きエンティティであり、リソース名で識別されます。リソース名はすべてのリクエストとレスポンスで使用されます。各リソースには独自の一意のリソース名が必要です。各リソース名は一連のフィールドによってエンコードされます。
割り当て設定リソース
QuotaPreference リソースの命名規則では、次のパターンを使用します。
projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID
割り当て設定を作成するときに quotaPreferenceId を設定できます。設定しない場合は、ID が生成されます。quotaPreferenceId 命名規則では、サービス名、割り当て ID、ロケーションなどのディメンションをエンコードすることをおすすめします。quotaPreferenceId は、プロジェクト、フォルダ、または組織に対して一意である必要があります。
たとえば、quotaPreference の場合、割り当て設定 ID をエンコードするパターンは次のとおりです。
SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER
次の例は、このパターンを示しています。
compute_us-central1_nvidia-200
リソース名の場合、GET メソッドを使用して QuotaPreference を取得する必要があります。allow_missing オプションを有効にして UPDATE メソッドを呼び出し、QuotaPreference を作成または更新することもできます。
割り当て情報リソース
QuotaInfo リソースの命名規則では、次のパターンを使用します。
projects/PROJECT_NUMBER/locations/global/services/SERVICE_NAME/quotaInfos/QUOTA_ID
ディメンションの優先順位
Cloud Quotas API の一部のユースケースでは、ディメンション設定が複雑になる場合があります。割り当ては、リージョンとゾーンだけでなく、より細かいレベルで構成できます。サービス固有のディメンションを使用するときに、この粒度を使用できます。たとえば、gpu_family と network_id は、Compute Engine サービス固有のディメンションです。ディメンションは個々のサービスによって定義されます。各サービスでサービス固有のディメンションのセットが異なる場合もあります。
ロケーション ディメンションまたはサービス固有のディメンションを使用する場合は、次の優先順位が適用されます。
ロケーションとサービス固有のディメンションがすべて指定されている割り当て設定は、他の構成よりも優先されます。
ロケーション ディメンションを指定する構成は、サービス固有のディメンションのみを含む構成よりも優先されます。
ディメンションの組み合わせ
割り当て設定の構成では、次の方法でディメンションを組み合わせることができます。
構成にロケーション ディメンションとサービス固有のディメンションの両方を含める。これは設定の中で最も高い優先順位になります。
構成にロケーション ディメンションのみを含める。この構成は、方法 1 で明示的に構成されたものを除き、サービス固有のすべてのディメンションに適用されます。
構成にサービス固有のディメンションのみを含める。この構成は、方法 1 または 2 で明示的に構成したものを除き、すべてのロケーションに適用されます。
構成にサービス固有のディメンションが含まれている場合は、サービス固有のディメンションをすべて含める必要があります。
ディメンションなしで構成することもできます。このような構成は、明示的に構成されたものを除き、すべてのロケーションとサービス固有のディメンションに適用されます。