Visão geral da API Cloud Quotas

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:

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 describe QUOTA_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