Mettre en œuvre des cas d'utilisation courants

Ce document explique comment implémenter des cas d'utilisation courants à l'aide de l'API Cloud Quotas. Cette API vous permet d'ajuster de manière automatisée des quotas et d'automatiser les ajustements de quota dans vos projets, dossiers ou organisations Google Cloud .

Pour en savoir plus, consultez la présentation et la documentation de référence de l'API Cloud Quotas.

Limites

Cloud Quotas présente les limites suivantes :

  • Dans la plupart des cas, les ajustements d'augmentation de quota doivent être effectués au niveau du projet. Un nombre limité de produits acceptent les ajustements d'augmentation de quota au niveau de l'organisation. Pour savoir si un produit Google Cloud accepte les ajustements d'augmentation de quota au niveau de l'organisation, consultez la documentation de ce produit.

  • Vous pouvez demander des ajustements de diminution de quota pour les quotas au niveau du projet, de l'organisation et du dossier.

Suivre l'utilisation et demander une augmentation lorsque l'utilisation est supérieure à 80 %

Cet exemple suit l'utilisation du quota avec Cloud Monitoring, puis demande une augmentation lorsque l'utilisation est supérieure à 80 %.

  1. Appelez la ressource QuotaInfo de votre service pour déterminer la valeur quotaValue actuelle. Dans cet exemple, le service est compute.googleapis.com :

    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos

    Remplacez PROJECT_NUMBER par le numéro de votre projet.

  2. Pour trouver les processeurs par projet et les emplacements applicables, recherchez l'ID de quota CPUS-per-project-region dans la réponse QuotaInfo. La valeur quotaValue est de 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. Appelez l'API Cloud Monitoring pour connaître l'utilisation du quota. Dans l'exemple suivant, la région us-central1 a été spécifiée. Les métriques de quota compatibles sont répertoriées sous 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. Pour déterminer votre utilisation, gérez la réponse de l'API Cloud Monitoring. Comparez la valeur de Cloud Monitoring à quotaValue dans les étapes précédentes pour déterminer l'utilisation.

    Dans l'exemple de réponse suivant, la valeur d'utilisation dans Cloud Monitoring est de 19 dans la région us-central1. La valeur quotaValue pour toutes les régions est 20. L'utilisation est supérieure à 80 % du quota, et une mise à jour des préférences de quota peut être effectuée.

    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. Pour éviter les préférences de quota en double, appelez d'abord ListQuotaPreferences pour vérifier si des requêtes sont en attente. L'option reconciling=true appelle les requêtes en attente.

    GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true

    Remplacez PROJECT_NUMBER par le numéro de votre projet.

  6. Appelez UpdateQuotaPreference pour augmenter la valeur du quota pour la région us-central1. Dans l'exemple suivant, une nouvelle valeur préférée de 100 a été spécifiée.

    Le champ allow_missing est défini sur true. Cela indique au système de créer une ressource QuotaPreference où aucun nom n'existe avec le nom fourni.

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

    Remplacez les éléments suivants :

    • PROJECT_NUMBER : identifiant unique de votre projet.
    • JUSTIFICATION : chaîne facultative expliquant votre requête.
    • EMAIL : adresse e-mail pouvant être utilisée comme contact, au cas où Google Cloud aurait besoin de plus d'informations avant d'accorder un quota supplémentaire.

  7. Appelez GetQuotaPreference pour vérifier l'état de la modification des préférences de quota :

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

    Remplacez PROJECT_NUMBER par le numéro de votre projet.

    Pendant que Google Cloud évalue la valeur de quota demandée, l'état de rapprochement de votre quota est défini sur true.

    Parfois, Google Cloud approuve partiellement votre demande d'augmentation au lieu de l'approuver entièrement. Si la demande est partiellement approuvée, la préférence de quota inclut un champ stateDetail. Le champ stateDetail décrit l'état partiellement approuvé. Le champ grantedValue indique l'ajustement effectué pour répondre partiellement à votre demande.

    Pour savoir si la valeur accordée est la valeur finale approuvée, consultez le champ reconciling. Si votre demande est toujours en cours d'évaluation, le champ reconciling est défini sur true. Si le champ reconciling est défini sur false ou est omis, la valeur accordée est la valeur finale approuvée.

    Dans l'exemple suivant, la valeur du quota demandée est de 100 et le champ reconciling indique que la demande est en cours d'examen.

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

    Une fois les préférences de quota traitées, le champ reconciling est défini sur false. La valeur grantedValue est identique à preferredValue. Le quota préféré est entièrement accordé.

    Lorsque Google Cloud refuse ou approuve partiellement une demande client, la valeur de quota accordée peut toujours être inférieure à la valeur préférée.

Réduire un quota

L'exemple suivant réduit le nombre de TPU à 10 dans chaque région.

  1. Obtenez l'ID de quota et la valeur actuelle du quota avec un appel ListQuotaInfos :

    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos

    Remplacez PROJECT_NUMBER par le numéro de votre projet.

  2. Parcourez les champs de réponse pour rechercher une entrée QuotaInfo pour 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"
              ]
          }
      ]
  },
  ...
]

    Dans cette réponse, l'ID de quota est V2-TPUS-per-project-region et la valeur quotaValue actuelle est de 20.

  3. Réduisez le quota de TPU à chaque région à 10 avec un CreateQuotaPreferenceRequest. Définissez preferredValue sur 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"
}

    Remplacez les éléments suivants :

    • PROJECT_NUMBER : identifiant unique de votre projet.
    • JUSTIFICATION : chaîne facultative expliquant votre requête.
    • EMAIL : adresse e-mail pouvant être utilisée comme contact, au cas où Google Cloud aurait besoin de plus d'informations avant d'accorder un quota supplémentaire.

  4. Confirmez la nouvelle valeur du quota avec un appel GetQuotaInfo qui définit l'ID de quota sur V2-TPUS-per-project-region.

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

    Remplacez PROJECT_NUMBER par le numéro de votre projet.

    Voici un exemple de réponse, la valeur de value est 10 et s'applique dans toutes les régions.

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

Copier les préférences de quota dans un autre projet

L'exemple suivant copie toutes les préférences de quota d'un projet à un autre. Il est écrit en Java, mais vous pouvez utiliser n'importe quel langage de programmation.

  1. Appelez ListQuotaPreferences sur le projet source sans filtre :

    GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences

    PROJECT_NUMBER1 est le numéro du projet source. La réponse contient toutes les préférences de quota pour le projet source.

  2. Pour chaque préférence de quota dans la réponse, appelez UpdateQuotaPreference et définissez les champs suivants :

    • name : le champ de nom mis à jour est extrait de la réponse et le numéro de projet source (PROJECT_NUMBER1) est remplacé par le numéro de projet de destination (PROJECT_NUMBER2).

    • service, quotaId, preferredValue, dimensions : ces champs peuvent être directement récupérés de la réponse telle quelle.

    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. Appelez ListQuotaPreferences pour vérifier l'état des préférences de quota pour le projet de destination :

    GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences

    Remplacez PROJECT_NUMBER2 par le numéro de votre projet de destination.

Répertorier les demandes de quota en attente

Pour répertorier toutes les requêtes de préférence de quota en attente pour un projet, appelez ListQuotaPreferences avec le filtre reconciling=true.

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

Remplacez PROJECT_NUMBER par le numéro de votre projet.

La réponse à cette requête renvoie la dernière préférence de quota en attente. Étant donné que l'API Cloud Quotas est une API déclarative, la dernière préférence de quota est celle que le système tente de remplir.

Un exemple de réponse ressemble à ce qui suit :

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

Demander une augmentation du quota des groupes

Pour demander des augmentations pour un groupe de quotas dans un nouveau projet, stockez les quotas préférés du nouveau projet dans un fichier CSV avec les valeurs suivantes : nom du service, ID du quota, valeur du quota préféré, dimensions.

Pour chaque ligne du fichier CSV, lisez le contenu dans les champs serviceName, quotaId, preferredValue et 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);

Remplacez PROJECT_NUMBER par le numéro de votre projet.

Étant donné que le projet cible est nouveau, vous pouvez appeler en toute sécurité la méthode CreateQuotaPreference lorsque vous lisez et attribuez des champs. Vous pouvez également appeler la méthode UpdateQuotaPreference avec le paramètre allow_missing défini sur true.

La méthode buildYourOwnQuotaPreferenceId crée un ID de préférence de quota à partir du nom du service, de l'ID de quota et d'un mappage des dimensions en fonction de votre schéma de nommage. Vous pouvez également choisir de ne pas définir d'ID de préférence de quota. Un ID de préférence de quota est généré pour vous.

Demander des ajustements pour des quotas qui ne sont pas utilisés

Il est possible que les quotas qui n'ont pas encore été utilisés et qui possèdent des dimensions spécifiques au service, comme vm_family, ne soient pas visibles dans la console Google Cloud . Vous devrez peut-être utiliser l'API Cloud Quotas à la place.

Par exemple, vous pouvez cloner un projet et savoir à l'avance que vous devez augmenter la valeur de compute.googleapis.com/gpus_per_gpu_family. Cette valeur n'apparaît dans la console Google Cloud que pour les familles de GPU que vous avez déjà utilisées. Pour utiliser l'API Cloud Quotas afin de demander une augmentation des GPU NVIDIA_H100 dans us-central1, vous pouvez envoyer une requête semblable à ce qui suit :

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

Remplacez les éléments suivants :

  • PROJECT_NUMBER : identifiant unique de votre projet.
  • JUSTIFICATION : chaîne facultative expliquant votre requête.
  • EMAIL : adresse e-mail pouvant être utilisée comme contact, au cas où Google Cloud aurait besoin de plus d'informations avant d'accorder un quota supplémentaire.

Pour en savoir plus, consultez également les descriptions des sections Priorité des dimensions et de Combiner des dimensions.

Obtenir des informations sur le quota d'une dimension spécifique au service

La famille de GPU est une dimension spécifique au service. L'exemple de requête suivant utilise l'ID de quota GPUS-PER-GPU-FAMILY-per-project-region pour obtenir la ressource QuotaInfo.

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

Remplacez PROJECT_NUMBER par le numéro de votre projet.

Ceci est un exemple de réponse. Pour chaque clé gpu_family unique, quotaValue et applicableLocations sont différents :

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

Créer une préférence de quota pour une dimension spécifique au service

L'exemple suivant montre comment créer un quota pour une région et une famille de GPU données avec une valeur préférée de 100. L'emplacement cible est spécifié dans le mappage des dimensions avec la clé region, et la famille du GPU cible avec la clé gpu_family.

L'exemple CreateQuotaPreference suivant spécifie une famille de GPU NVIDIA_H100 et une région 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"
}

Remplacez les éléments suivants :

  • PROJECT_NUMBER : identifiant unique de votre projet.
  • JUSTIFICATION : chaîne facultative expliquant votre requête.
  • EMAIL : adresse e-mail pouvant être utilisée comme contact, au cas où Google Cloud aurait besoin de plus d'informations avant d'accorder un quota supplémentaire.
Pour ajuster les dimensions de vos préférences de quota, procédez comme suit :

Mettre à jour une préférence de quota pour une dimension spécifique au service

L'exemple de code suivant obtient la valeur actuelle de la dimension {"region" : "us-central1"; gpu_family:"NVIDIA_H100"},, puis définit la valeur préférée sur le double de cette valeur. Il est écrit en Java, mais vous pouvez utiliser n'importe quel langage de programmation.

// 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);

Remplacez PROJECT_NUMBER par l'identifiant unique de votre projet.

Étape suivante