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%.

  1. 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.
  2. 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"
                    ]
                }
            ]
        },
        ...
    ]
  3. 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"
        }
    }
  4. 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
        }
      }
    }
  5. 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.
  6. 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" }
    }
  7. 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.

  1. 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.
  2. 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.
  3. 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
    }
  4. 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.

  1. 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.
  2. 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);
    }
  3. 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