Implementare casi d'uso comuni

Questo documento descrive come implementare i casi d'uso comuni utilizzando l'API Cloud Quotas. Questa API ti consente di modificare in modo programmatico le quote e automatizzare gli aggiustamenti delle quote nei tuoi progetti, nelle tue cartelle o nella tua organizzazione Trusted Cloud by S3NS .

Per saperne di più, consulta la panoramica e il riferimento dell'API Cloud Quotas.

Limitazioni

Cloud Quotas presenta le seguenti limitazioni:

  • Nella maggior parte dei casi, gli aggiustamenti dell'aumento della quota devono essere apportati a livello di progetto. Un numero limitato di prodotti supporta gli aggiustamenti dell'aumento della quota a livello di organizzazione. Per verificare se un prodotto Trusted Cloud by S3NS supporta gli aggiustamenti dell'aumento della quota a livello di organizzazione, consulta la documentazione di quel prodotto.

  • Puoi richiedere aggiustamenti per la riduzione delle quote a livello di progetto, organizzazione e cartella.

Monitorare l'utilizzo e richiedere un aumento quando l'utilizzo supera l'80%

Questo esempio monitora l'utilizzo della quota con Cloud Monitoring e poi richiede un aumento quando l'utilizzo supera l'80%.

  1. Chiama la risorsa QuotaInfo per il tuo servizio per determinare l'attuale quotaValue. Il servizio in questo esempio è compute.googleapis.com:

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

    Sostituisci PROJECT_NUMBER con il numero del progetto.

  2. Per trovare le CPU per progetto e le località applicabili, esamina la risposta QuotaInfo per l'ID quota CPUS-per-project-region. Il valore 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. Chiama l'API Cloud Monitoring per trovare l'utilizzo della quota. Nell'esempio seguente è stata specificata la regione us-central1. Le metriche delle quote supportate sono elencate in 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. Per determinare l'utilizzo, gestisci la risposta dell'API Cloud Monitoring. Confronta il valore di Cloud Monitoring con quotaValue nei passaggi precedenti per determinare l'utilizzo.

    Nella seguente risposta di esempio, il valore di utilizzo in Cloud Monitoring è 19 nella regione us-central1. Il valore di quotaValue per tutte le regioni è 20. L'utilizzo è superiore all'80% della quota e può essere avviato un aggiornamento delle preferenze di 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. Per evitare preferenze di quota duplicate, chiama prima ListQuotaPreferences per verificare se sono presenti richieste in attesa. Il flag reconciling=true chiama richieste in attesa.

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

    Sostituisci PROJECT_NUMBER con il numero del tuo progetto.

  6. Chiama il numero UpdateQuotaPreference per aumentare il valore della quota per la regione us-central1. Nell'esempio seguente, è stato specificato un nuovo valore preferito di 100.

    Il campo allow_missing è impostato su true. In questo modo, il sistema crea una risorsa QuotaPreference se non ne esiste una con il nome fornito.

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

    Sostituisci quanto segue:

    • PROJECT_NUMBER: l'identificatore univoco del tuo progetto.
    • JUSTIFICATION: Una stringa facoltativa che spiega la tua richiesta.
    • EMAIL: un indirizzo email che può essere utilizzato come contatto, nel caso in cui Trusted Cloud by S3NS abbia bisogno di ulteriori informazioni prima che possa essere concessa una quota aggiuntiva.

  7. Chiama il numero GetQuotaPreference per controllare lo stato della modifica della preferenza di quota:

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

    Sostituisci PROJECT_NUMBER con il numero del tuo progetto.

    Mentre Trusted Cloud by S3NS valuta il valore della quota richiesto, lo stato di riconciliazione della quota è impostato su true.

    A volte Trusted Cloud by S3NS approva una parte della tua richiesta di aumento anziché approvare l'aumento completo. Se la richiesta viene approvata parzialmente, la preferenza di quota include un campo stateDetail. Il campo stateDetail descrive lo stato di approvazione parziale. Il campo grantedValue mostra l'aggiustamento apportato per soddisfare parzialmente la tua richiesta.

    Per verificare se il valore concesso è quello finale approvato, controlla il campo reconciling. Se la tua richiesta è ancora in fase di valutazione, il campo reconciling è impostato su true. Se il campo reconciling è impostato su false o viene omesso, il valore concesso è il valore finale approvato.

    Nell'esempio seguente, il valore della quota richiesta è 100 e il campo reconciling indica che la richiesta è in fase di revisione.

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

    Una volta elaborata la preferenza di quota, il campo reconciling viene impostato su false. grantedValue è uguale a preferredValue. La quota preferita è completamente concessa.

    Quando Trusted Cloud by S3NS nega o approva parzialmente una richiesta del cliente, il valore della quota concessa può comunque essere inferiore al valore preferito.

Diminuire una quota

L'esempio seguente riduce il numero di TPU a 10 in ogni regione.

  1. Recupera l'ID quota e il valore della quota attuale con una chiamata ListQuotaInfos:

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

    Sostituisci PROJECT_NUMBER con il numero del progetto.

  2. Esamina i campi di risposta per trovare una voce QuotaInfo per 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"
              ]
          }
      ]
  },
  ...
]

    In questa risposta, l'ID quota è V2-TPUS-per-project-region e l'attuale quotaValue è 20.

  3. Riduci la quota TPU in ogni regione a 10 con un CreateQuotaPreferenceRequest. Imposta preferredValue su 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"
}

    Sostituisci quanto segue:

    • PROJECT_NUMBER: l'identificatore univoco del tuo progetto.
    • JUSTIFICATION: Una stringa facoltativa che spiega la tua richiesta.
    • EMAIL: un indirizzo email che può essere utilizzato come contatto, nel caso in cui Trusted Cloud by S3NS abbia bisogno di ulteriori informazioni prima che possa essere concessa una quota aggiuntiva.

  4. Conferma il nuovo valore della quota con una chiamata GetQuotaInfo che definisce l'ID quota come V2-TPUS-per-project-region.

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

    Sostituisci PROJECT_NUMBER con il numero del progetto.

    Di seguito è riportato un esempio di risposta, il valore di value è 10 ed è applicabile in tutte le regioni.

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

Copia le preferenze di quota in un altro progetto

L'esempio seguente copia tutte le preferenze di quota da un progetto a un altro. È scritto in Java, ma puoi utilizzare qualsiasi linguaggio di programmazione.

  1. Chiama ListQuotaPreferences sul progetto di origine senza filtro:

    GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences

    PROJECT_NUMBER1 è il numero di progetto del progetto di origine. La risposta contiene tutte le preferenze di quota per il progetto di origine.

  2. Per ogni preferenza di quota nella risposta, chiama UpdateQuotaPreference e definisci i seguenti campi:

    • name: il campo del nome aggiornato viene estratto dalla risposta e il numero del progetto di origine (PROJECT_NUMBER1) viene sostituito con il numero del progetto di destinazione (PROJECT_NUMBER2).

    • service, quotaId, preferredValue, dimensions: questi campi possono essere presi direttamente dalla risposta così come sono.

    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. Chiama ListQuotaPreferences per verificare lo stato delle preferenze di quota per il progetto di destinazione:

    GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences

    Sostituisci PROJECT_NUMBER2 con il numero del progetto di destinazione.

Elenca le richieste di quota in attesa

Per elencare tutte le richieste di preferenza di quota in attesa per un progetto, chiama ListQuotaPreferences con il filtro reconciling=true.

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

Sostituisci PROJECT_NUMBER con il numero del tuo progetto.

La risposta a questa richiesta restituisce l'ultima preferenza di quota in attesa. Poiché l'API Cloud Quotas è un'API dichiarativa, il sistema tenta di soddisfare l'ultima preferenza di quota.

Una risposta di esempio è simile alla seguente:

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

Richiedere aumenti della quota di gruppo

Per richiedere aumenti per un gruppo di quote in un nuovo progetto, memorizza le quote preferite per il nuovo progetto in un file CSV con i seguenti valori: nome del servizio, ID quota, valore della quota preferita, dimensioni.

Per ogni riga del file CSV, leggi i contenuti nei campi 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);

Sostituisci PROJECT_NUMBER con il numero del tuo progetto.

Poiché il progetto di destinazione è nuovo, è sicuro chiamare il metodo CreateQuotaPreference mentre leggi e assegni i campi. In alternativa, puoi chiamare il metodo UpdateQuotaPreference con allow_missing impostato su true.

Il metodo buildYourOwnQuotaPreferenceId crea un ID preferenza quota dal nome del servizio, dall'ID quota e da una mappa delle dimensioni in base allo schema di denominazione. In alternativa, puoi scegliere di non impostare l'ID preferenza quota. Viene generato un ID preferenza quota.

Richiedere aggiustamenti alle quote senza utilizzo

Per le quote che non hanno ancora un utilizzo e che hanno dimensioni specifiche del servizio, ad esempio vm_family, è possibile che queste quote non siano visibili nella console Trusted Cloud . Potresti dover utilizzare l'API Cloud Quotas.

Ad esempio, potresti clonare un progetto e sapere in anticipo che devi aumentare il valore di compute.googleapis.com/gpus_per_gpu_family. Questo valore viene visualizzato solo nella console Trusted Cloud per le famiglie di GPU che hai già utilizzato. Per utilizzare l'API Cloud Quotas per richiedere un aumento delle GPU NVIDIA_H100 in us-central1, puoi inviare una richiesta come la seguente:

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

Sostituisci quanto segue:

  • PROJECT_NUMBER: l'identificatore univoco del tuo progetto.
  • JUSTIFICATION: Una stringa facoltativa che spiega la tua richiesta.
  • EMAIL: un indirizzo email da utilizzare come contatto, nel caso in cui Trusted Cloud by S3NS abbia bisogno di ulteriori informazioni prima di poter concedere una quota aggiuntiva.

Per ulteriori informazioni, consulta anche le descrizioni di Precedenza delle dimensioni e Combinazione delle dimensioni.

Ottenere informazioni sulla quota per una dimensione specifica del servizio

La famiglia di GPU è una dimensione specifica del servizio. La seguente richiesta di esempio utilizza l'ID quota GPUS-PER-GPU-FAMILY-per-project-region per ottenere la risorsa QuotaInfo.

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

Sostituisci PROJECT_NUMBER con il numero del tuo progetto.

Questa è una risposta di esempio. Per ogni chiave gpu_family univoca, quotaValue e applicableLocations sono diversi:

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

Crea una preferenza di quota per una dimensione specifica del servizio

L'esempio seguente mostra come creare una quota per una determinata regione e famiglia di GPU con un valore preferito di 100. La località di destinazione è specificata nella mappa delle dimensioni con la chiave region e la famiglia di GPU di destinazione con la chiave gpu_family.

L'esempio di CreateQuotaPreference seguente specifica una famiglia di GPU NVIDIA_H100 e una regione 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"
}

Sostituisci quanto segue:

  • PROJECT_NUMBER: l'identificatore univoco del tuo progetto.
  • JUSTIFICATION: Una stringa facoltativa che spiega la tua richiesta.
  • EMAIL: un indirizzo email da utilizzare come contatto, nel caso in cui Trusted Cloud by S3NS abbia bisogno di ulteriori informazioni prima di poter concedere una quota aggiuntiva.

Aggiornare una preferenza di quota per una dimensione specifica del servizio

Il seguente codice campione recupera il valore corrente della dimensione {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, e poi imposta il valore preferito sul doppio del valore. È scritto in Java, ma puoi utilizzare qualsiasi linguaggio di programmazione.

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

Sostituisci PROJECT_NUMBER con l'identificatore univoco del tuo progetto.

Passaggi successivi