Implementare casi d'uso comuni

Questa pagina descrive come implementare casi d'uso comuni utilizzando l'API Cloud Quotas. Questa API ti consente di modificare in modo programmatico le quote e di automatizzare i modifiche alle quote nei tuoi progetti, nelle tue cartelle o nella tua organizzazione Google Cloud.

Per saperne di più, consulta la panoramica e la documentazione di riferimento dell'API Cloud Quotas.

Limitazioni

Le quote Cloud presentano le seguenti limitazioni:

  • Nella maggior parte dei casi, gli aggiustamenti per l'aumento della quota devono essere apportati a livello di progetto. Un numero limitato di prodotti supporta gli aggiustamenti dell'aumento della quota a livello di organizzazione. Per sapere se un prodotto Google Cloud supporta gli aggiustamenti dell'aumento della quota a livello di organizzazione, consulta la documentazione relativa al prodotto.

  • Puoi richiedere aggiustamenti di riduzione delle quote per le quote a livello di progetto, organizzazione e cartella.

  • L'API Cloud Quotas supporta solo le operazioni a livello di progetto. Le operazioni a livello di cartella e di organizzazione non sono supportate.

  • Nella console Google Cloud, la pagina Quote e limiti di sistema non supporta la selezione di regioni o zone per le richieste di aggiustamento delle quote dal pulsante Modifica. Per modificare le quote a livello regionale o zonale nella console Google Cloud, consulta le istruzioni su come richiedere una quota più alta.

Monitorare l'utilizzo e richiedere un aumento quando l'utilizzo supera l'80%

Questo esempio monitora l'utilizzo della quota con Cloud Monitoring e poi richiede un aumento quando l'utilizzo supera l'80%.

  1. Chiama la risorsa QuotaInfo per il tuo servizio per determinare il valore correntequotaValue. Il servizio in questo esempio è compute.googleapis.com:

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

    Sostituisci PROJECT_NUMBER con il numero del progetto.

  2. Per trovare le CPU per progetto e le località applicabili, cerca l'ID quota CPUS-per-project-region nella risposta QuotaInfo. Il valore 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. Chiama l'API Cloud Monitoring per trovare l'utilizzo della quota. Nell'esempio seguente è stata specificata la regione us-central1. Le metriche delle quote supportate sono elencate in 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"
  }
}

  4. Per determinare il tuo utilizzo, gestisci la risposta dell'API Cloud Monitoring. Confronta il valore di Cloud Monitoring con quotaValue nei passaggi precedenti per determinare l'utilizzo.

    Nell'esempio di risposta seguente, il valore di utilizzo in Cloud Monitoring è 19 nella regione us-central1. Il valore quotaValue per tutte le regioni è 20. L'utilizzo è superiore all'80% della quota ed è possibile avviare un aggiornamento delle preferenze relative alla quota.

    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. Per evitare preferenze di quota duplicate, chiama prima ListQuotaPreferences per verificare se ci sono richieste in attesa. Il flag reconciling=true richiama le richieste in attesa.

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

    Sostituisci PROJECT_NUMBER con il numero del progetto.

  6. Chiama UpdateQuotaPreference per aumentare il valore della quota per la regione us-central1. Nell'esempio seguente è stato specificato un nuovo valore preferito di 100.

    Il campo allow_missing è impostato su true. In questo modo, il sistema crea una risorsa QuotaPreference se non esiste alcuna risorsa con il nome fornito.

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

    Sostituisci quanto segue:

    • PROJECT_NUMBER: l'identificatore univoco del progetto.
    • JUSTIFICATION: una stringa facoltativa che spiega la tua richiesta.
    • EMAIL: un indirizzo email che può essere utilizzato come contatto, nel caso in cui Google Cloud abbia bisogno di ulteriori informazioni prima che possa essere concessa una quota aggiuntiva.

  7. Chiama GetQuotaPreference per controllare lo stato della modifica della preferenza di quota:

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

    Sostituisci PROJECT_NUMBER con il numero del progetto.

    Mentre Google Cloud valuta il valore della quota richiesta, lo stato di riconciliazione è impostato su 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"

    Dopo l'elaborazione della preferenza di quota, il campo reconciling viene impostato su false. grantedValue è uguale a preferredValue. La quota preferita è completamente concessa.

    Quando Google Cloud rifiuta o approva parzialmente una richiesta del cliente, il valore della quota concessa può comunque essere inferiore al valore preferito.

Diminuire una quota

L'esempio seguente riduce il numero di TPU a 10 in ogni regione.

  1. Ottieni l'ID quota e il valore della quota corrente con una chiamata ListQuotaInfos:

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

    Sostituisci PROJECT_NUMBER con il numero del progetto.

  2. Esamina i campi di risposta per trovare una voce QuotaInfo per 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 questa risposta, l'ID quota è V2-TPUS-per-project-region e il valore corrente di quotaValue è 20.

  3. Riduci la quota TPU in ogni regione a 10 con un CreateQuotaPreferenceRequest. Imposta preferredValue su 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"
}

    Sostituisci quanto segue:

    • PROJECT_NUMBER: l'identificatore univoco del progetto.
    • JUSTIFICATION: una stringa facoltativa che spiega la tua richiesta.
    • EMAIL: un indirizzo email che può essere utilizzato come contatto, nel caso in cui Google Cloud abbia bisogno di ulteriori informazioni prima che possa essere concessa una quota aggiuntiva.

  4. Conferma il nuovo valore della quota con una chiamata GetQuotaInfo che definisce l'ID quota come V2-TPUS-per-project-region.

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

    Sostituisci PROJECT_NUMBER con il numero del progetto.

    Di seguito è riportato un esempio di risposta. value è 10 ed è applicabile in tutte le regioni.

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

Copiare le preferenze relative alle quote in un altro progetto

L'esempio seguente copia tutte le preferenze relative alle quote da un progetto all'altro. È scritto in Java, ma puoi utilizzare qualsiasi linguaggio di programmazione.

  1. Chiama ListQuotaPreferences nel progetto di origine senza filtro:

    GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences

    PROJECT_NUMBER1 è il numero del progetto di origine. La risposta contiene tutte le preferenze relative alle quote per il progetto di origine.

  2. Per ogni preferenza di quota nella risposta, chiama UpdateQuotaPreference e definisci i seguenti campi:

    • name: il campo del nome aggiornato viene preso dalla risposta e il numero del progetto di origine (PROJECT_NUMBER1) viene sostituito con il numero del progetto di destinazione (PROJECT_NUMBER2).

    • service, quotaId, preferredValue, dimensions: questi campi possono essere ripresi direttamente dalla risposta così come sono.

    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. Chiama ListQuotaPreferences per verificare lo stato delle preferenze relative alle quote per il progetto di destinazione:

    GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences

    Sostituisci PROJECT_NUMBER2 con il numero del progetto di destinazione.

Elenca le richieste di quote in attesa

Per elencare tutte le richieste di preferenze relative alle quote in attesa per un progetto, chiama ListQuotaPreferences con il filtro reconciling=true.

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

Sostituisci PROJECT_NUMBER con il numero del progetto.

La risposta a questa richiesta restituisce l'ultima preferenza per la quota in attesa. Poiché l'API Cloud Quotas è un'API dichiarativa, il sistema tenta di soddisfare la preferenza di quota più recente.

Un esempio di risposta è simile al seguente:

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

Richiedere aumenti di quota del gruppo

Per richiedere aumenti per un gruppo di quote in un nuovo progetto, memorizza le quote preferite per il nuovo progetto in un file CSV con i seguenti valori: nome del servizio, ID quota, valore quota preferito, dimensioni.

Per ogni riga del file CSV, leggi i contenuti nei campi serviceName, quotaId, preferredValue e 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);

Sostituisci PROJECT_NUMBER con il numero del progetto.

Poiché il progetto di destinazione è nuovo, è sicuro chiamare il metodo CreateQuotaPreference durante la lettura e l'assegnazione dei campi. In alternativa, puoi chiamare il metodo UpdateQuotaPreference con allow_missing impostato su true.

Il metodo buildYourOwnQuotaPreferenceId genera un ID preferenza quota dal nome del servizio, dall'ID quota e da una mappa di dimensioni in base allo schema di denominazione. In alternativa, puoi scegliere di non impostare l'ID preferenza quota. Viene generato un ID preferenza quota per te.

Richiedere aggiustamenti alle quote che non vengono utilizzate

Le richieste di variazione della quota seguono la stessa procedura, indipendentemente dal fatto che la quota che stai modificando sia in uso o meno. Per scoprire come richiedere un aggiustamento dell'aumento della quota, consulta Richiedere un valore di quota più elevato. Per richiedere un valore di quota inferiore, segui le istruzioni per richiedere un valore di quota superiore, ma specifica il valore inferiore che preferisci quando inserisci il valore della richiesta.

Ottenere informazioni sulla quota per una dimensione specifica del servizio

La famiglia GPU è una dimensione specifica del servizio. La seguente richiesta di esempio utilizza l'ID quota GPUS-PER-GPU-FAMILY-per-project-region per ottenere la risorsa QuotaInfo.

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

Sostituisci PROJECT_NUMBER con il numero del progetto.

Questo è un esempio di risposta. Per ogni chiave gpu_family univoca, quotaValue e applicableLocations sono diversi:

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

Creare una preferenza di quota per una dimensione specifica del servizio

L'esempio seguente mostra come creare una quota per una determinata regione e una famiglia di GPU con un valore preferito di 100. La posizione target è specificata nella mappa delle dimensioni con la chiave region e la famiglia di GPU target con la chiave gpu_family.

L'esempio seguente di CreateQuotaPreference specifica una famiglia di GPU diNVIDIA_H100 e una regione di 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"
}

Sostituisci quanto segue:

  • PROJECT_NUMBER: l'identificatore univoco del progetto.
  • JUSTIFICATION: una stringa facoltativa che spiega la richiesta.
  • EMAIL: un indirizzo email che può essere utilizzato come contatto, nel caso in cui Google Cloud abbia bisogno di ulteriori informazioni prima che possa essere concessa una quota aggiuntiva.

Aggiornare una preferenza di quota per una dimensione specifica del servizio

Il seguente codice campione recupera il valore corrente per la dimensione {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, e imposta il valore preferito sul doppio del valore. È scritto in Java, ma puoi utilizzare qualsiasi linguaggio di programmazione.

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

Sostituisci PROJECT_NUMBER con l'identificatore univoco del tuo progetto.

Passaggi successivi