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:

  • 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 do 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.

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

  • No console do Google Cloud, a página Cotas e limites do sistema não oferece suporte à seleção regional ou zonal para solicitações de ajuste de cota do botão Editar. Para ajustar as cotas no nível regional ou zonal no console do Google Cloud, consulte as instruções sobre como solicitar uma cota maior.

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 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 com suporte 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 flag 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 abaixo, 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" },
"justification": "JUSTIFICATION",
"contactEmail": "EMAIL"
}

    Substitua:

    • PROJECT_NUMBER: o identificador exclusivo do projeto.
    • JUSTIFICATION: uma string opcional que explica sua solicitação.
    • EMAIL: um endereço de e-mail que pode ser usado como contato, caso o Google Cloud precise de mais informações antes de conceder uma cota extra.

  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 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",
  "justification": "JUSTIFICATION",
  "contactEmail": "EMAIL"
}

    Substitua:

    • PROJECT_NUMBER: o identificador exclusivo do projeto.
    • JUSTIFICATION: uma string opcional que explica sua solicitação.
    • EMAIL: um endereço de e-mail que pode ser usado como contato, caso o Google Cloud precise de mais informações antes de conceder uma cota extra.

  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 seu projeto.

    Confira 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. Ele está escrito em Java, mas você pode usar qualquer linguagem de programação.

  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())
      .setJustification(srcPreference.getJustification())
      .setContactEmail(srcPreference.getContactEmail())
      .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

    Substitua PROJECT_NUMBER2 pelo número do projeto de destino.

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)
            .setJustification(justification)
            .setContactEmail(contactEmail)
            .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

As solicitações de ajuste de cota seguem o mesmo processo, independentemente de a cota que você está ajustando ter uso ou não. Para saber como solicitar um ajuste de aumento de cota, consulte Solicitar um valor de cota maior. Para solicitar um valor de cota menor, siga as instruções para solicitar um valor de cota maior, mas especifique o valor menor de sua preferência ao inserir o valor da solicitação.

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"},
    "justification": "JUSTIFICATION",
    "contactEmail": ""EMAIL"
}

Substitua:

  • PROJECT_NUMBER: o identificador exclusivo do projeto.
  • JUSTIFICATION: uma string opcional que explica sua solicitação.
  • EMAIL: um endereço de e-mail que pode ser usado como contato, caso o Google Cloud precise de mais informações antes de conceder uma cota extra.

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. Ele está escrito em Java, mas você pode usar qualquer linguagem de programação.

// 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)
        .setJustification(justification)
        .setContactEmail(contactEmail)
        .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