Implemente casos de uso comuns

Nesta página, descrevemos como implementar casos de uso comuns com a API Cloud Quotas. Essa API permite ajustar as cotas de maneira programática e automatizar ajustes de cota nos seus projetos, pastas do Google Cloud ou organização.

Para saber mais, consulte a visão geral e a referência da API Cloud Quotas.

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.

Rastrear o uso e solicitar um aumento quando o uso estiver acima de 80%

Este exemplo acompanha o uso de cotas com o Cloud Monitoring e solicita um aumento quando o uso é superior a 80%.

Chame o recurso QuotaInfo do seu serviço para determinar o quotaValue atual. O serviço neste exemplo é compute.googleapis.com:
```
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
```
Substitua PROJECT_NUMBER pelo número do projeto do seu projeto.

Para encontrar as CPUs por projeto e os locais aplicáveis, procure na resposta QuotaInfo o ID de cota CPUS-per-project-region. O quotaValue é 20.

"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": [
            {
                "dimensions": [],
                "details": {
                    "quotaValue": 20,
                    "resetValue": 20
                },
                "applicableLocations": [
                    "us-central1",
                    "us-central2",
                    "us-west1",
                    "us-east1"
                ]
            }
        ]
    },
    ...
]

Chame a API Cloud Monitoring para saber o uso da cota. No exemplo a seguir, a região us-central1 foi especificada. As métricas de cota compatíveis são listadas em serviceruntime.

{
"name": "projects/PROJECT_NUMBER"
    "filter": "metric.type=\"serviceruntime.googleapis.com/quota/allocation/usage\" AND
    metric.labels.quota_metric=\"compute.googleapis.com/cpus\" AND resource.type=\"consumer_quota\" AND
    resource.label.location=\"us-central1\" ",
    "interval": {
    "startTime": "2023-11-10T18:18:18.0000Z",
    "endTime": "2023-11-17T18:18:18.0000Z"
    },
    "aggregation": {
    "alignmentPeriod": "604800s", // 7 days
    "perSeriesAligner": "ALIGN_MAX",
    "crossSeriesReducer": "REDUCE_MAX"
    }
}

Para determinar o uso, processe a resposta da API Cloud Monitoring. Compare o valor do Cloud Monitoring com o quotaValue nas etapas anteriores para determinar o uso.

Na resposta de exemplo a seguir, o valor de uso no Cloud Monitoring é 19 na região us-central1. O quotaValue para todas as regiões é 20. O uso é maior que 80% da cota e é possível iniciar uma atualização de preferência de cota.

time_series {
 metric {
  labels {
   key: "quota_metric"
   value: "compute.googleapis.com/cpus"
  }
     type: "serviceruntime.googleapis.com/quota/allocation/usage"
  }
  resource {
    type: "consumer_quota"
    labels {
      key: "project_id"
      value: "PROJECT_ID"
    }
    labels {
      key: "location"
      value: "us-central1"
    }
  }
  metric_kind: GAUGE
  value_type: INT64
  points {
    interval {
      start_time {
        seconds: "2023-11-10T18:18:18.0000Z"
      }
      end_time {
        seconds: "2023-11-17T18:18:18.0000Z"
      }
    }
    value {
      int64_value: 19
    }
  }
}

Para evitar preferências de cota duplicadas, chame ListQuotaPreferences primeiro para verificar se há solicitações pendentes. A sinalização reconciling=true chama solicitações pendentes.
```
GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true
```
Substitua PROJECT_NUMBER pelo número do projeto do seu projeto.
Chame UpdateQuotaPreference para aumentar o valor da cota para a região us-central1. No exemplo a seguir, um novo valor preferencial de 100 foi especificado.

O campo allow_missing está definido como true. Isso instrui o sistema a criar um recurso QuotaPreference em que não há nenhum com o nome fornecido.
```
PATCH projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1?allowMissing=true {
  "service": "compute.googleapis.com",
  "quotaId": "CPUS-per-project-region",
  "quotaConfig": { "preferredValue": 100 },
  "dimensions": { "region": "us-central1" }
}
```
Para ajustar as dimensões da sua preferência de cota, faça o seguinte:
- Se você quiser que a preferência de cota se aplique a todas as regiões, remova as informações de região.
- Se a cota for definida por zona, substitua as informações de região pelas de zona.

Chame GetQuotaPreference para verificar o status da mudança da preferência de cota:

GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1

Substitua PROJECT_NUMBER pelo número do projeto do seu projeto. Enquanto o Google Cloud avalia o valor da cota solicitada, o status de reconciliação é definido como true.

"name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1",
"service": "compute.googleapis.com",
"quotaId": "CPUS-per-project-region",
"quotaConfig": {
    "preferredValue": 100,
    "grantedValue": 50,
    "traceId": "123acd-345df23",
    "requestOrigin": "ORIGIN_UNSPECIFIED"
},
"dimensions": { "region": "us-central1" },
"reconciling": true,
"createTime": "2023-01-15T01:30:15.01Z",
"updateTime": "2023-01-16T02:35:16.01Z"

Depois que a preferência de cota for processada, o campo reconciling será definido como false. O grantedValue é igual ao preferredValue. A cota preferencial foi totalmente concedida.

Quando o Google Cloud nega ou aprova parcialmente uma solicitação do cliente, o valor da cota concedido ainda pode ser menor que o valor preferencial.

Diminuir uma cota

O exemplo a seguir diminui o número de TPUs para 10 em cada região.

Consiga o ID da cota e o valor da cota atual com uma chamada ListQuotaInfos:
```
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
```
Substitua PROJECT_NUMBER pelo número do projeto do seu projeto.

Procure nos campos de resposta uma entrada QuotaInfo para V2-TPUS-per-project-region.

"quotaInfos": [
    ...
     {
        "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region",
        "quotaId": "V2-TPUS-per-project-region",
        "metric": "compute.googleapis.com/Tpus",
        "containerType": "PROJECT",
        "dimensions": [
            "region"
        ],
        "dimensionsInfo": [
            {
                "dimensions": [],
                "details": {
                    "quotaValue": 20,
                    "resetValue": 20
                },
                "applicableLocations": [
                    "us-central1",
                    "us-central2",
                    "us-west1",
                    "us-east1"
                ]
            }
        ]
    },
    ...
]

Nesta resposta, o ID da cota é V2-TPUS-per-project-region, e o quotaValue atual é 20.

Reduza a cota de TPU em cada região para 10 com um CreateQuotaPreferenceRequest. Defina preferredValue como 10.

POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-Tpu-all-regions {
    "quotaConfig": {
        "preferredValue": 10
    },
    "dimensions": [],
    "service": "compute.googleapis.com",
    "quotaId": "V2-TPUS-per-project-region",
    "contactEmail": EMAIL
}

Confirme o novo valor da cota com uma chamada GetQuotaInfo que define o ID da cota como V2-TPUS-per-project-region.

GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region

Substitua PROJECT_NUMBER pelo número do projeto do seu projeto. Veja a seguir um exemplo de resposta. O value é 10 e é aplicável em todas as regiões.

"name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region",
"quotaId": "V2-TPUS-per-project-region",
"metric": "compute.googleapis.com/v2_tpus",
"containerType": "PROJECT",
"dimensions": [
    "region"
],
"dimensionsInfo": [
    {
        "dimensions": [],
        "details": {
            "value": 10,
        },
        "applicableLocations": [
            "us-central1",
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
]

Copiar preferências de cota para outro projeto

O exemplo a seguir copia todas as preferências de cota de um projeto para outro.

Chame ListQuotaPreferences no projeto de origem sem filtro:
```
GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
```
PROJECT_NUMBER1 é o número do projeto de origem. A resposta contém todas as preferências de cota para o projeto de origem.

Para cada preferência de cota na resposta, chame UpdateQuotaPreference e defina os seguintes campos:

name: o campo de nome atualizado é extraído da resposta, e o número do projeto de origem (PROJECT_NUMBER1) é substituído pelo número do projeto de destino (PROJECT_NUMBER2).
service, quotaId, preferredValue, dimensions: esses campos podem ser extraídos diretamente da resposta no estado em que se encontram.

for (QuotaPreference srcPreference : listResponse.getQuotaPreferences()) {
    QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
        .setName(srcPreference.getName().replace("PROJECT_NUMBER1", "PROJECT_NUMBER2"))
        .setService(srcPreference.getService())
        .setQuotaId(srcPreference.getQuotaId())
        .setQuotaConfig(
            QuotaConfig.newBuilder().setPreferredValue(srcPreference.getQuotaConfig().getPreferredValue()))
        .putAllDimensions(srcPreference.getDimensionsMap());
    UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
    cloudQuotas.updateQuotaPreference(updateRequest);
}

Chame ListQuotaPreferences para verificar o status das preferências de cota para o projeto de destino:
```
GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences
```
PROJECT_NUMBER2 é o número do projeto de origem.

Listar solicitações de cota pendentes

Para listar todas as solicitações de preferência de cota pendentes de um projeto, chame ListQuotaPreferences com o filtro reconciling=true.

Get projects/PROJECT_NUMBER/locations/global/quotaPreferences?reconciling=true

Substitua PROJECT_NUMBER pelo número do projeto do seu projeto.

A resposta para essa solicitação retorna a preferência de cota pendente mais recente. Como a API Cloud Cotas é declarativa, a preferência de cota mais recente é o que o sistema tenta atender.

Um exemplo de resposta é semelhante a este:

  "quotaPreferences": [
    {
      "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1",
      "service": "compute.googleapis.com",
      "quotaId": "CPUS-per-project-region",
      "quotaConfig": {
        "preferredValue": 100,
        "grantedValue": 30,
        "traceId": "123acd-345df23",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
      },
      "dimensions": {
        "region": "us-central1"
      },
      "reconciling": true,
      "createTime": "2023-01-15T01:30:15.01Z",
      "updateTime": "2023-01-16T02:35:16.01Z"
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-cross-regions",
      "service": "compute.googleapis.com",
      "quotaId": "CPUS-per-project-region",
      "quotaConfig": {
        "preferredValue": 10,
        "grantedValue": 5,
        "traceId": "456asd-678df43",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
      },
      "reconciling": true,
      "createTime": "2023-01-15T01:35:15.01Z",
      "updateTime": "2023-01-15T01:35:15.01Z"
    }
  ]

Solicitar aumentos de cota do grupo

Para solicitar aumentos para um grupo de cotas em um novo projeto, armazene as cotas preferenciais para o novo projeto em um arquivo CSV com os seguintes valores: nome do serviço, ID de cota, valor de cota preferido e dimensões.

Para cada linha no arquivo CSV, leia o conteúdo nos campos serviceName, quotaId, preferredValue e dimensionMap.

CreateQuotaPreferenceRequest request =
  CreateQuotaPreferenceRequest.newBuilder()
     .setParent("projects/PROJECT_NUMBER/locations/global")
     .setQuotaPreferenceId(buildYourOwnQuotaPreferenceId(serviceName, quotaId, dimensionMap))
     .setQuotaPreference(
        QuotaPreference.newBuilder()
            .setService(serviceName)
            .setQuotaId(quotaId)
            .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue))
            .putAllDimensions(dimensionMap))
  .build();
cloudQuotas.createQuotaPreference(request);

Substitua PROJECT_NUMBER pelo número do projeto do seu projeto.

Como o projeto de destino é novo, é seguro chamar o método CreateQuotaPreference ao ler e atribuir os campos. Como alternativa, chame o método UpdateQuotaPreference com allow_missing definido como true.

O método buildYourOwnQuotaPreferenceId cria um ID de preferência de cota com base no nome do serviço, no ID da cota e em um mapa de dimensões de acordo com o esquema de nomenclatura. Como alternativa, você pode optar por não definir o ID de preferência de cota. Um código de preferência de cota é gerado para você.

Solicitar ajustes em cotas que não são usadas

Para cotas que ainda não têm uso de cota e que têm cotas específicas dimensões como vm_family, é possível que essas cotas não no console do Google Cloud. Talvez seja necessário usar o a API Cloud Cotas.

Por exemplo, você pode clonar um projeto e saber com antecedência que precisa aumentar o valor de compute.googleapis.com/gpus_per_gpu_family. Esse valor só aparece no console do Google Cloud para as famílias de GPU que você tem já foi usado. Para usar a API Cloud Cotas para solicitar um aumento para GPUs NVIDIA_H100 em us-central1, você pode enviar uma solicitação como esta:

POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-gpus-us-central1-NVIDIA_H100 {
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": { "preferredValue": 100 },
    "dimensions": { "region": "us-central1", "gpu_family": "NVIDIA_H100" },
    "contactEmail": EMAIL
}

Substitua:

PROJECT_NUMBER: o identificador exclusivo 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 uma cota extra pode ser concedida.

Para mais informações, consulte também as descrições Precedência da dimensão e Combinação de dimensões.

Receber informações de cota para uma dimensão específica de serviço

A família de GPUs é uma dimensão específica do serviço. O exemplo de solicitação a seguir usa o ID de cota GPUS-PER-GPU-FAMILY-per-project-region para receber o recurso QuotaInfo.

GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GPUS-PER-GPU-FAMILY-per-project-region

Substitua PROJECT_NUMBER pelo número do projeto do seu projeto.

Este é um exemplo de resposta. Para cada chave gpu_family exclusiva, quotaValue e applicableLocations são diferentes:

"name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GpusPerProjectPerRegion",
"quotatName": "CPUS-per-project-region",
"metric": "compute.googleapis.com/gpus_per_gpu_family",
"isPrecise": true,
"quotaDisplayName": "GPUs per GPU family",
"metricDisplayName": "GPUs",
"dimensions": [
    "region",
    "gpu_family"
],
"dimensionsInfo": [
    {
        "dimensions": {
            "region": "us-central1",
            "gpu_family": "NVIDIA_H200"
        },
        "details": {
            "quotaValue": 30,
            "resetValue": 30,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": {
            "region": "us-central1"
            }
        "details": {
            "quotaValue": 100,
            "resetValue": 100,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": {
            "gpu_familly": "NVIDIA_H100"
            }
        "details": {
            "quotaValue": 10,
        },
        "applicableLocations": [
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
      {
        "dimensions": [],
        "details": {
            "quotaValue": 50,
            "resetValue": 50,
        },
        "applicableLocations": [
            "us-central1",
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
]

Criar uma preferência de cota para uma dimensão específica do serviço

O exemplo a seguir demonstra como criar uma cota para uma determinada região e família de GPUs com um valor preferencial de 100. O local de destino é especificado no mapa de dimensões com a chave region e a família de GPUs de destino com a chave gpu_family.

O exemplo de CreateQuotaPreference a seguir especifica uma família de GPU de NVIDIA_H100 e uma região de us-central1.

POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-gpus-us-central1-NVIDIA_H100 {
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": {"region": "us-central1", "gpu_family": "NVIDIA_H100"},
    "contactEmail": EMAIL"
}

Substitua:

PROJECT_NUMBER: o identificador exclusivo 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 uma cota extra pode ser concedida.

Atualizar uma preferência de cota para uma dimensão específica do serviço

O exemplo de código a seguir mostra o valor atual da dimensão. {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, e, em seguida, define o valor preferido para duplicar esse valor.

// Get the current quota value for the target dimensions
Map<String, String> targetDimensions = Maps.createHashMap("region", "us-central1", "gpu_family", "NVIDIA_H100");
long currentQuotaValue = 0;
QuotaInfo quotaInfo = cloudQuotas.GetQuotaInfo(
    "projects/PROJECT_NUMBER/locations/global/services/" + serviceName + "quotaInfos/" + quotaId;
for (dimensionsInfo : quotaInfo.getDimensionsInfoList()) {
    If (targetDimensions.entrySet().containsAll(dimensionsInfo.getDimensionsMap().entrySet()) {
       currentQuotaValue = dimensionsInfo.getDetails().getValue();
       break;
    })
}

// Set the preferred quota value to double the current value for the target dimensions
QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
        .setName(buildYourOwnQuotaPreferenceId(serviceName, quotaId, targetDimensions))
        .setService(serviceName)
        .setQuotaId(quotaId)
        .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2))
        .putAllDimensions(targetDimensions));
UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
 cloudQuotas.updateQuotaPreference(updateRequest);

Substitua PROJECT_NUMBER pelo identificador exclusivo de seu projeto.

A seguir

Sobre a API Cloud Cotas
Referência da API Cloud Cotas
Entenda as cotas