Implementare casi d'uso comuni

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

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

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 le quote a livello di progetto.

  • Puoi richiedere aggiustamenti delle diminuzioni delle quote per le quote a livello di project-, folder- e organizzazione.

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

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

  1. Chiama la risorsa QuotaInfo per il tuo servizio per determinare il quotaValue attuale. 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 tuo 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 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"
                ]
            }
        ]
    },
      …
]
    Questo output include i seguenti valori:
    • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.
  3. Chiama l'API Cloud Monitoring per trovare l'utilizzo della quota. Nell'esempio seguente, la regione us-central1 è stata specificata. 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
    }
}
    Questo output include i seguenti valori:
    • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.
  4. Per determinare l'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 seguente, il valore di utilizzo in Cloud Monitoring è 19 nella regione us-central1. Il quotaValue per tutte le regioni è 20. L'utilizzo è superiore all'80% della quota ed è possibile avviare un aggiornamento della preferenza per la 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
    }
  }
}
    Questo output include i seguenti valori:
    • PROJECT_ID: un identificatore univoco globale per il progetto.
  5. Per evitare preferenze di quota duplicate, chiama prima ListQuotaPreferences per verificare se sono presenti richieste in attesa. reconciling=true segnala le chiamate 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 tuo progetto.
  6. Chiama UpdateQuotaPreference per aumentare il valore della quota per la regione us-central1. Nell'esempio seguente, è stato specificato un nuovo valore preferito pari a 100.

    Il campo allow_missing è impostato su true. Questo indica al sistema di creare una risorsa QuotaPreference se non esiste 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": [
    "mapField": {
    "key": "region",
    "value": "us-central1"
    }
    ],
    }
    Questo output include i seguenti valori:
    • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.
  7. Richiama GetQuotaPreference per verificare lo stato della modifica delle preferenze per le quote: 
    GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1
    Sostituisci PROJECT_NUMBER con il numero del progetto per il tuo progetto. Mentre Google Cloud valuta il valore di quota richiesto, 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": [
    "mapField": {
        "key": "region",
        "value": "us-central1"
    }
],
"reconciling": true
"createTime": "2023-01-15T01:30:15.01Z",
"updateTime": "2023-01-16T02:35:16.01Z"
    Questo output include i seguenti valori:
    • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.
    Una volta elaborata la preferenza di quota, il campo reconciling viene impostato su false. grantedValue è uguale al 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ò comunque essere inferiore al valore preferito.

Diminuisci una quota

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

  1. Recupera l'ID quota e il valore attuale della quota con una chiamata ListQuotaInfos: 
    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
    Sostituisci PROJECT_NUMBER con il numero del 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"
                ]
            }
        ]
    },
      …
]
    Questo output include i seguenti valori:
    • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.
    In questa risposta, l'ID quota è V2-TPUS-per-project-region e il valore quotaValue attuale è 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",
}
    Questo output include i seguenti valori:
    • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.
  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 del tuo 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"
        ]
    }
]
    Questo output include i seguenti valori:
    • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.

Copia le preferenze di quota in un altro progetto

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

  1. Richiama ListQuotaPreferences sul 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 di quota 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 recuperato 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ì 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())
        .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 di quota 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 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 del progetto.

La risposta a questa richiesta restituisce l'ultima preferenza di quota in attesa. Poiché l'API Cloud Quotas è un'API dichiarativa, l'ultima preferenza per la quota è quella che il sistema tenta 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": [
            "map_field": {
                "key": "region",
                "value": "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"
    }
]

Questo output include i seguenti valori:

  • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.

Richiedi aumenti della quota del gruppo

Per richiedere aumenti per un gruppo di quote in un nuovo progetto, archivia le quote preferite 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 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 crea un ID preferenza di quota utilizzando il nome del servizio, l'ID quota e una mappa delle dimensioni in base allo schema di denominazione. In alternativa, puoi scegliere di non impostare l'ID preferenza della quota. Viene generato automaticamente un ID preferenza di quota.

Ricevere 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 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 del progetto.

Questo è un esempio di risposta. Per ogni chiave gpu_family univoca, i valori di 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": [
            "mapField": {
                "key": "region",
                "value": "us-central1"
            },
            "mapField": {
                "key": "gpu_family",
                "value": "NVIDIA_H200"
            }
        ],
        "details": {
            "quotaValue": 30,
            "resetValue": 30,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": [
            "mapField": {
                "key": "region",
                "value": "us-central1"
            }
        ],
        "details": {
            "quotaValue": 100,
            "resetValue": 100,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": [
            "mapField": {
                "key": "gpu_familly",
                "value": "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"
        ]
    }
]

Questo output include i seguenti valori:

  • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.

Creare una preferenza di quota per una dimensione specifica del servizio

L'esempio seguente mostra come creare una quota per una determinata regione e famiglia di GPU con un valore preferito pari a 100. La posizione di destinazione viene specificata nella mappa delle dimensioni con la chiave region, mentre 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. Sostituisci PROJECT_NUMBER con il numero del tuo progetto.

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": [
        "mapField": {
            "key": "region",
            "value": "us-central1"
        }
          "mapField": {
            "key": "gpu_family",
            "value": "NVIDIA_H100"
        }
    ],
}

Aggiornare una preferenza di quota per una dimensione specifica del servizio

Il codice campione riportato di seguito recupera il valore corrente per le dimensioni {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, quindi imposta il valore preferito in modo che sia raddoppiato. Sostituisci PROJECT_NUMBER con il numero del tuo progetto.

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

Passaggi successivi