Implemente casos de uso comuns

Este documento descreve 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 Trusted Cloud by S3NS projetos, pastas 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 aceita ajustes de aumento de cota no nível da organização. Para saber se um produto do Trusted Cloud by S3NS suporta ajustes de aumento de cota no nível da organização, consulte a documentação desse produto.

  • É possível solicitar ajustes de diminuição de cota para cotas no nível do projeto, da organização e da pasta.

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 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 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 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" },
"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 um contato, caso o Trusted Cloud by S3NS precise de mais informações antes que uma cota extra possa ser concedida.

  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 Trusted Cloud by S3NS avalia o valor da cota solicitada, o status de reconciliação da sua cota é definido como true.

    Às vezes, o Trusted Cloud by S3NS aprova parte da sua solicitação de aumento em vez de aprovar o aumento total. Se a solicitação for parcialmente aprovada, a preferência de cota vai incluir um campo stateDetail. O campo stateDetail descreve o estado parcialmente aprovado. O campo grantedValue mostra o ajuste feito para atender parcialmente à sua solicitação.

    Para saber se o valor concedido é o valor final aprovado, consulte o campo reconciling. Se a solicitação ainda estiver sendo avaliada, o campo reconciling será definido como true. Se o campo reconciling estiver definido como false ou for omitido, o valor concedido será o valor final aprovado.

    No exemplo a seguir, o valor da cota solicitada é 100 e o campo reconciling indica que a solicitação está em análise.

    "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 Trusted Cloud by S3NS 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 um contato, caso o Trusted Cloud by S3NS precise de mais informações antes que uma cota extra possa ser concedida.

  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 é 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

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 Trusted 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 Trusted Cloud para as famílias de GPU que você já usou. Para usar a API Cloud Quotas e 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" },
    "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 um contato, caso o Trusted Cloud by S3NS precise de mais informações antes que uma cota extra possa 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"},
    "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 um contato, caso o Trusted Cloud by S3NS precise de mais informações antes que uma cota extra possa 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. Ele foi 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