Implemente exemplos de utilização comuns

Este documento descreve como implementar exemplos de utilização comuns através da API Cloud Quotas. Esta API permite-lhe ajustar programaticamente as quotas e automatizar os ajustes de quotas nos seus Google Cloud projetos, pastas ou organização.

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

Limitações

As quotas do Google Cloud têm as seguintes limitações:

  • Na maioria dos casos, os ajustes de aumento da quota têm de ser feitos ao nível do projeto. Um número limitado de produtos suporta ajustes de aumento da quota ao nível da organização. Para ver se um Google Cloud produto suporta ajustes de aumento da quota ao nível da organização, consulte a documentação desse produto.

  • Pode pedir ajustes de diminuição da quota para quotas ao nível do projeto, da organização e da pasta.

Monitorize a utilização e peça um aumento quando a utilização for superior a 80%

Este exemplo monitoriza a utilização da quota com o Cloud Monitoring e, em seguida, pede um aumento quando a utilização é superior a 80%.

  1. Chame o recurso QuotaInfo para o seu serviço para determinar o estado atual quotaValue. 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 as localizações aplicáveis, procure na resposta QuotaInfo o ID da quota 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 encontrar a utilização da quota. No exemplo seguinte, foi especificada a região us-central1. As métricas de quota suportadas estã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 a sua utilização, processe a resposta da API Cloud Monitoring. Compare o valor do Cloud Monitoring com o quotaValue nos passos anteriores para determinar a utilização.

    Na resposta de exemplo seguinte, o valor de utilização no Cloud Monitoring é 19 na região us-central1. O quotaValue para todas as regiões é 20. A utilização é superior a 80% da quota e é possível iniciar uma atualização das preferências de quota.

    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 quota duplicadas, chame ListQuotaPreferences primeiro para verificar se existem pedidos pendentes. O indicador reconciling=true chama pedidos 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. Ligue para UpdateQuotaPreference para aumentar o valor da quota para a região us-central1. No exemplo seguinte, foi especificado um novo valor preferencial de 100.

    O campo allow_missing está definido como true. Isto indica ao sistema que deve criar um recurso QuotaPreference onde não exista 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 o seguinte:

    • PROJECT_NUMBER: o identificador exclusivo do seu projeto.
    • JUSTIFICATION: uma string opcional que explica o seu pedido.
    • EMAIL: um endereço de email que pode ser usado como contacto, caso a Google Cloud precise de mais informações antes de poder conceder quota adicional.

  7. Ligue para GetQuotaPreference para verificar o estado da alteração da preferência de quota:

    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 Google Cloud avalia o valor da quota pedido, o estado de conciliação da sua quota é definido como true.

    Por vezes, a Google Google Cloud aprova parte do seu pedido de aumento em vez de aprovar o aumento total. Se o pedido for parcialmente aprovado, a preferência de quota inclui um campo stateDetail. O campo stateDetail descreve o estado parcialmente aprovado. O campo grantedValue mostra o ajuste feito para satisfazer parcialmente o seu pedido.

    Para ver se o valor concedido é o valor final aprovado, consulte o campo reconciling. Se o seu pedido ainda estiver a ser avaliado, o campo reconciling está definido como true. Se o campo reconciling estiver definido como false ou for omitido, o valor concedido é o valor final aprovado.

    No exemplo seguinte, o valor da quota pedido é 100 e o campo reconciling indica que o pedido está em revisão.

    "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 de a preferência de quota ser processada, o campo reconciling é definido como false. O grantedValue é igual ao preferredValue. A quota preferencial é totalmente concedida.

    Quando Google Cloud rejeita ou aprova parcialmente um pedido do cliente, o valor da quota concedida pode continuar a ser inferior ao valor preferencial.

Diminua uma quota

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

  1. Obtenha o ID da quota e o valor atual da quota 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 quota é V2-TPUS-per-project-region e o valor atual quotaValue é 20.

  3. Reduza a quota de TPUs em cada região para 10 com um CreateQuotaPreferenceRequest. Defina o 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 o seguinte:

    • PROJECT_NUMBER: o identificador exclusivo do seu projeto.
    • JUSTIFICATION: uma string opcional que explica o seu pedido.
    • EMAIL: um endereço de email que pode ser usado como contacto, caso a Google Cloud precise de mais informações antes de poder conceder quota adicional.

  4. Confirme o novo valor da quota com uma chamada GetQuotaInfo que define o ID da quota 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.

    Segue-se um exemplo de resposta. O valor 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"
      ]
  }
]

Copie as preferências de quota para outro projeto

O exemplo seguinte copia todas as preferências de quota de um projeto para outro. Está escrito em Java, mas 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 quota para o projeto de origem.

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

    • name: o campo de nome atualizado é retirado 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: estes campos podem ser retirados diretamente da resposta tal como estão.

    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 estado das preferências de quota para o projeto de destino:

    GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences

    Substitua PROJECT_NUMBER2 pelo número do projeto do seu projeto de destino.

Liste os pedidos de quota pendentes

Para listar todos os pedidos de preferência de quota pendentes para 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 a este pedido devolve a preferência de quota pendente mais recente. Uma vez que a API Cloud Quotas é uma API declarativa, o sistema tenta satisfazer a preferência de quota mais recente.

Uma resposta de exemplo tem um aspeto semelhante ao seguinte:

  "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"
    }
  ]

Peça aumentos da quota do grupo

Para pedir aumentos para um grupo de quotas num novo projeto, armazene as quotas preferenciais para o novo projeto num ficheiro CSV com os seguintes valores: nome do serviço, ID da quota, valor da quota preferencial e dimensões.

Para cada linha no ficheiro 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.

Uma vez que o projeto de destino é novo, é seguro chamar o método CreateQuotaPreference à medida que lê e atribui os campos. Em alternativa, pode chamar o método UpdateQuotaPreference com allow_missing definido como true.

O método buildYourOwnQuotaPreferenceId cria um ID de preferência de quota a partir do nome do serviço, do ID de quota e de um mapa de dimensões de acordo com o seu esquema de nomenclatura. Em alternativa, pode optar por não definir o ID de preferência de quota. É gerado um ID de preferência de quota para si.

Peça ajustes em quotas que não têm utilização

Para quotas que ainda não tenham utilização de quotas e que tenham dimensões específicas do serviço, como vm_family, é possível que essas quotas não estejam visíveis na consola Google Cloud . Em alternativa, pode ter de usar a API Cloud Quotas.

Por exemplo, pode clonar um projeto e saber antecipadamente que tem de aumentar o valor de compute.googleapis.com/gpus_per_gpu_family. Este valor só aparece na Google Cloud consola para famílias de GPUs que já usou. Para usar a API Cloud Quotas para pedir um aumento das GPUs NVIDIA_H100 em us-central1, pode enviar um pedido como o seguinte:

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 o seguinte:

  • PROJECT_NUMBER: o identificador exclusivo do seu projeto.
  • JUSTIFICATION: uma string opcional que explica o seu pedido.
  • EMAIL: um endereço de email que pode ser usado como contacto, caso a equipa do Google Cloud precise de mais informações antes de poder conceder quota adicional. Google Cloud

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

Obtenha informações sobre a quota para uma dimensão específica do serviço

A família de GPUs é uma dimensão específica do serviço. O pedido de exemplo seguinte usa o ID da quota GPUS-PER-GPU-FAMILY-per-project-region para obter 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.

Esta é uma resposta de exemplo. Para cada chave gpu_family única, o quotaValue e o 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"
        ]
    }
]

Crie uma preferência de quota para uma dimensão específica do serviço

O exemplo seguinte demonstra como criar uma quota para uma determinada região e família de GPUs com um valor preferencial de 100. A localização de destino é especificada no mapa de dimensões com a chave region e a família de GPUs de destino com a chave gpu_family.

O CreateQuotaPreference exemplo seguinte especifica uma família de GPUs 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 o seguinte:

  • PROJECT_NUMBER: o identificador exclusivo do seu projeto.
  • JUSTIFICATION: uma string opcional que explica o seu pedido.
  • EMAIL: um endereço de email que pode ser usado como contacto, caso a equipa do Google Cloud precise de mais informações antes de poder conceder quota adicional. Google Cloud

Atualize uma preferência de quota para uma dimensão específica do serviço

O seguinte exemplo de código obtém o valor atual da dimensão {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, e, em seguida, define o valor preferencial para o dobro do valor. Está escrito em Java, mas 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 do seu projeto.

O que se segue?