Visão geral da API Cloud Quotas

Com a API Cloud Cotas, é possível ajustar programaticamente as quotas e automatizar os ajustes de cota no nível do projeto. A API Cloud Cotas pode ser usada para:

Automatizar ajustes de cota
Use a API Cloud Cotas para solicitar aumentos de cotas quando determinadas condições forem atendidas. Por exemplo, para evitar erros de cota excedida, use a API para solicitar um aumento de cota programaticamente quando os recursos do Compute Engine atingirem 80% da cota disponível.
Dimensionar as configurações de cota nos projetos
A API Cloud Cotas 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 do Google Cloud, é possível integrar a API à lógica de criação do seu projeto para solicitar automaticamente um .aumento de quota. Todos os aumentos de cota estão sujeitos à aprovação do Google Cloud.
Exibir 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 ao Google Cloud para processamento. A API Cloud Cotas pode encaminhar automaticamente as solicitações dos clientes.
Ativar o controle de versões da configuração do cliente
A API Cloud Cotas é 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

A API Cloud Cotas tem as seguintes limitações:

  • A API não é compatível com a CLI do Google Cloud.

  • A API não aceita solicitações de aumento de cota no nível da pasta e da organização.

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 e cloudquotas_quotaInfos, peça ao administrador para conceder a você o Administrador de cotas do Cloud (cloudquotas.admin ) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém as permissões necessárias para acessar os recursos cloudquotas_quotaPreferences e cloudquotas_quotaInfos. Para acessar 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 e cloudquotas_quotaInfos:

  • 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

O exemplo a seguir mostra um recurso QuotaPreference em um método GetQuotaPreference.

{
    "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 pelo Google Cloud.

  • Mudanças nas cotas iniciadas pelo 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 aprovado pelo Google Cloud 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 seu 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.

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 UPDATE 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

Precedência da dimensão

Alguns casos de uso da API Cloud Cotas têm configurações de dimensão complexas. As cotas podem ser configuradas em um nível mais granular que apenas regiões e zonas. Você pode conseguir essa granularidade ao usar dimensões específicas do serviço. Por exemplo, gpu_family e network_id são dimensões específicas do serviço no Compute Engine. As dimensões são definidas por serviço individual, e cada serviço pode ter um conjunto diferente de dimensões específicas.

Ao trabalhar com dimensões de local ou dimensões específicas do serviço, a seguinte precedência é aplicada:

  1. Uma configuração de preferência de cota com todas as dimensões específicas de local e serviço especificadas tem precedência sobre qualquer outra configuração.

  2. As configurações que especificam dimensões de local só têm precedência sobre aquelas que contêm apenas dimensões específicas do serviço.

Combinar dimensões

Em uma configuração de preferência de cota, é possível combinar dimensões das seguintes maneiras:

  1. A configuração pode conter ambas as dimensões de local e as específicas do serviço. Essa é a ordem de precedência mais alta.

  2. A configuração somente pode conter dimensões de local. Essa configuração se aplica a todas as dimensões específicas de serviços, exceto as explicitamente configuradas com o método 1.

  3. A configuração pode conter apenas dimensões específicas de serviços. Essa configuração se aplica a todos os locais, exceto aqueles explicitamente configurados com os métodos 1 ou 2.

  4. Se a configuração contiver alguma dimensão específica de serviço, ela precisará conter todas as dimensões específicas do serviço.

  5. Você pode ter configurações sem dimensões. Essas configurações se aplicam a todos os locais e a todas as dimensões específicas do serviço, exceto as configuradas explicitamente.

A seguir