Implementare casi d'uso comuni

Questa pagina descrive come implementare casi d'uso comuni utilizzando API Cloud Quotas. Questa API consente di regolare in modo programmatico quote e automatizzare un modello aggiustamenti delle quote nei progetti, nelle cartelle o nell'organizzazione di Google Cloud.

Per saperne di più, consulta l'API Cloud Quotas panoramica e riferimento.

Limitazioni

Cloud Quotas presenta le seguenti limitazioni:

  • Tutti gli aggiustamenti relativi all'aumento della quota sono soggetti all'approvazione di Google Cloud.

  • Puoi richiedere aggiustamenti di aumento e riduzione della quota per quote a livello di progetto.

  • Puoi richiedere aggiustamenti della riduzione della quota per project-, folder-, e a livello di organizzazione quotas.

Monitora l'utilizzo e richiedi un aumento quando l'utilizzo è superiore all'80%

Questo esempio monitora l'utilizzo della quota con Cloud Monitoring e quindi le richieste un aumento quando l'utilizzo è superiore all'80%.

  1. Chiama la risorsa QuotaInfo per il servizio per determinare quotaValue corrente. In questo esempio il servizio è compute.googleapis.com: 
    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
    Sostituisci PROJECT_NUMBER con il numero di progetto per il tuo progetto.
  2. Per trovare le CPU per progetto e le località applicabili, esamina la Risposta QuotaInfo per CPUS-per-project-region l'ID quota. Il valore quotaValue fa 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. Nel seguente Ad esempio, la regione us-central1 è stata specificata. Quota supportata 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 l'utilizzo, gestisci la risposta dell'API Cloud Monitoring. Confronta il valore di Cloud Monitoring al quotaValue in passaggi precedenti per determinare l'utilizzo.

    Nella risposta di esempio seguente il valore di utilizzo in Cloud Monitoring è 19 nella regione us-central1. quotaValue per tutte le regioni è 20. L'utilizzo è superiore all'80% della quota e una quota aggiornamento delle preferenze. 
    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 per la quota duplicate, chiama ListQuotaPreferences per controllare se ci sono richieste in attesa. reconciling=true segnalare 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 di progetto per il tuo progetto.
  6. Chiama UpdateQuotaPreference per aumentare il valore della quota per regione us-central1. Nell'esempio seguente, un nuovo valore preferito È stato specificato 100.

    Il campo allow_missing è impostato su true. Questo indica per creare una risorsa QuotaPreference dove non esiste 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" }
}
  7. Chiama GetQuotaPreference per controllare lo stato della quota modifica delle preferenze: 
    GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1
    Sostituisci PROJECT_NUMBER con il numero di progetto per il tuo progetto. Mentre Google Cloud valuta il valore di quota richiesto, lo stato della 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"
    Una volta elaborata la preferenza per la quota, reconciling è impostato su false. Il grantedValue è uguale a preferredValue. La quota preferita è stata concessa completamente.

    Quando Google Cloud rifiuta o approva parzialmente una richiesta di un cliente, il valore di quota concesso può essere comunque inferiore al valore preferito.

Diminuisci una quota

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

  1. Ottieni l'ID quota e il valore attuale della quota con un Chiamata ListQuotaInfos: 
    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
    Sostituisci PROJECT_NUMBER con il numero di progetto per il tuo 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 attuale 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",
    "contactEmail": EMAIL
}
  4. Conferma il nuovo valore di 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 di progetto per il tuo progetto. Di seguito è riportato un esempio di risposta: value è 10 e è 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"
        ]
    }
]

Copia le preferenze di quota in un altro progetto

L'esempio seguente copia tutte le preferenze di quota da un progetto all'altro.

  1. Chiama ListQuotaPreferences sul progetto di origine senza filtro: 
    GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
    PROJECT_NUMBER1 è il numero del progetto di origine. La la risposta contiene tutte le preferenze di quota per il progetto di origine.
  2. Per ogni preferenza di quota nella risposta, richiama UpdateQuotaPreference e definisci i seguenti campi:
    • name - Il campo del nome aggiornato viene recuperato dalla risposta, e il numero di progetto di origine (PROJECT_NUMBER1) viene sostituito numero progetto di destinazione (PROJECT_NUMBER2).
    • service, quotaId, preferredValue dimensions. Questi campi possono essere ricavati direttamente dalla risposta così com'è.
    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. Chiama ListQuotaPreferences per verificare lo stato della quota preferenze per il progetto di destinazione: 
    GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences
    Sostituisci PROJECT_NUMBER2 con il numero di progetto per il tuo progetto di destinazione.

Elenca le richieste di quota in attesa

Per elencare tutte le richieste di preferenze per la quota 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 di progetto per il tuo progetto.

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

Ecco un esempio di risposta:

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

Richiedi aumenti della quota del gruppo

Per richiedere aumenti per un gruppo di quote in un nuovo progetto, archivia il quote per il nuovo progetto in un file CSV con i seguenti valori: nome servizio, ID quota, valore quota preferita, dimensioni.

Per ogni riga del file CSV, leggi il contenuto 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)
            .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue))
            .putAllDimensions(dimensionMap))
  .build();
cloudQuotas.createQuotaPreference(request);

Sostituisci PROJECT_NUMBER con il numero di progetto per il tuo 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 crea un ID preferenza quota dal nome del servizio, dall'ID quota e da una mappa delle dimensioni secondo la tua denominazione . In alternativa, puoi scegliere di non impostare l'ID preferenza della quota. Una quota l'ID preferenza viene generato automaticamente.

Richiedi aggiustamenti delle quote senza utilizzo

Per le quote che non includono già l'utilizzo della quota e che hanno specifiche come vm_family, è possibile che quelle quote non saranno visibili nella console Google Cloud. Potresti dover utilizzare l'API Cloud Quotas.

Ad esempio, potresti clonare un progetto e sapere in anticipo che devi Aumenta il valore di compute.googleapis.com/gpus_per_gpu_family. Questo valore viene visualizzato solo nella console Google Cloud per le famiglie di GPU a tua disposizione sono già in uso. Utilizzare l'API Cloud Quotas per richiedere un aumento a GPU NVIDIA_H100 in us-central1, potresti inviare una richiesta come la seguente:

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
}

Sostituisci quanto segue:

  • PROJECT_NUMBER: l'identificatore univoco del progetto.
  • EMAIL: un indirizzo email che può essere utilizzato come contatto nel caso in cui Google Cloud abbia bisogno di maggiori informazioni per prendere una decisione prima di puoi concedere una quota aggiuntiva.

Per ulteriori informazioni, vedi anche le descrizioni Precedenza dimensioni e Combinazione di dimensioni.

Ricevere informazioni sulla quota per una dimensione specifica del servizio

La famiglia GPU è una dimensione specifica del servizio. La seguente richiesta di esempio utilizza ID quota GPUS-PER-GPU-FAMILY-per-project-region per recuperare 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 di progetto per il tuo progetto.

Questo è un esempio di risposta. Per ogni chiave gpu_family univoca, il valore quotaValue e applicableLocations è diverso:

"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 data regione Famiglia di GPU con un valore preferito 100. La località target è specificata nel mappa delle dimensioni con la chiave region e la famiglia GPU di destinazione con la chiave gpu_family.

Il seguente esempio di CreateQuotaPreference specifica una famiglia di GPU di NVIDIA_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"},
    "contactEmail": EMAIL"
}

Sostituisci quanto segue:

  • PROJECT_NUMBER: l'identificatore univoco del progetto.
  • EMAIL: un indirizzo email che può essere utilizzato come contatto nel caso in cui Google Cloud abbia bisogno di maggiori informazioni per prendere una decisione prima di puoi concedere 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 poi imposta il valore preferito doppio.

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

Sostituisci PROJECT_NUMBER con l'identificatore univoco di del progetto.

Passaggi successivi