Mettre en œuvre des cas d'utilisation courants

Vous trouverez sur cette page la procédure à suivre pour mettre en œuvre des cas d'utilisation courants utilisant 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

L'API Cloud Quotas présente les limites suivantes :

L'API n'est pas compatible avec Google Cloud CLI.
L'API accepte les ajustements de quota pour les quotas au niveau des projets. Des quotas peuvent être demandés pour les quotas au niveau du projet, du dossier et de l'organisation.
L'API n'est pas compatible avec VPC Service Controls.

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

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.

Pour trouver les processeurs par projet et les emplacements applicables, recherchez l'ID de quota CPUS-per-project-region dans la réponse QuotaInfo. quotaValue est défini sur 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"
                ]
            }
        ]
    },
      …
]

Ce résultat inclut les valeurs suivantes :

PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.

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

Ce résultat inclut les valeurs suivantes :

PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.

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

Ce résultat inclut les valeurs suivantes :

PROJECT_ID : identifiant unique global pour votre projet.

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.
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": [
    "mapField": {
    "key": "region",
    "value": "us-central1"
    }
    ],
    }
```
Ce résultat inclut les valeurs suivantes :
- PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.
Pour ajuster les dimensions de votre préférence de quota, procédez comme suit :
- Si vous souhaitez que les préférences de quota s'appliquent à toutes les régions, supprimez les informations régionales.
- Si votre quota est défini par zone, remplacez les informations régionales par les informations de zone.
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 est défini sur 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": [
    "mapField": {
        "key": "region",
        "value": "us-central1"
    }
],
"reconciling": true
"createTime": "2023-01-15T01:30:15.01Z",
"updateTime": "2023-01-16T02:35:16.01Z"
```
Ce résultat inclut les valeurs suivantes :
- PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.
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.

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 projet de votre projet.

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

Ce résultat inclut les valeurs suivantes :

PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.

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

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

Ce résultat inclut les valeurs suivantes :

PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.

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

Ce résultat inclut les valeurs suivantes :

PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.

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.

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.

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())
        .setQuotaConfig(
            QuotaConfig.newBuilder().setPreferredValue(srcPreference.getQuotaConfig().getPreferredValue()))
        .putAllDimensions(srcPreference.getDimensionsMap());
    UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
    cloudQuotas.updateQuotaPreference(updateRequest);
}

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.

Voici un exemple de réponse :

"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": [
            "map_field": {
                "key": "region",
                "value": "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"
    }
]

Ce résultat inclut les valeurs suivantes :

PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.

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

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": [
            "mapField": {
                "key": "region",
                "value": "us-central1"
            },
            "mapField": {
                "key": "gpu_family",
                "value": "NVIDIA_H200"
            }
        ],
        "details": {
            "quotaValue": 30,
            "resetValue": 30,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": [
            "mapField": {
                "key": "region",
                "value": "us-central1"
            }
        ],
        "details": {
            "quotaValue": 100,
            "resetValue": 100,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": [
            "mapField": {
                "key": "gpu_familly",
                "value": "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"
        ]
    }
]

Ce résultat inclut les valeurs suivantes :

PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.

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. Remplacez PROJECT_NUMBER par le numéro de votre projet.

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": [
        "mapField": {
            "key": "region",
            "value": "us-central1"
        }
          "mapField": {
            "key": "gpu_family",
            "value": "NVIDIA_H100"
        }
    ],
}

Pour ajuster les dimensions de votre préférence 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 pour les dimensions {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, puis définit la valeur préférée sur le double de cette valeur. Remplacez PROJECT_NUMBER par le numéro de votre projet.

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

Étapes suivantes

À propos de l'API Cloud Quotas
Documentation de référence de l'API Cloud Quotas
Comprendre les quotas