Gängige Anwendungsfälle implementieren

Auf dieser Seite wird beschrieben, wie Sie gängige Anwendungsfälle mithilfe der Cloud Quotas API implementieren. Mit dieser API können Sie Kontingente programmatisch anpassen und Kontingentanpassungen in Ihren Google Cloud-Projekten, Ordnern oder Ihrer Organisation automatisieren.

Weitere Informationen finden Sie in der Übersicht und in der Referenz zur Cloud Quotas API.

Beschränkungen

Für Cloud-Kontingente gelten die folgenden Einschränkungen:

• Anpassungen der Kontingenterhöhung müssen auf Projektebene vorgenommen werden und unterliegen der Genehmigung von Google Cloud.

• You can request quota decrease adjustments for project-, folder-, and auf Organisationsebene.

• Die Cloud Quotas API unterstützt nur Vorgänge auf Projektebene. Vorgänge auf Ordner- und Organisationsebene werden nicht unterstützt.

Wichtig: Informationen zu Pflichtfeldern und erwarteten Werten finden Sie unter REST-Ressource: folders.locations.quotaPreferences.

Verfolgen Sie die Nutzung und fordern Sie einen Anstieg an, wenn die Nutzung über 80 % liegt.

In diesem Beispiel wird die Kontingentnutzung mit Cloud Monitoring nachverfolgt. Anschließend wird eine Erhöhung angefordert, wenn die Nutzung über 80 % liegt.

1. Rufen Sie die Ressource QuotaInfo für Ihren Dienst auf, um den aktuellen quotaValue zu ermitteln. Der Dienst in diesem Beispiel ist compute.googleapis.com:

   GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos

   Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.
2. Suchen Sie in der Antwort QuotaInfo nach der Kontingent-ID CPUS-per-project-region, um die CPUs pro Projekt und die entsprechenden Standorte zu ermitteln. Der quotaValue ist 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. Rufen Sie die Cloud Monitoring API auf, um die Kontingentnutzung zu ermitteln. Im folgenden Beispiel wurde die Region us-central1 angegeben. Unterstützte Kontingentmesswerte sind unter serviceruntime aufgeführt.

   {
   "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. Verarbeiten Sie zum Ermitteln der Nutzung die Antwort der Cloud Monitoring API. Vergleichen Sie den Wert von Cloud Monitoring mit dem quotaValue in den vorherigen Schritten, um die Nutzung zu ermitteln.
   
   In der folgenden Beispielantwort beträgt der Nutzungswert in Cloud Monitoring 19 in der Region us-central1. Der quotaValue für alle Regionen ist 20. Die Nutzung beträgt mehr als 80 % des Kontingents und eine Aktualisierung der Kontingenteinstellung kann initiiert werden.

   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. Rufen Sie zuerst ListQuotaPreferences auf, um zu prüfen, ob ausstehende Anfragen vorhanden sind, um doppelte Kontingenteinstellungen zu vermeiden. Das Flag reconciling=true ruft ausstehende Anfragen auf.

   GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true

   Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.
6. Rufen Sie UpdateQuotaPreference auf, um den Kontingentwert für die Region us-central1 zu erhöhen. Im folgenden Beispiel wurde ein neuer bevorzugter Wert von 100 angegeben.
   
   Das Feld allow_missing ist auf true gesetzt. Damit wird das System angewiesen, eine QuotaPreference-Ressource zu erstellen, in der keine mit dem angegebenen Namen vorhanden ist.

   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" }
   }

   So passen Sie die Dimensionen Ihrer Kontingenteinstellung an:

   • Wenn die Kontingenteinstellung für alle Regionen gelten soll, entfernen Sie die Regionsinformationen.
   • Wenn Ihr Kontingent pro Zone definiert ist, ersetzen Sie die Regionsinformationen durch die Zoneninformationen.
7. Rufen Sie GetQuotaPreference auf, um den Status der Änderung der Kontingenteinstellung zu prüfen:

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

   Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts. Während Google Cloud den angeforderten Kontingentwert auswertet, wird der Abgleichsstatus auf true gesetzt.

   "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"

   Nachdem die Kontingenteinstellung verarbeitet wurde, wird das Feld reconciling auf false gesetzt. grantedValue ist mit preferredValue identisch. Das bevorzugte Kontingent ist vollständig gewährt.
   
   Wenn Google Cloud eine Kundenanfrage ablehnt oder teilweise genehmigt, kann der zugewiesene Kontingentwert immer noch unter dem bevorzugten Wert liegen.

Kontingent verringern

Im folgenden Beispiel wird die Anzahl der TPUs in jeder Region auf 10 reduziert.

1. Rufen Sie die Kontingent-ID und den aktuellen Kontingentwert mit einem ListQuotaInfos-Aufruf ab:

   GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos

   Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.
2. Suchen Sie in den Antwortfeldern nach einem QuotaInfo-Eintrag für V2-TPUS-per-project-region.

   "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"
                   ]
               }
           ]
       },
       ...
   ]

   In dieser Antwort lautet die Kontingent-ID V2-TPUS-per-project-region und der aktuelle quotaValue ist 20.
3. Reduzieren Sie das TPU-Kontingent in jeder Region mit einem CreateQuotaPreferenceRequest auf 10. Legen Sie den Wert preferredValue auf 10 fest.

   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. Bestätigen Sie den neuen Kontingentwert mit einem GetQuotaInfo-Aufruf, der die Kontingent-ID als V2-TPUS-per-project-region definiert.

   GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region

   Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts. Das folgende Beispiel zeigt eine Antwort. value ist 10 und gilt in allen Regionen.

   "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"
           ]
       }
   ]

Kontingenteinstellungen in ein anderes Projekt kopieren

Im folgenden Beispiel werden alle Kontingenteinstellungen von einem Projekt in ein anderes kopiert.

1. Rufen Sie ListQuotaPreferences für das Quellprojekt ohne Filter auf:

   GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences

   PROJECT_NUMBER1 ist die Projektnummer für das Quellprojekt. Die Antwort enthält alle Kontingenteinstellungen für das Quellprojekt.
2. Rufen Sie für jede Kontingenteinstellung in der Antwort UpdateQuotaPreference auf und definieren Sie die folgenden Felder:
   • name: Das aktualisierte Feld "Name" stammt aus der Antwort und die Quellprojektnummer (PROJECT_NUMBER1) wird durch die Zielprojektnummer (PROJECT_NUMBER2) ersetzt.
   • service, quotaId, preferredValue, dimensions – Diese Felder können direkt aus der Antwort übernommen werden.

   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. Rufen Sie ListQuotaPreferences auf, um den Status der Kontingenteinstellungen für das Zielprojekt zu prüfen:

   GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences

   Ersetzen Sie PROJECT_NUMBER2 durch die Projektnummer Ihres Projekts.

Ausstehende Kontingentanfragen auflisten

Rufen Sie ListQuotaPreferences mit dem Filter reconciling=true auf, um alle ausstehenden Anfragen für Kontingenteinstellungen für ein Projekt aufzulisten.

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

Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.

Die Antwort auf diese Anfrage gibt die neueste ausstehende Kontingenteinstellung zurück. Da die Cloud Quotas API eine deklarative API ist, versucht das System, die aktuellste Kontingenteinstellung zu erfüllen.

Eine Beispielantwort sieht in etwa so aus:

  "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"
    }
  ]

Kontingenterhöhungen für Gruppen anfordern

Wenn Sie Erhöhungen für eine Gruppe von Kontingenten in einem neuen Projekt anfordern möchten, speichern Sie die bevorzugten Kontingente für das neue Projekt in einer CSV-Datei mit den folgenden Werten: Dienstname, Kontingent-ID, bevorzugter Kontingentwert, Dimensionen.

Lesen Sie für jede Zeile in der CSV-Datei den Inhalt in die Felder serviceName, quotaId, preferredValue und 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);

Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.

Da das Zielprojekt neu ist, kann beim Lesen und Zuweisen der Felder die Methode CreateQuotaPreference sicher aufgerufen werden. Alternativ können Sie die Methode UpdateQuotaPreference aufrufen, wobei allow_missing auf true gesetzt ist.

Die Methode buildYourOwnQuotaPreferenceId erstellt eine Kontingentpräferenz-ID aus dem Dienstnamen, der Kontingent-ID und einer Zuordnung von Dimensionen gemäß Ihrem Benennungsschema. Alternativ können Sie sich entscheiden, die Kontingent-ID nicht festzulegen. Eine ID für die Kontingenteinstellung wird für Sie generiert.

Anpassungen von Kontingenten ohne Nutzung anfordern

Kontingente, die noch nicht genutzt wurden und dienstspezifische Dimensionen wie vm_family haben, sind möglicherweise nicht in der Google Cloud Console zu sehen. Möglicherweise müssen Sie stattdessen die Cloud Quotas API verwenden.

Beispielsweise können Sie ein Projekt klonen und vorab wissen, dass Sie den Wert für compute.googleapis.com/gpus_per_gpu_family erhöhen müssen. Dieser Wert wird in der Google Cloud Console nur für GPU-Familien angezeigt, die Sie bereits verwendet haben. Wenn Sie mit der Cloud Quotas API eine Erhöhung der Anzahl der NVIDIA_H100-GPUs in us-central1 beantragen möchten, könnten Sie eine Anfrage wie die folgende senden:

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"
}

Ersetzen Sie Folgendes:

• PROJECT_NUMBER: Die eindeutige Kennung für Ihr Projekt.
• JUSTIFICATION: Der Grund für diese Anfrage.
• EMAIL: Eine E-Mail-Adresse, die als Kontakt verwendet werden kann, falls Google Cloud weitere Informationen benötigt, um eine Entscheidung zu treffen, bevor ein zusätzliches Kontingent gewährt werden kann.

Weitere Informationen finden Sie auch in den Beschreibungen zu Dimensionenvorrang und Dimensionen kombinieren.

Kontingentinformationen für eine dienstspezifische Dimension abrufen

Die GPU-Familie ist eine dienstspezifische Dimension. In der folgenden Beispielanfrage wird die Kontingent-ID GPUS-PER-GPU-FAMILY-per-project-region verwendet, um die Ressource QuotaInfo abzurufen.

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

Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.

Dies ist eine Beispielantwort. Für jeden eindeutigen gpu_family-Schlüssel unterscheiden sich quotaValue und 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"
        ]
    }
]

Kontingenteinstellung für eine dienstspezifische Dimension erstellen

Das folgende Beispiel zeigt, wie Sie ein Kontingent für eine bestimmte Region und GPU-Familie mit einem bevorzugten Wert von 100 erstellen. Der Zielspeicherort wird in der Zuordnung der Dimensionen mit dem Schlüssel region und die Ziel-GPU-Familie mit dem Schlüssel gpu_family angegeben.

Im folgenden CreateQuotaPreference-Beispiel wird eine GPU-Familie von NVIDIA_H100 und eine Region von us-central1 angegeben.

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"
}

Ersetzen Sie Folgendes:

• PROJECT_NUMBER: Die eindeutige Kennung für Ihr Projekt.
• EMAIL: Eine E-Mail-Adresse, die als Kontakt verwendet werden kann, falls Google Cloud weitere Informationen benötigt, um eine Entscheidung zu treffen, bevor ein zusätzliches Kontingent gewährt werden kann.

So passen Sie die Dimensionen Ihrer Kontingenteinstellung an:

• Wenn Sie eine QuotaPreference für NVIDIA_H100-GPUs für alle Regionen erstellen möchten, entfernen Sie die Zuordnung region aus der Dimensionszuordnung.
• Wenn Sie eine QuotaPreference für alle GPU-Familien in der Region us-central1 erstellen möchten, entfernen Sie die Zuordnung gpu_family aus der Dimensionszuordnung.

Kontingenteinstellung für eine dienstspezifische Dimension aktualisieren

Im folgenden Beispiel wird der aktuelle Wert für die Dimension {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, abgerufen und der bevorzugte Wert auf das Doppelte festgelegt.

// 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);

Ersetzen Sie PROJECT_NUMBER durch die eindeutige Kennung für Ihr Projekt.

Nächste Schritte

• Informationen zur Cloud Quotas API

• Referenz zur Cloud Quotas API

• Lernen Sie Kontingente kennen