Implementare casi d'uso comuni

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

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

Limitazioni

Cloud Quotas presenta le seguenti limitazioni:

  • Gli aggiustamenti per l'aumento della quota devono essere apportati a livello di progetto e sono soggetti all'approvazione di Google Cloud.

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

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

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 del 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 è 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 il tuo 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 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. 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 del progetto.
  6. Chiama UpdateQuotaPreference per aumentare il valore della quota per la 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 il numero GetQuotaPreference per controllare lo stato della modifica della preferenza relativa al limite: 
    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 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 di un cliente, il valore di quota concesso può essere comunque 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 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 quotaValue corrente è 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"
        ]
    }
]

Copiare le preferenze relative alle quote in un altro progetto

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

  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 presi 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 delle preferenze per le quote 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 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 la preferenza di quota. Poiché l'API Cloud Quotas è un'API dichiarativa, il l'ultima preferenza relativa alla quota è quella che il sistema cerca di soddisfare.

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

Richiedi aumenti della 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)
            .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 al tuo schema di denominazione. In alternativa, puoi scegliere di non impostare l'ID preferenza 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 limitazioni 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 nella console Google Cloud solo per le famiglie di GPU che hai già utilizzato. 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" },
    "justification": "JUSTIFICATION",
    "contactEmail": "EMAIL"
}

Sostituisci quanto segue:

  • PROJECT_NUMBER: l'identificatore univoco del progetto.
  • JUSTIFICATION: il motivo della richiesta.
  • 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, consulta anche le descrizioni di Precedenza delle dimensioni e Combinazione di dimensioni.

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, 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 determinata regione e una famiglia di GPU con un valore preferito di 100. La località target è specificata nel mappa delle dimensioni con la chiave region e la famiglia GPU di destinazione 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"},
    "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 di esempio recupera il valore corrente della dimensione{"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, e imposta il valore preferito sul 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