As seções a seguir contêm exemplos de comandos gcloud beta quotas info
e gcloud beta 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 Google Cloud APIs e serviços.
Limitações
As cotas do Cloud têm as seguintes limitações:
Na maioria dos casos, os ajustes de aumento de cota precisam ser feitos no nível do projeto. Um número limitado de produtos oferece suporte a ajustes de aumento de cota no nível da organização. Para saber se um produto Google Cloud oferece suporte a ajustes de aumento de cota no nível da organização, consulte a documentação do produto.
É possível solicitar ajustes de diminuição de cota para cotas no nível do projeto, da organização e da pasta.
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 usar a gcloud CLI, verifique se você instalou e inicializou a gcloud CLI.
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 gcloud CLI para cotas do Cloud, instale e inicialize os componentes:
Instale a CLI gcloud.
Se você estiver usando o Cloud Shell, pule esta etapa porque a gcloud CLI vem pré-instalada.
Inicialize a CLI gcloud.
Instale o componente Beta executando o seguinte comando:
gcloud components install beta
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:
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 beta 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 projetoPara encontrar o ID do projeto usando o console do Google Cloud, navegue até a página do 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 beta 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 especificarQUOTA_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 beta 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 beta 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 projetoBILLING_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 beta 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çãoBILLING_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 beta 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 beta 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 projetoBILLING_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 beta 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 projetoBILLING_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 beta 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 \
--justification=JUSTIFICATION --preference-id=PREFERENCE_ID
Substitua:
PREFERRED_VALUE
: o valor de cota preferencialQUOTA_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 projetoBILLING_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 Google Cloud precise de mais informações antes de conceder uma cota extra.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ê.
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 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
Substitua:
PREFERENCE_ID
: o ID de preferência, que é necessário como o primeiro argumento ao usar o comandogcloud beta quotas preferences update
.PREFERRED_VALUE
: o valor de cota preferencialQUOTA_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 projetoBILLING_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 Google Cloud precise de mais informações antes de conceder uma cota extra.JUSTIFICATION
: uma string opcional que explica sua solicitação.
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 beta 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 preferencialQUOTA_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 projetoKEY1=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 Google Cloud precise de mais informações antes de conceder uma cota extra.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 beta 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 comandogcloud beta quotas preferences describe
.PROJECT_ID_OR_NUMBER
: o ID ou o número do projetoBILLING_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'
Ativar o ajustador de cotas em um projeto de cliente
Um projeto de cliente se refere ao projeto usado por um aplicativo ou usuário para acessar e interagir com recursos Google Cloud , enquanto um projeto de recurso é o projeto subjacente em que esses recursos são armazenados e gerenciados.
Para ativar o ajustador de cota em um projeto de cliente usando a CLI gcloud, siga estas etapas:
Criar um projeto de cliente:
gcloud projects create CLIENT_PROJECT_ID gcloud config set project CLIENT_PROJECT_ID
Substitua
CLIENT_PROJECT_ID
pelo ID do projeto que você quer criar. Os IDs de projeto são imutáveis e só podem ser definidos durante a criação do projeto. Eles precisam começar com uma letra minúscula e podem ter letras ASCII minúsculas, dígitos ou hifens. Os IDs de projeto precisam ter entre 6 e 30 caracteres.Ative a API Cloud Quotas no projeto do cliente:
gcloud services enable cloudquotas.googleapis.com
Crie uma conta de serviço no projeto do cliente:
gcloud iam service-accounts create SA_NAME \ --display-name SA_DISPLAY_NAME \ --project=CLIENT_PROJECT_ID
Substitua:
SA_NAME
: o nome interno da nova conta de serviço. Usado para gerar um IAM_ACCOUNT (um endereço de e-mail interno do IAM usado como um identificador da conta de serviço), que precisa ser transmitido para comandos subsequentes.SA_DISPLAY_NAME
: o nome de exibição da conta de serviço.CLIENT_PROJECT_ID
: o ID do projeto do cliente.
Crie uma chave de conta de serviço:
gcloud iam service-accounts keys create KEY_FILE \ --iam-account=SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com
Substitua:
KEY_FILE
: o caminho para o arquivo de chave da conta de serviço JSON.SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com
: o endereço de e-mail da conta de serviço.
Conceda as permissões do IAM à conta de serviço:
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"
Substitua:
CLIENT_PROJECT_ID
: o ID do projeto do cliente.RESOURCE_PROJECT_ID
: o ID do projeto de recurso.SA_NAME@CLIENT_PROJECT_ID.iam.gserviceaccount.com
: o endereço de e-mail da conta de serviço.
Ative a conta de serviço usando a chave que você criou anteriormente:
gcloud auth activate-service-account --key-file=KEY_FILE
Ative o ajustador de cotas no projeto de recurso especificando o projeto e a configuração de ativação:
gcloud beta quotas adjuster settings update --project=RESOURCE_PROJECT_ID \ --enablement=enabled
A configuração de ativação é necessária ao usar a CLI gcloud e precisa ser definida como
enabled
oudisabled
.Opcional: para conferir as configurações atuais do ajustador de cota, execute o seguinte comando:
gcloud beta quotas adjuster settings describe --project=RESOURCE_PROJECT_ID
A resposta será semelhante a:
enablement: ENABLED etag: 8izmJp6EI__mOfLyhkQU9 name: projects/RESOURCE_PROJECT_ID/locations/global/quotaAdjusterSettings updateTime: '2025-01-10T17:22:37.883221181Z'
Para ativar o ajustador de cotas em vários projetos de cliente, siga as etapas 5 a 8 anteriores. Ao fazer isso, verifique se as seguintes condições são atendidas:
- A API Cloud Quotas está ativada no projeto do cliente.
- Verifique se a conta de serviço tem o
papel do IAM
cloudquotas.admin
em todos os projetos de recursos em que você quer ativar o ajustador de cota.
Outros serviços com comandos da gcloud CLI relacionados a cotas
Além de gcloud beta 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 resolver problemas com comandos
gcloud beta quotas
, consulte Solução de problemas com erros da gcloud CLI.Para detalhes sobre comandos e flags
gcloud beta quotas
, consulte a seção cotas gcloud beta 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.