Gestire le quote utilizzando l'interfaccia a riga di comando gcloud beta

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Le sezioni seguenti contengono esempio gcloud beta quotas info e gcloud beta quotas preferences comandi. Questi comandi consentono di visualizzare e gestire le risorse QuotaInfo e QuotaPreference.

Puoi utilizzare Google Cloud CLI (gcloud CLI) per ottenere i valori delle quote attuali e specificare le preferenze di quota per alcuni servizi e alcune API Google Cloud e.

Limitazioni

Quote Cloud presenta le seguenti limitazioni:

• Nella maggior parte dei casi, le modifiche di aumento della quota devono essere apportate a livello di progetto. Un numero limitato di prodotti supporta le modifiche di aumento della quota a livello di organizzazione. Per verificare se un Google Cloud prodotto supporta le modifiche di aumento della quota a livello di organizzazione, consulta la documentazione del prodotto.

• Puoi richiedere modifiche di diminuzione della quota per le quote a livello di progetto, organizzazione e cartella.

Prima di iniziare

Prima di utilizzare gcloud CLI, assicurati di installarlo e inizializzarlo.

Potresti anche aver bisogno del valore QUOTA_ID. In questo caso, consulta le istruzioni per trovare l'ID quota.

Installare e inizializzare gcloud CLI

Per utilizzare gcloud CLI per Quote Cloud, assicurati di installare e inizializzare i componenti:

1. Installa gcloud CLI.

   Se utilizzi Cloud Shell, puoi saltare questo passaggio perché gcloud CLI è preinstallato.

2. Inizializza gcloud CLI.

3. Installa il componente beta eseguendo il seguente comando:

   gcloud components install beta
   

Trovare l'ID quota

Diversi comandi gcloud CLI in questo documento fanno riferimento al valore dell'ID quota. Puoi trovare l'ID quota utilizzando la Google Cloud console, gcloud CLI, le librerie client o l'API REST. Questa sezione mostra come trovare l'ID quota utilizzando la Google Cloud console o gcloud CLI.

Console

1. Nella console Google Cloud , vai alla pagina IAM e amministrazione > Quote e limiti di sistema:

   Vai a Quote e Limiti di sistema

2. Fai clic su filter_listFiltra per filtrare il servizio.

3. Se non vedi la colonna Nome limite, fai clic sull'icona Opzioni di visualizzazione delle colonne.... Seleziona Nome limite e fai clic su Ok.

4. La colonna Nome limite mostra l'ID quota.

gcloud

Per trovare il valore dell'ID quota utilizzando gcloud CLI, esegui il seguente comando per elencare le informazioni sulla quota per il servizio specificato:

1. Inserisci il seguente comando gcloud CLI in una finestra del terminale:

   gcloud beta quotas info list --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \
   --billing-project=BILLING_PROJECT_ID_OR_NUMBER
   

   Sostituisci quanto segue:

   • SERVICE_NAME: il nome del servizio con le quote che vuoi visualizzare, ad esempio il nome del servizio per Compute Engine è compute.googleapis.com.

   • PROJECT_ID_OR_NUMBER: l'ID progetto o il numero di progetto.

     Per trovare l'ID progetto utilizzando la Google Cloud console, vai alla pagina Resource Manager:

     Vai a Resource Manager

   • BILLING_PROJECT_ID_OR_NUMBER: l'ID o il numero di progetto del progetto la cui quota dell'API Cloud Quotas vuoi utilizzare per eseguire questo comando. Può essere diverso dal progetto contenente il servizio per cui stai cercando l'ID quota.

     Se hai già impostato il progetto di fatturazione durante la configurazione di gcloud CLI, questo flag è facoltativo. In caso contrario, se lo ometti potresti ricevere un errore di autorizzazione negata. Per saperne di più, consulta Impostare il progetto di quota.

2. L'output del comando gcloud beta quotas info list contiene testo simile al seguente esempio:

   ...
   "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": [
               {
                   "details": {
                       "value": 20
                   },
                   "applicableLocations": [
                       "us-central1",
                       "us-central2",
                       "us-west1",
                       "us-east1"
                   ]
                   ...
               }
           ]
       },
       ...
   ]
   ...

3. Cerca il valore corrispondente a quotaId e utilizzalo quando specifichi QUOTA_ID nelle sezioni seguenti.

Esempi di comandi gcloud per le informazioni sulla quota

Questa sezione fornisce esempi che mostrano come utilizzare i comandi gcloud beta quotas info per visualizzare le informazioni sulla quota per un determinato servizio o per un'organizzazione.

QuotaInfo è una risorsa di sola lettura che fornisce metadati e informazioni sul valore della quota per una determinata quota per un determinato progetto, cartella o organizzazione.

Visualizzare le informazioni sulla quota per un determinato servizio

Per visualizzare le informazioni sulla quota per un determinato servizio, esegui il seguente comando:

gcloud beta quotas info describe QUOTA_ID --service=SERVICE_NAME \
    --project=PROJECT_ID_OR_NUMBER --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Sostituisci quanto segue:

• QUOTA_ID: il valore dell'ID quota. Per trovare questo valore, consulta Trovare l'ID quota.
• SERVICE_NAME: il nome del servizio con le quote che vuoi visualizzare, ad esempio il nome del servizio per Compute Engine è compute.googleapis.com.
• PROJECT_ID_OR_NUMBER: l'ID progetto o il numero di progetto.

• BILLING_PROJECT_ID_OR_NUMBER: l'ID o il numero di progetto del progetto la cui quota dell'API Cloud Quotas vuoi utilizzare per eseguire questo comando. Può essere diverso dal progetto contenente il servizio per cui stai visualizzando le informazioni sulla quota.

  Se hai già impostato il progetto di fatturazione durante la configurazione di gcloud CLI, questo flag è facoltativo. In caso contrario, se lo ometti potresti ricevere un errore di autorizzazione negata. Per saperne di più, consulta Impostare il progetto di quota.

Visualizzare le informazioni sulla quota per un'organizzazione

Per visualizzare i dettagli della quota dello stesso servizio per un'organizzazione, esegui il seguente comando:

gcloud beta quotas info list --service=SERVICE_NAME --organization=ORGANIZATION_ID \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Sostituisci quanto segue:

• SERVICE_NAME: il nome del servizio con le quote che vuoi visualizzare, ad esempio il nome del servizio per Compute Engine è compute.googleapis.com.
• ORGANIZATION_ID: l'ID della tua organizzazione.

• BILLING_PROJECT_ID_OR_NUMBER: l'ID o il numero di progetto del progetto la cui quota dell'API Cloud Quotas vuoi utilizzare per eseguire questo comando. Può essere diverso dal progetto contenente il servizio per cui stai visualizzando le informazioni sulla quota.

  Se hai già impostato il progetto di fatturazione durante la configurazione di gcloud CLI, questo flag è facoltativo. In caso contrario, se lo ometti potresti ricevere un errore di autorizzazione negata. Per saperne di più, consulta Impostare il progetto di quota.

Esempi di comandi gcloud per le preferenze di quota

Questa sezione fornisce esempi che mostrano come utilizzare i comandi gcloud beta quotas preferences per controllare le preferenze di quota esistenti e modificare il valore della quota.

La risorsa QuotaPreference rappresenta la tua preferenza per una determinata combinazione di dimensioni. Una dimensione è un attributo che rappresenta una regione o una zona oppure una dimensione specifica del servizio, ad esempio gpu_family o network_id.

Verificare la presenza di preferenze esistenti

Per verificare la presenza di preferenze esistenti, esegui il seguente comando:

gcloud beta quotas preferences list --project=PROJECT_ID_OR_NUMBER \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Sostituisci quanto segue:

• PROJECT_ID_OR_NUMBER : l'ID progetto o il numero di progetto.

• BILLING_PROJECT_ID_OR_NUMBER: l'ID o il numero di progetto del progetto la cui quota dell'API Cloud Quotas vuoi utilizzare per eseguire questo comando. Può essere diverso dal progetto contenente il servizio per cui stai verificando le preferenze di quota.

  Se hai già impostato il progetto di fatturazione durante la configurazione di gcloud CLI, questo flag è facoltativo. In caso contrario, se lo ometti potresti ricevere un errore di autorizzazione negata. Per saperne di più, consulta Impostare il progetto di quota.

Verificare la presenza di preferenze esistenti con modifiche della quota in attesa

Per verificare la presenza di preferenze esistenti con modifiche della quota in attesa, aggiungi il flag --reconciling-only=true come mostrato nel seguente comando:

gcloud beta quotas preferences list --project=PROJECT_ID_OR_NUMBER --reconciling-only=true \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Sostituisci quanto segue:

• PROJECT_ID_OR_NUMBER : l'ID progetto o il numero di progetto.

• BILLING_PROJECT_ID_OR_NUMBER: l'ID o il numero di progetto del progetto la cui quota dell'API Cloud Quotas vuoi utilizzare per eseguire questo comando. Può essere diverso dal progetto contenente il servizio per cui stai verificando le preferenze di quota.

  Se hai già impostato il progetto di fatturazione durante la configurazione di gcloud CLI, questo flag è facoltativo. In caso contrario, se lo ometti potresti ricevere un errore di autorizzazione negata. Per saperne di più, consulta Impostare il progetto di quota.

Richiedere una modifica di aumento della quota quando non è ancora stata impostata una preferenza di quota

Per richiedere una modifica della quota utilizzando gcloud CLI, esegui il seguente comando:

gcloud beta quotas preferences create --project=PROJECT_ID_OR_NUMBER \
    --service=SERVICE_NAME \
    --quota-id=QUOTA_ID \
    --dimensions=DIMENSIONS \
    --preferred-value=PREFERRED_VALUE \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER \
    --email=EMAIL \
    --justification=JUSTIFICATION \
    --preference-id=PREFERENCE_ID

Sostituisci quanto segue:

• PROJECT_ID_OR_NUMBER: l'ID progetto o il numero di progetto.
• SERVICE_NAME: il nome del servizio con le quote che vuoi modificare, ad esempio il nome del servizio per Compute Engine è compute.googleapis.com.
• QUOTA_ID: il valore dell'ID quota. Per trovare questo valore, consulta Trovare l'ID quota.
• DIMENSIONS: le dimensioni da modificare, specificate come un elenco separato da virgole di coppie chiave-valore, ad esempio region=us-east4,gpu_family=NVIDIA_H100. Per saperne di più sulle dimensioni della quota, consulta Configurare le dimensioni di Quote Cloud.
• PREFERRED_VALUE: il valore della quota preferito.
• BILLING_PROJECT_ID_OR_NUMBER: l'ID o il numero di progetto del progetto la cui quota dell'API Cloud Quotas vuoi utilizzare per eseguire questo comando. Può essere diverso dal progetto contenente il servizio per cui stai richiedendo una modifica della quota.

  Se hai già impostato il progetto di fatturazione durante la configurazione di gcloud CLI, questo flag è facoltativo. In caso contrario, se lo ometti potresti ricevere un errore di autorizzazione negata. Per saperne di più, consulta Impostare il progetto di quota.

• EMAIL: un indirizzo email che può essere utilizzato come contatto, nel caso Google Cloud in cui siano necessarie ulteriori informazioni prima di poter concedere una quota aggiuntiva.
• JUSTIFICATION: una stringa facoltativa che spiega la tua richiesta.
• PREFERENCE_ID: un ID preferenza facoltativo; se non specifichi un ID preferenza, l'API genera un UUID (Universally Unique Identifier) per te.

L'output è simile al seguente:

{
    "createTime":"CREATE_TIME",
    "dimensions":{
        "DIMENSION_KEY_1":"DIMENSION_VALUE_1",
        "DIMENSION_KEY_2":"DIMENSION_VALUE_2"
    },
    "etag":"ETAG_VALUE",
    "name":"projects/PROJECT_ID_OR_NUMBER/locations/global/quotaPreferences/PREFERENCE_ID",
    "quotaConfig":{
        "grantedValue":"GRANTED_VALUE",
        "preferredValue":"PREFERRED_VALUE",
        "traceId":"TRACE_ID"
    },
    "quotaId":"QUOTA_ID",
    "reconciling":true,
    "service":"SERVICE_NAME",
    "updateTime":"UPDATE_TIME",
}

Richiedere una modifica di aumento della quota quando è stata impostata una preferenza di quota

Per richiedere una modifica di aumento della quota per una regione specifica e se esiste già una preferenza, esegui il seguente comando:

gcloud beta quotas preferences update PREFERENCE_ID --preferred-value=PREFERRED_VALUE \
    --quota-id=QUOTA_ID --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER --email=EMAIL  \
    --justification=JUSTIFICATION

Sostituisci quanto segue:

• PREFERENCE_ID: l'ID preferenza, che è obbligatorio come primo argomento quando si utilizza il comando gcloud beta quotas preferences update.
• PREFERRED_VALUE: il valore della quota preferito.
• QUOTA_ID: il valore dell'ID quota. Per trovare questo valore, consulta Trovare l'ID quota.
• SERVICE_NAME: il nome del servizio con le quote che vuoi visualizzare, ad esempio il nome del servizio per Compute Engine è compute.googleapis.com.
• PROJECT_ID_OR_NUMBER: l'ID progetto o il numero di progetto.

• BILLING_PROJECT_ID_OR_NUMBER: l'ID o il numero di progetto del progetto la cui quota dell'API Cloud Quotas vuoi utilizzare per eseguire questo comando. Può essere diverso dal progetto contenente il servizio per cui stai richiedendo una modifica della quota.

  Se hai già impostato il progetto di fatturazione durante la configurazione di gcloud CLI, questo flag è facoltativo. In caso contrario, se lo ometti potresti ricevere un errore di autorizzazione negata. Per saperne di più, consulta Impostare il progetto di quota.

• EMAIL: un indirizzo email che può essere utilizzato come contatto, nel caso Google Cloud in cui siano necessarie ulteriori informazioni prima di poter concedere una quota aggiuntiva.

• JUSTIFICATION: una stringa facoltativa che spiega la tua richiesta.

Visualizzare una preferenza di quota esistente

Per visualizzare i dettagli della preferenza di quota appena creata, esegui il seguente comando:

gcloud beta quotas preferences describe PREFERENCE_ID \
    --project=PROJECT_ID_OR_NUMBER \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Sostituisci quanto segue:

• PREFERENCE_ID: l'ID preferenza, che è obbligatorio come primo argomento quando si utilizza il comando gcloud beta quotas preferences describe.
• PROJECT_ID_OR_NUMBER: l'ID progetto o il numero di progetto.

• BILLING_PROJECT_ID_OR_NUMBER: l'ID o il numero di progetto del progetto la cui quota dell'API Cloud Quotas vuoi utilizzare per eseguire questo comando. Può essere diverso dal progetto contenente il servizio per cui stai visualizzando la preferenza di quota.

  Se hai già impostato il progetto di fatturazione durante la configurazione di gcloud CLI, questo flag è facoltativo. In caso contrario, se lo ometti potresti ricevere un errore di autorizzazione negata. Per saperne di più, consulta Impostare il progetto di quota.

L'output conterrà dati specifici per la tua configurazione e sarà simile al seguente output di esempio:

createTime: 'CREATE_TIME'
dimensions:
  gpu_family: NVIDIA_H100
  region: us-east4
etag: ETAG_VALUE
name: projects/12345/locations/global/quotaPreferences/PREFERENCE_ID
quotaConfig:
  grantedValue: '0'
  preferredValue: '128'
  traceId: TRACE_ID
quotaId: GPUS-PER-GPU-FAMILY-per-project-region
reconciling: true
service: compute.googleapis.com
updateTime: 'UPDATE_TIME'

Abilitare l'aggiustamento delle quote tramite un progetto client

Un progetto client si riferisce al progetto utilizzato da un'applicazione o da un utente per accedere e interagire con Google Cloud le risorse, mentre un progetto di risorse è il progetto sottostante in cui le risorse vengono archiviate e gestite.

Per abilitare l'aggiustamento delle quote tramite un progetto client utilizzando gcloud CLI:

1. Crea un progetto client:

   gcloud projects create CLIENT_PROJECT_ID
   gcloud config set project CLIENT_PROJECT_ID
   

   Sostituisci CLIENT_PROJECT_ID con l'ID del progetto che vuoi creare. Gli ID progetto sono immutabili e possono essere impostati solo durante la creazione del progetto. Devono iniziare con una lettera minuscola e possono contenere lettere ASCII minuscole, cifre o trattini. Gli ID progetto devono essere compresi tra 6 e 30 caratteri.

2. Abilita l'API Cloud Quotas nel progetto client:

   gcloud services enable cloudquotas.googleapis.com
   

3. Crea un service account nel progetto client:

   gcloud iam service-accounts create SA_NAME \
     --display-name SA_DISPLAY_NAME \
     --project=CLIENT_PROJECT_ID
   

   Sostituisci quanto segue:

   • SA_NAME: il nome interno del nuovo account di servizio. Utilizzato per generare un IAM_ACCOUNT (un indirizzo email interno IAM utilizzato come identificatore del account di servizio), che deve essere passato ai comandi successivi.
   • SA_DISPLAY_NAME: il nome visualizzato del account di servizio.
   • CLIENT_PROJECT_ID: l'ID del progetto client.

4. Crea una chiave dell'account di servizio:

   gcloud iam service-accounts keys create KEY_FILE \
     --iam-account=SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com
   

   Sostituisci quanto segue:

   • KEY_FILE: il percorso del file JSON della chiave dell'account di servizio.
   • SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com: l'indirizzo email del account di servizio.

5. Concedi le autorizzazioni IAM al account di servizio:

   gcloud projects add-iam-policy-binding CLIENT_PROJECT_ID \
     --member="serviceAccount:SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/serviceusage.serviceUsageConsumer"
   
   gcloud projects add-iam-policy-binding RESOURCE_PROJECT_ID \
     --member="serviceAccount:SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/cloudquotas.admin"
   

   Sostituisci quanto segue:

   • CLIENT_PROJECT_ID: l'ID del progetto client.
   • RESOURCE_PROJECT_ID: l'ID del progetto di risorse.
   • SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com: l'indirizzo email del account di servizio.

6. Attiva il account di servizio utilizzando la chiave del account di servizio che hai creato in precedenza:

   gcloud auth activate-service-account --key-file=KEY_FILE
   

7. Abilita l'aggiustamento delle quote nel progetto di risorse specificando il progetto e l'impostazione di abilitazione:

   gcloud beta quotas adjuster settings update --project=RESOURCE_PROJECT_ID \
     --enablement=enabled
   

   L'impostazione di abilitazione è obbligatoria quando si utilizza gcloud CLI e deve essere impostata su enabled o disabled.

8. (Facoltativo) Per visualizzare le impostazioni correnti dell'aggiustamento delle quote, esegui il seguente comando:

   gcloud beta quotas adjuster settings describe --project=RESOURCE_PROJECT_ID 
   

   L'output è simile al seguente:

   enablement: ENABLED
   etag: 8izmJp6EI__mOfLyhkQU9
   name: projects/RESOURCE_PROJECT_ID/locations/global/quotaAdjusterSettings
   updateTime: '2025-01-10T17:22:37.883221181Z'
   

Per abilitare l'aggiustamento delle quote per più progetti client, segui i passaggi da 5 a 8 precedenti. Quando esegui questa operazione, assicurati che siano soddisfatte le seguenti condizioni:

• L'API Cloud Quotas è abilitata nel progetto client.
• Il account di servizio ha il ruolo IAM cloudquotas.admin in tutti i progetti di risorse in cui vuoi abilitare l'aggiustamento delle quote.

Altri servizi con comandi gcloud CLI relativi alle quote

Oltre a gcloud beta quotas, alcuni servizi hanno un proprio accesso da riga di comando alle informazioni su quota e utilizzo delle risorse.

Ad esempio, Compute Engine consente di accedere alle informazioni sulla quota. Per maggiori dettagli, consulta le seguenti sezioni di Compute Engine:

• quote di allocazione
• La panoramica di gcloud CLI compute
• Sezione gcloud CLI compute del riferimento di Google Cloud SDK

Passaggi successivi

• Per risolvere i problemi relativi ai com0andi gcloud beta quotas, consulta Risolvere i problemi relativi agli errori di gcloud CLI.

• Per informazioni dettagliate sui comandi e sui flag gcloud beta quotas, consulta la sezione del riferimento di Google Cloud CLI.

• Per saperne di più sulla terminologia delle quote, consulta Comprendere la terminologia relativa a quote e limiti di sistema.