Mengimplementasikan kasus penggunaan umum

Dokumen ini menjelaskan cara menerapkan kasus penggunaan umum menggunakan Cloud Quotas API. API ini memungkinkan Anda menyesuaikan kuota secara terprogram dan mengotomatiskan penyesuaian kuota di project, folder, atau organisasi Google Cloud .

Untuk mempelajari lebih lanjut, lihat ringkasan dan referensi Cloud Quotas API.

Batasan

Cloud Quotas memiliki batasan berikut:

  • Dalam sebagian besar kasus, penyesuaian peningkatan kuota harus dilakukan di tingkat project. Sejumlah produk terbatas mendukung penyesuaian peningkatan kuota tingkat organisasi. Untuk melihat apakah produk mendukung penyesuaian peningkatan kuota tingkat organisasi, lihat dokumentasi untuk produk tersebut. Google Cloud

  • Anda dapat meminta penyesuaian penurunan kuota untuk kuota tingkat project, organisasi, dan folder.

Lacak penggunaan dan minta peningkatan saat penggunaan melebihi 80%

Contoh ini melacak penggunaan kuota dengan Cloud Monitoring, lalu meminta penambahan kuota saat penggunaan melebihi 80%.

  1. Panggil resource QuotaInfo untuk layanan Anda guna menentukan quotaValue saat ini. Layanan dalam contoh ini adalah compute.googleapis.com:

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

    Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

  2. Untuk menemukan CPU per project dan lokasi yang berlaku, lihat respons QuotaInfo untuk ID kuota CPUS-per-project-region. The quotaValue adalah 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. Panggil Cloud Monitoring API untuk menemukan penggunaan kuota. Dalam contoh berikut, region us-central1 telah ditentukan. Metrik kuota yang didukung tercantum di bagian 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. Untuk menentukan penggunaan Anda, tangani respons dari Cloud Monitoring API. Bandingkan nilai dari Cloud Monitoring dengan quotaValue pada langkah-langkah sebelumnya untuk menentukan penggunaan.

    Dalam contoh respons berikut, nilai penggunaan di Cloud Monitoring adalah 19 di region us-central1. quotaValue untuk semua wilayah adalah 20. Penggunaan lebih dari 80% kuota, dan pembaruan preferensi kuota dapat dimulai.

    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. Untuk menghindari preferensi kuota yang duplikat, panggil ListQuotaPreferences terlebih dahulu untuk memeriksa apakah ada permintaan yang menunggu keputusan. Flag reconciling=true memanggil permintaan yang menunggu keputusan.

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

    Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

  6. Panggil UpdateQuotaPreference untuk meningkatkan nilai kuota untuk region us-central1. Dalam contoh berikut, nilai pilihan baru 100 telah ditentukan.

    Kolom allow_missing ditetapkan ke true. Tindakan ini memberi tahu sistem untuk membuat resource QuotaPreference jika tidak ada resource dengan nama yang diberikan.

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

    Ganti kode berikut:

    • PROJECT_NUMBER: ID unik untuk project Anda.
    • JUSTIFICATION: String opsional yang menjelaskan permintaan Anda.
    • EMAIL: Alamat email yang dapat digunakan sebagai kontak, jika Google Cloud membutuhkan informasi lebih lanjut sebelum kuota tambahan dapat diberikan.

  7. Panggil GetQuotaPreference untuk memeriksa status perubahan preferensi kuota:

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

    Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

    Saat Google Cloud mengevaluasi nilai kuota yang diminta, status rekonsiliasi kuota Anda ditetapkan ke true.

    Terkadang Google Cloud menyetujui sebagian permintaan kenaikan Anda, bukan menyetujui kenaikan penuh. Jika permintaan disetujui sebagian, preferensi kuota menyertakan kolom stateDetail. Kolom stateDetail menjelaskan status disetujui sebagian. Kolom grantedValue menampilkan penyesuaian yang dilakukan untuk memenuhi sebagian permintaan Anda.

    Untuk melihat apakah nilai yang diberikan adalah nilai akhir yang disetujui, lihat kolom reconciling. Jika permintaan Anda masih dalam evaluasi, kolom reconciling akan ditetapkan ke true. Jika kolom reconciling ditetapkan ke false atau tidak ada, nilai yang diberikan adalah nilai akhir yang disetujui.

    Dalam contoh berikut, nilai kuota yang diminta adalah 100 dan kolom reconciling menunjukkan bahwa permintaan sedang dalam peninjauan.

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

    Setelah preferensi kuota diproses, kolom reconciling ditetapkan ke false. grantedValue sama dengan preferredValue. Kuota pilihan diberikan sepenuhnya.

    Saat Google Cloud menolak atau menyetujui sebagian permintaan pelanggan, nilai kuota yang diberikan masih dapat kurang dari nilai yang diinginkan.

Mengurangi kuota

Contoh berikut mengurangi jumlah TPU menjadi 10 di setiap region.

  1. Dapatkan ID kuota dan nilai kuota saat ini dengan panggilan ListQuotaInfos:

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

    Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

  2. Periksa kolom respons untuk menemukan entri QuotaInfo untuk 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"
              ]
          }
      ]
  },
  ...
]

    Dalam respons ini, ID kuotanya adalah V2-TPUS-per-project-region, dan quotaValue saat ini adalah 20.

  3. Kurangi kuota TPU di setiap region menjadi 10 dengan CreateQuotaPreferenceRequest. Setel preferredValue ke 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"
}

    Ganti kode berikut:

    • PROJECT_NUMBER: ID unik untuk project Anda.
    • JUSTIFICATION: String opsional yang menjelaskan permintaan Anda.
    • EMAIL: Alamat email yang dapat digunakan sebagai kontak, jika Google Cloud membutuhkan informasi lebih lanjut sebelum kuota tambahan dapat diberikan.

  4. Konfirmasi nilai kuota baru dengan panggilan GetQuotaInfo yang menentukan ID kuota sebagai V2-TPUS-per-project-region.

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

    Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

    Berikut adalah contoh respons, value adalah 10 dan berlaku di semua region.

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

Menyalin preferensi kuota ke project lain

Contoh berikut menyalin semua preferensi kuota dari satu project ke project lain. Ditulis dalam Java, tetapi Anda dapat menggunakan bahasa pemrograman apa pun.

  1. Panggil ListQuotaPreferences di project sumber tanpa filter:

    GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences

    PROJECT_NUMBER1 adalah nomor project untuk project sumber. Respons berisi semua preferensi kuota untuk project sumber.

  2. Untuk setiap preferensi kuota dalam respons, panggil UpdateQuotaPreference dan tentukan kolom berikut:

    • name - Kolom nama yang diperbarui diambil dari respons, dan nomor project sumber (PROJECT_NUMBER1) diganti dengan nomor project tujuan (PROJECT_NUMBER2).

    • service, quotaId, preferredValue, dimensions - Kolom ini dapat diambil langsung dari respons apa adanya.

    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. Panggil ListQuotaPreferences untuk memverifikasi status preferensi kuota untuk project tujuan:

    GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences

    Ganti PROJECT_NUMBER2 dengan nomor project untuk project tujuan Anda.

Mencantumkan permintaan kuota yang menunggu keputusan

Untuk mencantumkan semua permintaan preferensi kuota yang tertunda untuk suatu project, panggil ListQuotaPreferences dengan filter reconciling=true.

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

Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

Respons untuk permintaan ini menampilkan preferensi kuota tertunda terbaru. Karena Cloud Quotas API adalah API deklaratif, preferensi kuota terbaru adalah yang coba dipenuhi oleh sistem.

Contoh responsnya akan terlihat seperti berikut:

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

Meminta penambahan kuota grup

Untuk meminta penambahan kuota untuk sekelompok kuota dalam project baru, simpan kuota pilihan untuk project baru dalam file CSV dengan nilai berikut: nama layanan, ID kuota, nilai kuota pilihan, dimensi.

Untuk setiap baris dalam file CSV, baca konten ke dalam kolom serviceName, quotaId, preferredValue, dan 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);

Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

Karena project target baru, Anda dapat memanggil metode CreateQuotaPreference dengan aman saat membaca dan menetapkan kolom. Atau, Anda dapat memanggil metode UpdateQuotaPreference dengan allow_missing yang ditetapkan ke true.

Metode buildYourOwnQuotaPreferenceId membuat ID preferensi kuota dari nama layanan, ID kuota, dan peta dimensi sesuai dengan skema penamaan Anda. Atau, Anda dapat memilih untuk tidak menetapkan ID preferensi kuota. ID preferensi kuota dibuat untuk Anda.

Meminta penyesuaian pada kuota yang tidak digunakan

Untuk kuota yang belum memiliki penggunaan kuota dan memiliki dimensi khusus layanan seperti vm_family, kuota tersebut mungkin tidak terlihat di konsol Google Cloud . Anda mungkin perlu menggunakan Cloud Quotas API sebagai gantinya.

Misalnya, Anda dapat meng-clone project dan mengetahui sebelumnya bahwa Anda perlu menaikkan nilai untuk compute.googleapis.com/gpus_per_gpu_family. Nilai ini hanya muncul di konsol Google Cloud untuk keluarga GPU yang telah Anda gunakan. Untuk menggunakan Cloud Quotas API guna meminta peningkatan GPU NVIDIA_H100 di us-central1, Anda dapat mengirim permintaan seperti berikut:

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

Ganti kode berikut:

  • PROJECT_NUMBER: ID unik untuk project Anda.
  • JUSTIFICATION: String opsional yang menjelaskan permintaan Anda.
  • EMAIL: Alamat email yang dapat digunakan sebagai kontak, jika Google Cloud membutuhkan informasi lebih lanjut sebelum kuota tambahan dapat diberikan.

Untuk mengetahui informasi selengkapnya, lihat juga deskripsi Prioritas dimensi dan Menggabungkan dimensi.

Mendapatkan info kuota untuk dimensi spesifik layanan

Seri GPU adalah dimensi khusus layanan. Contoh permintaan berikut menggunakan ID kuota GPUS-PER-GPU-FAMILY-per-project-region untuk mendapatkan resource QuotaInfo.

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

Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

Ini adalah contoh respons. Untuk setiap kunci gpu_family yang unik, quotaValue dan applicableLocations berbeda:

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

Membuat preferensi kuota untuk dimensi khusus layanan

Contoh berikut menunjukkan cara membuat kuota untuk region dan keluarga GPU tertentu dengan nilai pilihan 100. Lokasi target ditentukan dalam peta dimensi dengan kunci region, dan keluarga GPU target dengan kunci gpu_family.

Contoh CreateQuotaPreference berikut menentukan keluarga GPU NVIDIA_H100 dan region 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"
}

Ganti kode berikut:

  • PROJECT_NUMBER: ID unik untuk project Anda.
  • JUSTIFICATION: String opsional yang menjelaskan permintaan Anda.
  • EMAIL: Alamat email yang dapat digunakan sebagai kontak, jika Google Cloud membutuhkan informasi lebih lanjut sebelum kuota tambahan dapat diberikan.

Memperbarui preferensi kuota untuk dimensi khusus layanan

Contoh kode berikut mendapatkan nilai saat ini untuk dimensi {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, lalu menetapkan nilai pilihan menjadi dua kali lipat nilai tersebut. Ditulis dalam Java, tetapi Anda dapat menggunakan bahasa pemrograman apa pun.

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

Ganti PROJECT_NUMBER dengan ID unik untuk project Anda.

Langkah berikutnya