Mengimplementasikan kasus penggunaan umum

Halaman 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 Anda.

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

Batasan

Kuota Cloud memiliki batasan berikut:

  • Penyesuaian peningkatan kuota harus dilakukan di tingkat project dan tunduk pada persetujuan Google Cloud.

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

  • Cloud Quotas API hanya mendukung operasi tingkat project. Operasi tingkat folder dan tingkat organisasi tidak didukung.

Melacak penggunaan dan meminta peningkatan jika penggunaan lebih dari 80%

Contoh ini melacak penggunaan kuota dengan Cloud Monitoring, lalu meminta peningkatan saat penggunaannya 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. 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. Pada 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 di langkah sebelumnya untuk menentukan penggunaan.

    Dalam contoh respons berikut, nilai penggunaan di Cloud Monitoring adalah 19 di region us-central1. quotaValue untuk semua region adalah 20. Penggunaan lebih besar dari 80% kuota, dan update 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 duplikat, panggil ListQuotaPreferences terlebih dahulu untuk memeriksa apakah ada permintaan yang tertunda. Flag reconciling=true memanggil permintaan yang tertunda. 
    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 akan memberi tahu sistem untuk membuat resource QuotaPreference jika tidak ada 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" }
}
  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 ditetapkan ke 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": { "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 akan disetel ke false. grantedValue sama dengan preferredValue. Kuota pilihan diberikan sepenuhnya.

    Jika Google Cloud menolak atau menyetujui sebagian permintaan pelanggan, nilai kuota yang diberikan masih dapat lebih rendah 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. Lihat 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 kuota adalah V2-TPUS-per-project-region, dan quotaValue saat ini adalah 20.
  3. Kurangi kuota TPU di setiap region menjadi 10 dengan CreateQuotaPreferenceRequest. Tetapkan 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",
    "contactEmail": EMAIL
}
  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 lainnya. Aplikasi ini 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 ini 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 seperti 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())
        .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 tertunda

Untuk mencantumkan semua permintaan preferensi kuota yang tertunda untuk sebuah 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 terbaru yang tertunda. Karena Cloud Quotas API adalah API deklaratif, preferensi kuota terbaru adalah yang dicoba dipenuhi oleh sistem.

Contoh respons terlihat mirip dengan berikut ini:

  "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 peningkatan kuota untuk sekelompok kuota dalam project baru, simpan kuota yang diinginkan untuk project baru dalam file CSV dengan nilai berikut: nama layanan, ID kuota, nilai kuota yang diinginkan, dimensi.

Untuk setiap baris dalam file CSV, baca konten ke 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)
            .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue))
            .putAllDimensions(dimensionMap))
  .build();
cloudQuotas.createQuotaPreference(request);

Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

Karena project target masih baru, Anda dapat memanggil metode CreateQuotaPreference dengan aman saat membaca dan menetapkan kolom. Atau, Anda dapat memanggil metode UpdateQuotaPreference dengan allow_missing 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 akan 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 meningkatkan 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: Alasan permintaan ini.
  • EMAIL: Alamat email yang dapat digunakan sebagai kontak, jika Google Cloud memerlukan informasi lebih lanjut untuk membuat keputusan sebelum kuota tambahan dapat diberikan.

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

Mendapatkan info kuota untuk dimensi khusus layanan

Grup 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 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"},
    "contactEmail": "EMAIL"
}

Ganti kode berikut:

  • PROJECT_NUMBER: ID unik untuk project Anda.
  • EMAIL: Alamat email yang dapat digunakan sebagai kontak, jika Google Cloud memerlukan informasi lebih lanjut untuk membuat keputusan 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 untuk menggandakan nilai tersebut. Aplikasi ini 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)
        .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 selanjutnya