A API Cloud Quotas permite que você ajuste programaticamente cotas em nível de projeto e automatize solicitações de ajuste de cotas em nível de projeto. Por exemplo, é possível usar a API Cloud Quotas para:
Automatizar ajustes de cota: use a API Cloud Quotas para solicitar ajustes de cota com base nos seus próprios critérios. Por exemplo, para evitar erros de cota excedida, você pode usar a API para solicitar programaticamente um ajuste de cota quando os recursos do Compute Engine atingirem 80% da cota disponível.
Reutilizar configurações de cota em projetos: a API Cloud Quotas pode clonar suas configurações de cota de projeto em projeto. Se houver um conjunto conhecido de cotas que precisam ser aumentadas para cada novo projeto Google Cloud , você poderá usar a API Cloud Quotas para automatizar isso na lógica de criação do seu projeto. As solicitações de ajuste de cota estão sujeitas à Google Cloud aprovação.
Atender às solicitações de cota do cliente: se você for um provedor de SaaS integrado ao Google Cloud, poderá receber solicitações de aumento de cota por um portal voltado para o cliente que não seja o console do Google Cloud. Essas solicitações precisam ser encaminhadas a Google Cloud para processamento. A API Cloud Quotas pode encaminhar automaticamente as solicitações dos clientes.
Ativar o controle de versão da configuração do cliente: a API Cloud Quotas é declarativa. É possível tratar as configurações de cota como código e armazenar as configurações no seu próprio sistema controlado por versão para fins de histórico e reversão.
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.
Endpoint de serviço
Um endpoint de serviço é um URL base que especifica o endereço de rede de um serviço de API. Um serviço pode ter vários endpoints. O serviço da API Cloud Cotas tem o endpoint a seguir e todos os URIs são relacionados a ele:
https://cloudquotas.googleapis.com
Funções exigidas
Para ter as permissões necessárias para acessar os recursos cloudquotas_quotaPreferences
, cloudquotas_quotaInfos
e cloudquotas_quotaAdjusterSettings
, peça ao administrador para conceder a você o papel do IAM de
Administrador de cotas do Cloud (cloudquotas.admin
)
no projeto.
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Esse papel predefinido contém
as permissões necessárias para acessar os recursos cloudquotas_quotaPreferences
, cloudquotas_quotaInfos
e cloudquotas_quotaAdjusterSettings
. Para conferir as permissões exatas
necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As permissões a seguir são necessárias para acessar os recursos cloudquotas_quotaPreferences
, cloudquotas_quotaInfos
e cloudquotas_quotaAdjusterSettings
:
-
cloudquotas.quotas.update
-
cloudquotas.quotas.get
-
monitoring.timeSeries.list
-
resourcemanager.projects.get
-
resourcemanager.projects.list
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Modelo de recurso de API
O modelo de recursos da API Cloud Cotas consiste em dois recursos: QuotaPreference
e QuotaInfo
.
Preferência de cota
O recurso QuotaPreference
representa sua preferência de cota por uma determinada
combinação de dimensões. Use esse recurso para ajustar as cotas nos seus projetos, pastas ou organizações.
Definir um valor preferencial para uma região
O exemplo a seguir mostra um recurso QuotaPreference
em um
método CreateQuotaPreference
.
{ "service": "compute.googleapis.com", "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region", "quotaConfig": { "preferredValue": 100 }, "dimensions": { "region": "us-central1" } }
O preferredValue
de 100 indica que o solicitante quer que a cota GPUS-PER-GPU-FAMILY-per-project-region
seja definida como esse valor. O campo de dimensões indica que a preferência se aplica apenas à região us-central1
.
Verificar o valor concedido
Confira sua preferência de cota e analise o campo grantedValue
para verificar o
valor concedido.
Para conferir sua preferência de cota usando a Google Cloud CLI, execute o seguinte no terminal:
gcloud alpha quotas preferences describeQUOTA_PREFERENCE_ID --project=PROJECT
Substitua:
QUOTA_PREFERENCE_ID
: o ID da sua preferência de cota. Esse é o valor especificado quando a preferência de cota foi criada.PROJECT
: o ID ou número do Google Cloud projeto.
Se você fez uma solicitação de ajuste de cota e ela foi parcialmente aprovada,
um campo stateDetail
vai aparecer após o campo grantedValue
. O
grantedValue
mostra o ajuste que foi feito, e o campo stateDetail
descreve o estado parcialmente aprovado.
Para saber se o valor concedido é o valor final aprovado, consulte o
campo reconciling
. Se a solicitação ainda estiver em avaliação, o campo
reconciling
será definido como true
. Se o campo reconciling
for definido como
false
ou omitido, o valor concedido será o valor final aprovado.
Os snippets de código abaixo mostram exemplos do objeto de preferência de cota. Eles
usam uma preferência de cota de demonstração com o ID
compute_googleapis_com-gpus-us-central1
.
Se você consultar sua preferência de cota usando a CLI gcloud, a saída será semelhante a esta:
createTime: '2023-01-15T01:30:15.01Z' dimensions: region: us-central1 name: projects/PROJECT_NUMBER /locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1 quotaConfig: granteddValue: '100' preferredValue: '100' traceId: 123acd-345df23 requestOrigin: ORIGIN_UNSPECIFIED service: compute.googleapis.com quotaId: GPUS-PER-GPU-FAMILY-per-project-region updateTime: '2023-01-16T02:35:16.01Z'
Se você consultar sua preferência de cota usando a API Cloud Quotas, a saída será semelhante a esta:
{ "name": "projects/PROJECT_NUMBER /locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1", "service": "compute.googleapis.com", "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region", "quotaConfig": { "preferredValue": 100, "grantedValue": 100, "traceId": "123acd-345df23", "requestOrigin": "ORIGIN_UNSPECIFIED" }, "dimensions": { "region": "us-central1" }, "createTime": "2023-01-15T01:30:15.01Z", "updateTime": "2023-01-16T02:35:16.01Z" }
Esta saída inclui os seguintes valores:
PROJECT_NUMBER
: um identificador exclusivo gerado automaticamente para seu projeto.
A resposta mostra um grantedValue
de 100, o que significa
que o preferredValue
do exemplo anterior foi aprovado e atendido.
As preferências para dimensões diferentes são recursos QuotaPreference
diferentes. Por exemplo, QuotaPreference
para CPU nas regiões us-central1
e
us-east1
são dois recursos distintos.
A preferência de cota é obrigatória
Os recursos de QuotaPreference
são usados para indicar o valor preferido de uma
cota específica. O valor atual de uma cota específica é baseado em:
QuotaPreference
solicitações feitas por você.Solicitações de aumento de cota aprovadas por Google Cloud.
Mudanças nas cotas iniciadas por Google Cloud.
Não há suporte para a capacidade de excluir um QuotaPreference
. No entanto, é possível definir
um valor de cota preferencial menor que o Google Cloud aprovado para adicionar mais proteções.
Para mais informações sobre o recurso QuotaPreference
, consulte a Referência da API Cloud Cotas.
Para mais informações sobre as consultas QuotaPreference
, acesse
Implementar casos de uso comuns.
Informações de cota
QuotaInfo
é um recurso somente leitura que fornece informações sobre uma cota
específica para um determinado projeto, pasta ou organizações. Ela exibe informações das cotas definidas pelos serviços do Google Cloud e quaisquer ajustes de cotas iniciados pelos clientes. O recurso QuotaInfo
contém
informações como metadados, tipo de contêiner e dimensão.
Definir valores de cota diferentes por região
O exemplo de recurso QuotaInfo
a seguir mostra que a cota de CPU para o
projeto é de 200 para a região us-central1
e 100 para todas as outras regiões.
{ "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" ], "isPrecise": true, "quotaDisplayName": "CPUs per project per region", "metricDisplayName": "CPUs", "dimensionsInfo": [ { "dimensions": { "region": "us-central1" }, "details": { "quotaValue": 200, "resetValue": 200 }, "applicableLocations": [ "us-central1", ] }, { "details": { "quotaValue": 100, "resetValue": 100 }, "applicableLocations": [ "us-central2", "us-west1", "us-east1" ] } ] }
Esta saída inclui os seguintes valores:
PROJECT_NUMBER
: um identificador exclusivo gerado automaticamente para seu projeto.
Definir uma cota global
O exemplo de recurso QuotaInfo
a seguir mostra uma cota de taxa com um intervalo de atualização
por minuto. As dimensões estão em branco, o que indica que essa é uma
cota global. Todas as cotas sem dimensão de região ou zona são globais.
{ "name": "projects/PROJECT_NUMBER /locations/global/services/compute.googleapis.com/quotaInfos/ReadRequestsPerMinutePerProject", "quotaId": "ReadRequestsPerMinutePerProject", "metric": "compute.googleapis.com/read_requests", "refreshInterval": "minute", "containerType": "PROJECT", "dimensions": [], "isPrecise": false, "quotaDisplayName": "Read Requests per Minute", "metricDisplayName": "Read Requests", "dimensionsInfo": [ { "details": { "quotaValue": 100, "resetValue": 200 }, "applicableLocations": [ "global" ] } ] }
Esta saída inclui os seguintes valores:
PROJECT_NUMBER
: um identificador exclusivo gerado automaticamente para o projeto.
Para mais detalhes sobre o recurso QuotaInfo
, consulte a Referência da API Cloud Cotas.
Para mais detalhes sobre as consultas QuotaPreference
, consulte
Implementar casos de uso comuns.
Configurações do ajustador de cotas
O recurso QuotaAdjusterSettings
(Prévia)
representa as configurações do ajustador de cotas para um projeto específico. Quando ativado,
o ajustador de cotas monitora o uso dos recursos especificados e emite
solicitações de ajuste de cota quando o uso se aproxima do limite da cota.
Para conferir as configurações atuais do ajustador de cota de um projeto, use uma operação GET para extrair o recurso
QuotaAdjusterSettings
.Para ativar o ajustador de cotas em um projeto, use uma operação PATCH para definir as seguintes opções de recurso
QuotaAdjusterSettings
:"quota_adjuster_settings" :{ "name": "projects/
PROJECT_NUMBER /locations/global/quotaAdjusterSettings", "enablement": ENABLED, }Substitua
PROJECT_NUMBER
pelo identificador exclusivo de seu projeto.
Para saber mais, consulte Ativar o ajustador de cotas e Desativar o ajustador de cotas.
Nomes de recursos
Recursos são entidades nomeadas e são identificados por nomes de recursos. Os nomes dos recursos são usados em todas as solicitações e respostas, e cada recurso precisa ter o próprio nome exclusivo. Cada nome de recurso é codificado por um conjunto de campos.
Recurso de preferência de cota
A convenção de nomenclatura para um recurso QuotaPreference
usa o seguinte padrão:
projects/PROJECT_NUMBER /locations/global/quotaPreferences/QUOTA_PREFERENCE_ID
É possível definir quotaPreferenceId
ao criar uma preferência de cota. Caso contrário, um ID será gerado. É recomendável que um esquema de nomenclatura quotaPreferenceId
codifique o nome do serviço, o ID da cota, o local e outras dimensões. O
quotaPreferenceId
precisa ser exclusivo para o projeto, a pasta ou as organizações.
Por exemplo, quotaPreference
Este é um padrão para codificar seu ID de preferência de cota:
SERVICE _LOCATION _DIMENSION1-VALUES-IN-ORDER
O exemplo abaixo demonstra esse padrão.
compute_us-central1_nvidia-200
Com um nome de recurso, use o método
GET
para extrair um QuotaPreference
. Você também pode chamar o método
PATCH
com a opção allow_missing
ativada para criar ou atualizar um
QuotaPreference
.
Recurso de informações de cota
A convenção de nomenclatura para um recurso QuotaInfo
usa o seguinte padrão:
projects/PROJECT_NUMBER /locations/global/services/SERVICE_NAME /quotaInfos/QUOTA_ID
Recurso de configurações do ajustador de cotas
A convenção de nomenclatura para um recurso QuotaAdjusterSettings
usa o seguinte padrão:
projects/PROJECT_NUMBER /locations/global/quotaAdjusterSettings
A seguir
Referência da API Cloud Cotas
Entenda as cotas