Conferir e gerenciar cotas usando a CLI gcloud alpha

As seções a seguir contêm exemplos de comandos gcloud alpha quotas info e gcloud alpha quotas preferences. Esses comandos permitem que você visualize e gerencie recursos QuotaInfo e QuotaPreference.

É possível usar a CLI do Google Cloud (CLI gcloud) para receber os valores de cotas atuais e especificar preferências de cota para algumas APIs e serviços do Google Cloud.

Limitações

As cotas do Cloud têm as seguintes limitações:

Os ajustes de aumento de cota precisam ser feitos no nível do projeto e estão sujeitos à aprovação do Google Cloud.
É possível solicitar ajustes de diminuição de cota para project-, folder- e as cotas no nível da organização.
A API Cloud Quotas é compatível apenas com operações no nível do projeto. Operações em nível de pasta e organização não são compatíveis.

Antes de começar

Antes de começar, instale e inicialize a CLI gcloud.

Talvez também seja necessário usar o valor QUOTA_ID. Se esse for o caso, consulte as instruções para encontrar o ID da cota.

Instale e inicialize a CLI gcloud

Para usar a CLI gcloud, verifique se você tem instalado e inicializado a versão mais recente da CLI gcloud, incluindo componentes de comandos alfa. Se você estiver usando o Cloud Shell para interagir com o Google Cloud, a CLI do Google Cloud será instalada.

Encontrar o ID da cota

Vários comandos da gcloud CLI nesta página fazem referência ao valor do ID da cota. É possível encontrar o ID de cota usando o console do Google Cloud, a gcloud CLI, as bibliotecas de cliente ou a API REST. Esta seção mostra como encontrar o ID de cota usando o console do Google Cloud ou a gcloud CLI.

Console

Acesse a página Cotas e limites do sistema:
Acesse "Cotas e limites do sistema
Clique em Filtrar para filtrar seu serviço.
Se a coluna Nome do limite não aparecer, clique no ícone Opções de exibição de coluna. Selecione Nome do limite e clique em OK.
A coluna Nome do limite mostra o ID da cota.

gcloud

Para encontrar o valor do ID de cota usando a gcloud CLI, execute o comando a seguir para listar as informações de cota do serviço especificado:

Digite o seguinte comando da CLI gcloud em uma janela de terminal:
```
gcloud alpha quotas info list --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \
--billing-project=BILLING_PROJECT_ID_OR_NUMBER
```
Substitua:
- SERVICE_NAME: o nome do serviço com cotas que você quer ver. Por exemplo, o nome do serviço do Compute Engine é compute.googleapis.com.
- PROJECT_ID_OR_NUMBER: o ID ou o número do projeto
  
  Para encontrar o ID do projeto usando o console do Google Cloud, navegue até a página do Resource Manager:
  Acesse o Resource Manager
- BILLING_PROJECT_ID_OR_NUMBER: o ID ou o número do projeto para uso de cota e faturamento. Executar um comando gcloud afeta a cota como se você tivesse feito a solicitação equivalente diretamente por uma API REST ou RPC.
  
  Especifique o projeto cuja cota você quer usar. Ele pode ser diferente do projeto que contém o serviço para o qual você está encontrando o ID de cota.
  
  Se você já configurou o projeto de faturamento ao configurar a gcloud CLI, essa flag é opcional. Caso contrário, a omissão pode causar um erro de permissão negada. Para mais informações, consulte Defina o projeto de cota.

A saída do comando gcloud alpha quotas info list contém um texto semelhante ao seguinte exemplo:

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

Procure o valor que corresponde a quotaId e use-o ao especificar QUOTA_ID nas próximas seções.

Exemplo de comandos de informações de cota da gcloud

Esta seção fornece exemplos que mostram como usar os comandos gcloud alpha quotas info para visualizar informações de cota para um serviço específico ou para uma organização.

QuotaInfo é um recurso somente leitura que fornece informações de metadados e valores de cota sobre uma cota específica para um determinado projeto, pasta ou organização.

Visualizar informações de cota para um serviço específico

Para visualizar informações de cota de um serviço específico, execute o seguinte comando:

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

Substitua:

QUOTA_ID: o valor do ID da cota. Para encontrar esse valor, consulte Encontrar o ID da cota.
SERVICE_NAME: o nome do serviço com cotas que você quer ver. Por exemplo, o nome do serviço do Compute Engine é compute.googleapis.com.
PROJECT_ID_OR_NUMBER: o ID ou o número do projeto
BILLING_PROJECT_ID_OR_NUMBER: o ID ou o número do projeto para uso de cota e faturamento. Executar um comando gcloud afeta a cota como se você tivesse feito a solicitação equivalente diretamente por uma API REST ou RPC.

Especifique o projeto cuja cota você quer usar. Ele pode ser diferente do projeto que contém o serviço para o qual você está visualizando as informações de cota.

Se você já configurou o projeto de faturamento ao configurar a gcloud CLI, essa flag é opcional. Caso contrário, a omissão pode causar um erro de permissão negada. Para mais informações, consulte Defina o projeto de cota.

Visualizar informações de cota de uma organização

Para visualizar os mesmos detalhes de cota do serviço para uma organização, execute o seguinte comando:

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

Substitua:

SERVICE_NAME: o nome do serviço com cotas que você quer ver. Por exemplo, o nome do serviço do Compute Engine é compute.googleapis.com.
ORGANIZATION_ID: o ID da organização
BILLING_PROJECT_ID_OR_NUMBER: o ID ou o número do projeto para uso de cota e faturamento. Executar um comando gcloud afeta a cota como se você tivesse feito a solicitação equivalente diretamente por uma API REST ou RPC.

Especifique o projeto cuja cota você quer usar. Ele pode ser diferente do projeto que contém o serviço para o qual você está visualizando as informações de cota.

Se você já configurou o projeto de faturamento ao configurar a gcloud CLI, essa flag é opcional. Caso contrário, a omissão pode causar um erro de permissão negada. Para mais informações, consulte Defina o projeto de cota.

Exemplo de comandos de preferências de cota da gcloud

Nesta seção, fornecemos exemplos que mostram como usar os comandos gcloud alpha quotas preferences para verificar as preferências de cota atuais e ajustar o valor da cota.

O recurso QuotaPreference representa sua preferência por uma determinada combinação de dimensões. Uma dimensão é um atributo que representa uma região ou zona ou uma dimensão específica do serviço, como gpu_family ou network_id.

Verificar as preferências

Para verificar as preferências existentes, execute o seguinte comando:

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

Substitua:

PROJECT_ID_OR_NUMBER: o ID ou o número do projeto
BILLING_PROJECT_ID_OR_NUMBER: o ID ou o número do projeto para uso de cota e faturamento. Executar um comando gcloud afeta a cota como se você tivesse feito a solicitação equivalente diretamente por uma API REST ou RPC.

Especifique o projeto cuja cota você quer usar. Ele pode ser diferente do projeto para o qual você está verificando as preferências de cota.

Se você já configurou o projeto de faturamento ao configurar a gcloud CLI, essa flag é opcional. Caso contrário, a omissão pode causar um erro de permissão negada. Para mais informações, consulte Defina o projeto de cota.

Verifique as preferências existentes com ajustes de cota pendentes

Para verificar as preferências atuais com ajustes de cota pendentes, adicione a sinalização --reconciling-only=true, conforme mostrado no comando a seguir:

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

Substitua:

PROJECT_ID_OR_NUMBER: o ID ou o número do projeto
BILLING_PROJECT_ID_OR_NUMBER: o ID ou o número do projeto para uso de cota e faturamento. Executar um comando gcloud afeta a cota como se você tivesse feito a solicitação equivalente diretamente por uma API REST ou RPC.

Especifique o projeto cuja cota você quer usar. Ele pode ser diferente do projeto para o qual você está verificando as preferências de cota.

Se você já configurou o projeto de faturamento ao configurar a gcloud CLI, essa flag é opcional. Caso contrário, a omissão pode causar um erro de permissão negada. Para mais informações, consulte Defina o projeto de cota.

Solicita um ajuste de aumento de cota quando uma preferência de cota ainda não tiver sido definida

Para solicitar um ajuste de aumento de cota para uma região específica quando uma preferência ainda não tiver sido definida, execute o seguinte comando:

gcloud alpha quotas preferences create --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 --preference-id=PREFERENCE_ID

Substitua:

PREFERRED_VALUE: o valor de cota preferencial
QUOTA_ID: o valor do ID da cota. Para encontrar esse valor, consulte Encontrar o ID da cota.
SERVICE_NAME: o nome do serviço com cotas que você quer ver. Por exemplo, o nome do serviço do Compute Engine é compute.googleapis.com.
PROJECT_ID_OR_NUMBER: o ID ou o número do projeto
BILLING_PROJECT_ID_OR_NUMBER: o ID ou o número do projeto para uso de cota e faturamento. Executar um comando gcloud afeta a cota como se você tivesse feito a solicitação equivalente diretamente por uma API REST ou RPC.

Especifique o projeto cuja cota você quer usar. Ele pode ser diferente do projeto para o qual você está solicitando um ajuste de cota.

Se você já configurou o projeto de faturamento ao configurar a gcloud CLI, essa flag é opcional. Caso contrário, a omissão pode causar um erro de permissão negada. Para mais informações, consulte Defina o projeto de cota.
EMAIL: um endereço de e-mail que pode ser usado como contato. caso o Google Cloud precise de mais informações para tomar uma decisão antes que uma cota extra possa ser concedida.
PREFERENCE_ID: um ID de preferência opcional. Se você não especificar um ID de preferência, a API vai gerar um identificador universalmente exclusivo (UUID, na sigla em inglês) para você.

Solicita um ajuste de aumento de cota quando uma preferência de cota tiver sido definida

Para solicitar um ajuste de aumento de cota para uma região específica e já houver uma preferência, execute o seguinte comando:

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

Substitua:

PREFERENCE_ID: o ID de preferência, que é necessário como o primeiro argumento ao usar o comando gcloud alpha quotas preferences update.
PREFERRED_VALUE: o valor de cota preferencial
QUOTA_ID: o valor do ID da cota. Para encontrar esse valor, consulte Encontrar o ID da cota.
SERVICE_NAME: o nome do serviço com cotas que você quer ver. Por exemplo, o nome do serviço do Compute Engine é compute.googleapis.com.
PROJECT_ID_OR_NUMBER: o ID ou o número do projeto
EMAIL: um endereço de e-mail que pode ser usado como contato. caso o Google Cloud precise de mais informações para tomar uma decisão antes que uma cota extra possa ser concedida.
BILLING_PROJECT_ID_OR_NUMBER: o ID ou o número do projeto para uso de cota e faturamento. Executar um comando gcloud afeta a cota como se você tivesse feito a solicitação equivalente diretamente por uma API REST ou RPC.

Especifique o projeto cuja cota você quer usar. Ele pode ser diferente do projeto para o qual você está solicitando um ajuste de cota.

Se você já configurou o projeto de faturamento ao configurar a gcloud CLI, essa flag é opcional. Caso contrário, a omissão pode causar um erro de permissão negada. Para mais informações, consulte Defina o projeto de cota.

Solicita um ajuste de aumento de cota usando uma dimensão

Para solicitar um ajuste de aumento de cota usando uma dimensão, execute o seguinte comando:

gcloud alpha quotas preferences create --preferred-value=PREFERRED_VALUE \
    --quota-id=QUOTA_ID --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \
    --dimensions=KEY1=VALUE1,KEY2=VALUE2,... --billing-project=BILLING_PROJECT_ID_OR_NUMBER \
    --email=EMAIL --justification=JUSTIFICATION --preference-id=PREFERENCE_ID

Substitua:

PREFERRED_VALUE: o valor de cota preferencial
QUOTA_ID: o valor do ID da cota. Para encontrar esse valor, consulte Encontrar o ID da cota.
SERVICE_NAME: o nome do serviço com cotas que você quer ver. Por exemplo, o nome do serviço do Compute Engine é compute.googleapis.com.
PROJECT_ID_OR_NUMBER: o ID ou o número do projeto
KEY1=VALUE1,KEY2=VALUE2,...: uma lista opcional que especifica a dimensão como uma lista separada por vírgulas de pares de chave-valor. Por exemplo, sua dimensão pode especificar estes valores do Compute Engine:
- KEY1=VALUE1: region=us-east4
- KEY2=VALUE2: gpu_family=NVIDIA_H100
BILLING_PROJECT_ID_OR_NUMBER: o ID ou o número do projeto para uso de cota e faturamento. Executar um comando gcloud afeta a cota como se você tivesse feito a solicitação equivalente diretamente por uma API REST ou RPC.

Especifique o projeto cuja cota você quer usar. Ele pode ser diferente do projeto para o qual você está solicitando um ajuste de cota.

Se você já configurou o projeto de faturamento ao configurar a gcloud CLI, essa flag é opcional. Caso contrário, a omissão pode causar um erro de permissão negada. Para mais informações, consulte Defina o projeto de cota.
EMAIL: um endereço de e-mail que pode ser usado como contato. caso o Google Cloud precise de mais informações para tomar uma decisão antes que uma cota extra possa ser concedida.
JUSTIFICATION: uma string opcional que explica sua solicitação.
PREFERENCE_ID: um ID de preferência opcional. Se você não especificar um ID de preferência, a API vai gerar um identificador universalmente exclusivo (UUID, na sigla em inglês) para você.

A saída vai conter dados específicos da sua configuração e será semelhante ao exemplo abaixo:

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

Ver uma preferência de cota

Para acessar os detalhes da preferência de cota que você acabou de criar, execute o seguinte comando:

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

Substitua:

PREFERENCE_ID: o ID de preferência, que é necessário como o primeiro argumento ao usar o comando gcloud alpha quotas preferences describe.
PROJECT_ID_OR_NUMBER: o ID ou o número do projeto
BILLING_PROJECT_ID_OR_NUMBER: o ID ou o número do projeto para uso de cota e faturamento. Executar um comando gcloud afeta a cota como se você tivesse feito a solicitação equivalente diretamente por uma API REST ou RPC.

Especifique o projeto cuja cota você quer usar. Ele pode ser diferente do projeto em que você está visualizando a preferência de cota.

Se você já configurou o projeto de faturamento ao configurar a gcloud CLI, essa flag é opcional. Caso contrário, a omissão pode causar um erro de permissão negada. Para mais informações, consulte Defina o projeto de cota.

A saída vai conter dados específicos da sua configuração e será semelhante ao exemplo abaixo:

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'

Outros serviços com comandos da gcloud CLI relacionados a cotas

Além de gcloud alpha quotas, alguns serviços têm o próprio acesso à linha de comando para obter informações de uso de recursos e cotas.

Por exemplo, o Compute Engine permite acessar informações de cota usando. Para mais detalhes, consulte as seguintes seções do Compute Engine:

cotas de alocação.
Visão geral do compute da gcloud CLI
A seção gcloud CLI compute da referência do SDK do Google Cloud.

A seguir

Para mais informações sobre comandos e flags gcloud alpha quotas, consulte as cotas gcloud alpha da referência da CLI do Google Cloud.

Para mais informações sobre a terminologia de cotas, consulte Noções básicas sobre valores de cota e limites do sistema.