Dokumen ini menjelaskan cara mengambil dan menggunakan metrik kustom dan eksternal untuk menskalakan Pod secara horizontal.
Untuk mengambil metrik, Anda dapat menggunakan adaptor metrik yang dikelola GKE. Solusi terkelola ini tersedia untuk metrik di Cloud Monitoring yang dapat dikueri dengan PromQL, dan metrik Pod kustom tertentu yang diekspos di bawah endpoint HTTP dalam format Prometheus.
Kemudian, autoscaler workload dapat menggunakan data ini untuk menskalakan workload secara lebih efisien. Misalnya, Anda dapat menggunakan fitur ini untuk memantau kedalaman antrean atau penggunaan cache, lalu mengizinkan penskala otomatis untuk menambah atau mengurangi jumlah Pod. Dari contoh vLLM, metrik yang dapat berguna untuk melacak
pemanfaatan cache adalah vllm:gpu_cache_usage_perc.
Sebagai alternatif untuk adaptor metrik terkelola, untuk menskalakan otomatis menggunakan metrik apa pun, Anda dapat mengambil metrik dengan mengonfigurasi adaptor metrik secara manual untuk mengirim metrik ke autoscaler. Alur kerja ini melibatkan penginstalan adaptor pihak ketiga, seperti Stackdriver Adapter, dan mengonfigurasi izin. Misalnya, lihat tutorial Mengoptimalkan penskalaan otomatis Pod berdasarkan metrik.
Bagian selanjutnya dari dokumen ini berfokus pada adaptor metrik terkelola.
Mengambil metrik
Anda dapat mengambil metrik menggunakan adaptor metrik terkelola dengan cara berikut:
- Metrik pod kustom yang dikeluarkan oleh Pod dapat diambil dalam cluster. Metrik ini dapat digunakan untuk penskalaan otomatis tanpa perlu melewati sistem pemantauan seperti Cloud Monitoring.
- Metrik pod kustom yang disimpan di Cloud Monitoring dapat diambil menggunakan kueri PromQL. Metrik tersebut dipancarkan oleh Pod dan diekspor ke Cloud Monitoring, biasanya menggunakan Google Cloud Managed Service for Prometheus. Dibandingkan dengan metode sebelumnya, pendekatan ini memungkinkan Anda menggunakan fitur PromQL seperti menghitung persentil, atau membaca nilai historis.
- Metrik eksternal dapat diambil dari Cloud Monitoring menggunakan kueri PromQL.
Setelah mengambil metrik, Anda akan mereferensikan metrik tersebut dalam objek HorizontalPodAutoscaler. Untuk mengetahui informasi selengkapnya, lihat bagian Menggunakan metrik di penskalaan otomatis Pod horizontal.
Untuk mengetahui ringkasan tentang penskalaan otomatis berdasarkan metrik, lihat Tentang penskalaan otomatis workload berdasarkan metrik.
Mengambil metrik kustom dalam cluster
Metrik kustom berasal dari layanan atau aplikasi yang Anda jalankan. Untuk melihat salah satu contoh metrik yang diekspos, lihat metrik yang diekspos oleh vLLM Engine.
Persyaratan
Persyaratan untuk Pod adalah sebagai berikut:
- GKE 1.37.0-gke.3100000 dan yang lebih baru. Fitur ini juga tersedia dalam pratinjau untuk GKE versi 1.36.4-gke.1247000 dan yang lebih baru.
- Gunakan penskalaan otomatis Pod horizontal dengan profil performa.
Persyaratan untuk metrik adalah sebagai berikut:
- Metrik harus dipancarkan oleh Pod dalam workload yang diskalakan otomatis.
- Metrik harus dapat diakses di endpoint HTTP. Jalur endpoint secara default adalah
/metrics. - Metrik harus diformat sesuai dengan standar Prometheus.
- Hanya metrik pengukur yang didukung.
- Secara default, maksimum 50 metrik unik dapat diekspos per node. Jika perlu mengekspos lebih banyak metrik, Anda dapat meminta jumlah memori tambahan yang lebih tinggi.
- Jika Anda menggunakan versi pratinjau dari fitur ini, di GKE versi 1.36.4-gke.1247000 hingga versi 1.37.0-gke.3100000, persyaratan tambahan berikut berlaku:
- Nama label dalam pemilih label Pod tidak boleh berisi karakter khusus. Hanya huruf a-z (huruf kecil atau huruf besar), angka, tanda hubung, dan garis bawah yang didukung.
- Saat Anda menggunakan pemfilteran berdasarkan label metrik, kunci label harus
cocok dengan ekspresi reguler
^[a-zA-Z_][a-zA-Z0-9_]*(diawali dengan huruf atau garis bawah, dan hanya berisi huruf, angka, atau garis bawah). - Maksimal 20 metrik unik dapat diekspos per cluster.
Tentukan metrik
Pilih metrik yang akan diekspos. Anda dapat memilih metrik apa pun yang diekspos oleh workload Anda, dan yang juga memenuhi persyaratan yang tercantum di bagian sebelumnya.
Jika workload Anda mengekspos beberapa metrik dengan nama yang sama tetapi label yang berbeda, tambahkan filter label untuk membantu memastikan hanya satu yang dipilih.
Tambahkan resource kustom berikut, dengan mengganti detail yang khusus untuk metrik dan Pod Anda:
apiVersion: autoscaling.gke.io/v1beta1 kind: AutoscalingMetric metadata: name: NAME namespace: NAMESPACE spec: metrics: - pod: selector: matchLabels: APP_LABEL_NAME: APP_LABEL_VALUE containers: - endpoint: port: METRIC_PORT path: METRIC_PATH metrics: - gauge: name: METRIC_NAME prometheusMetricName: METRIC_PROMETHEUS_NAMEGanti yang berikut agar sesuai dengan beban kerja Anda:
NAME: nama objek AutoscalingMetric.NAMESPACE: namespace tempat Pod berada.APP_LABEL_NAMEdanAPP_LABEL_VALUE: nama dan nilai label yang cocok dengan Pod yang memancarkan metrik.METRIC_PORT: nomor port.METRIC_PATH: jalur ke metrik. Verifikasi jalur yang digunakan oleh layanan atau aplikasi Anda; jalur ini sering kali/metrics.METRIC_NAME: nama metrik yang Anda ekspos. Nama harus cocok dengan regular expression^[a-z]([-a-z0-9]*[a-z0-9])?, dan memiliki panjang tidak lebih dari 63 karakter. Ekspresi ini berarti karakter pertama harus berupa huruf kecil, dan semua karakter berikutnya harus berupa tanda hubung, huruf kecil, atau angka. Namun, karakter terakhir tidak boleh berupa tanda hubung.Opsional:
METRIC_PROMETHEUS_NAME: nama metrik Prometheus seperti yang diekspos oleh Pod. Anda dapat menggunakan kolom ini untuk mengganti nama metrik, misalnya, karena nama metrik yang diekspos oleh Pod tidak mematuhi batasan nama yang ditetapkan oleh autoscaler.Untuk mengetahui informasi selengkapnya tentang batasan nama, lihat batasan untuk penskalaan otomatis Pod horizontal. Anda juga dapat memfilter metrik menggunakan label metrik.
Terapkan manifes menggunakan perintah berikut:
kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yamlGanti
FILE_NAME_AUTOSCALING_METRICdengan nama file YAML.Verifikasi definisi metrik dan ambil nama metrik yang akan digunakan untuk objek HorizontalPodAutoscaler:
Jalankan perintah
kubectl describeuntuk resource kustom AutoscalingMetric:kubectl describe autoscalingmetric NAME -n NAMESPACEGanti kode berikut:
NAME: nama objek AutoscalingMetric.NAMESPACE: namespace objek AutoscalingMetric.
Lihat kolom
Status. Jika tidak ada error yang tercantum, berarti objek valid.Salin nama di kolom
HPA Name. Ini adalah nama yang Anda tambahkan ke objek HorizontalPodAutoscaler. Nama ini memiliki format berikut:autoscaling.gke.io|NAME|METRIC_NAME.
Metrik kini ditentukan dalam objek AutoscalingMetric. Untuk melakukan penskalaan otomatis dengan metrik ini, Anda harus mereferensikannya dalam objek HorizontalPodAutoscaler. Untuk mengetahui informasi selengkapnya, lihat bagian Menggunakan metrik dalam objek HorizontalPodAutoscaler.
Saat Anda menambahkan resource kustom, metrik akan dikirim ke API penskalaan otomatis. Metrik dibaca setiap beberapa detik dan dikirim ke penskalaan otomatis workload.
Memfilter metrik menggunakan label metrik
Memfilter metrik menggunakan label metrik tersedia di GKE 1.36.0-gke.1759000 atau yang lebih baru.
Metrik yang dikeluarkan oleh workload Anda sering kali menyertakan label. Label adalah pasangan nilai kunci yang memungkinkan Anda menambahkan dimensi ke nilai. Misalnya, metrik yang menghitung jumlah permintaan ke endpoint HTTP yang dikelompokkan menurut metode dan lingkungan dapat menggunakan label untuk menentukan konteks ini. Contoh ini dapat terlihat seperti berikut:
http_requests_total{method="GET", env="prod"} 11111
http_requests_total{method="PUT", env="staging"} 22222
Anda dapat menggunakan filter label untuk membantu memastikan bahwa spesifikasi metrik Anda cocok dengan satu metrik. Misalnya, untuk memilih hanya metrik pertama dalam contoh sebelumnya, gunakan spesifikasi berikut untuk metrik AutoscalingMetric gauge:
apiVersion: autoscaling.gke.io/v1beta1
kind: AutoscalingMetric
metadata:
name: filter-sample
spec:
# Several lines are omitted here.
metrics:
- gauge:
name: http_requests_total
filter:
matchLabels:
method: GET
env: prod
Kunci pasangan nilai kunci matchLabels harus cocok dengan ekspresi reguler
^[a-zA-Z_][a-zA-Z0-9_]*: yaitu, diawali dengan huruf atau garis bawah, dan
hanya berisi huruf, angka, atau garis bawah.
Mengambil metrik kustom atau eksternal dari Cloud Monitoring
Anda dapat mengambil metrik dari Cloud Monitoring untuk menskalakan beban kerja. GKE mendukung pengambilan dua jenis metrik dari Cloud Monitoring:
- Metrik kustom: gunakan jenis ini untuk menerapkan fitur PromQL, seperti menghitung persentil atau membaca nilai historis, ke metrik yang dikeluarkan oleh beban kerja cluster Anda.
- Metrik eksternal: gunakan jenis ini untuk menskalakan berdasarkan entitas di luar cluster, seperti jumlah pesan yang tertunda pada langganan Pub/Sub.
Jika tidak, ambil metrik kustom dari cluster.
Persyaratan
- GKE versi 1.36.2-gke.2771000 atau yang lebih baru.
- Metrik harus disimpan di Cloud Monitoring. Misalnya, Anda dapat menggunakan Google Cloud Managed Service for Prometheus.
- Maksimum 100 metrik didukung per cluster. Batas ini adalah total gabungan untuk metrik kustom dan eksternal.
- Metrik di Cloud Monitoring harus berada di Google Cloud project yang sama dengan cluster yang diskalakan otomatis.
Tentukan metrik
Anda menggunakan file YAML untuk menentukan metrik, termasuk kueri PromQL tertentu.
Pilih salah satu konfigurasi berikut, bergantung pada apakah Anda mengambil metrik kustom atau metrik eksternal:
Buat objek AutoscalingMetric dan tentukan metrik yang akan diambil.
Metrik kustom (Pod)
apiVersion: autoscaling.gke.io/v1beta1 kind: AutoscalingMetric metadata: name: NAME namespace: NAMESPACE spec: metrics: - promql: name: METRIC_NAME query: PROMQL_QUERY type: Pods # Specifies that the metric is associated with Pods. # metricLabels are optional, default to the labels used by Google # Cloud Managed Service for Prometheus. The defaults are used # below. metricLabels: podName: "pod" namespace: "namespace" clusterName: "cluster" location: "location" projectId: "project_id"Ganti kode berikut:
NAME: nama objek AutoscalingMetric.NAMESPACE: namespace objek AutoscalingMetric, yang harus cocok dengan namespace workload yang ingin Anda skalakan.METRIC_NAME: nama metrik yang digunakan oleh objek HorizontalPodAutoscaler.PROMQL_QUERY: kueri PromQL yang mengkueri metrik. Kueri PromQL harus menampilkan vektor dengan satu entri per Pod dalam resource yang diskalakan otomatis—misalnya, satu entri per Pod dalam Deployment.
Anda dapat menentukan lebih dari satu metrik dalam satu manifes AutoscalingMetric dengan menambahkan entri
promqltambahan ke arraymetrics.Dalam manifes ini, hal berikut berlaku:
- Kolom
type: Podsmenunjukkan bahwa metrik dikeluarkan oleh Pod. Opsional: Kolom
metricLabelsadalah nama label dalam hasil kueri PromQL yang mencantumkan detail resource (seperti nama Pod, namespace, atau informasi cluster). Metrik kustom yang dikeluarkan oleh Pod harus menyertakan label yang cocok dengan kolompodName, yang menentukan Pod yang terkait dengan metrik tersebut. Label ini dikonfigurasi secara otomatis saat Anda mengirim metrik ke Cloud Monitoring menggunakan Google Cloud Managed Service for Prometheus.Jika kolom ini tidak ditentukan dalam objek AutoscalingMetric, maka nilai default berikut akan digunakan untuk menemukan informasi dalam label. Nilai default ini adalah nama label yang sama yang dikonfigurasi oleh Google Cloud Managed Service for Prometheus:
podName: "pod"namespace: "namespace"clusterName: "cluster"location: "location"projectId: "project_id"
Metrik eksternal
apiVersion: autoscaling.gke.io/v1beta1 kind: AutoscalingMetric metadata: name: NAME namespace: NAMESPACE spec: metrics: - promql: name: METRIC_NAME query: PROMQL_QUERY type: External # Optional, default is 'External'Ganti kode berikut:
NAME: nama objek AutoscalingMetric.NAMESPACE: namespace objek AutoscalingMetric, yang harus cocok dengan namespace workload yang ingin Anda skalakan.METRIC_NAME: nama metrik yang digunakan HPA.PROMQL_QUERY: kueri PromQL yang mengueri metrik. Kueri PromQL harus menampilkan nilai skalar, atau vektor dengan entri unik.
Verifikasi kueri PromQL di Cloud Monitoring untuk memastikan kueri tersebut menampilkan metrik yang diharapkan. Lebih mudah untuk memverifikasi kueri saat Anda menyiapkan kueri tersebut daripada memecahkan masalah perilaku yang tidak terduga nanti.
Untuk memverifikasi kueri, lihat bagian berikut: Memverifikasi kueri PromQL.
Terapkan manifes AutoscalingMetric ke cluster:
kubectl apply -f MANIFEST_FILE.yamlGanti
MANIFEST_FILEdengan nama file YAML.Verifikasi definisi metrik dan ambil nama metrik yang akan digunakan untuk objek HorizontalPodAutoscaler:
Jalankan perintah
kubectl describeuntuk resource kustom AutoscalingMetric:kubectl describe autoscalingmetric NAME -n NAMESPACEGanti kode berikut:
NAME: nama objek AutoscalingMetric.NAMESPACE: namespace objek AutoscalingMetric.
Lihat kolom
Status. Jika tidak ada error yang tercantum, berarti objek valid.Salin nama di kolom
HPA Name. Ini adalah nama yang Anda tambahkan ke objek HorizontalPodAutoscaler. Nama ini memiliki format berikut:autoscaling.gke.io|NAME|METRIC_NAME.
Metrik kini ditentukan dalam objek AutoscalingMetric. Untuk melakukan penskalaan otomatis dengan metrik ini, Anda harus mereferensikannya dalam objek HorizontalPodAutoscaler. Untuk mengetahui informasi selengkapnya, lihat bagian Menggunakan metrik dalam objek HorizontalPodAutoscaler.
Menggunakan metrik dalam objek HorizontalPodAutoscaler
Buat objek HorizontalPodAutoscaler. Jenis metrik HorizontalPodAutoscaler harus cocok dengan nilai kolom
typeyang ditentukan dalam resource kustom AutoscalingMetric. Pilih salah satu konfigurasi berikut, bergantung pada jenis metrik Anda:Opsi 1: Metrik eksternal
apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: HPA_NAME namespace: NAMESPACE spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: DEPLOYMENT_NAME minReplicas: MIN_REPLICAS maxReplicas: MAX_REPLICAS metrics: - type: External external: metric: name: autoscaling.gke.io|NAME|METRIC_NAME target: type: AverageValue averageValue: AVERAGE_VALUEOpsi 2: Metrik pod
apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: HPA_NAME namespace: NAMESPACE spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: DEPLOYMENT_NAME minReplicas: MIN_REPLICAS maxReplicas: MAX_REPLICAS metrics: - type: Pods pods: metric: name: autoscaling.gke.io|NAME|METRIC_NAME target: type: AverageValue # This is the only supported target type averageValue: AVERAGE_VALUEGanti kode berikut:
HPA_NAME: nama objek HorizontalPodAutoscaler.NAMESPACE: namespace objek HorizontalPodAutoscaler, yang harus cocok dengan namespace beban kerja dan resource AutoscalingMetric.DEPLOYMENT_NAME: nama Deployment workload yang ingin Anda skalakan.MIN_REPLICAS: jumlah minimum Pod yang sedang berjalan.MAX_REPLICAS: jumlah maksimum Pod yang sedang berjalan.NAME: nama resource kustom AutoscalingMetric yang Anda buat.METRIC_NAME: nama metrik yang ditentukan di resource AutoscalingMetric.AVERAGE_VALUE: nilai metrik target saat autoscaler menskalakan workload.
Saat Anda membuat objek HorizontalPodAutoscaler sendiri, perhatikan hal-hal berikut:
- Objek AutoscalingMetric, Deployment, dan HorizontalPodAutoscaler harus berada di namespace yang sama.
- Contoh sebelumnya menggunakan pasangan nilai kolom
type: AverageValue. Perhatikan bahwatype: Valuejuga didukung untuk metrik eksternal. - Contoh sebelumnya hanya menggunakan objek Deployment sebagai contoh. Anda juga dapat menskalakan otomatis objek apa pun yang didukung oleh objek HorizontalPodAutoscaler, seperti objek ReplicaSet.
Terapkan manifes HorizontalPodAutoscaler:
kubectl apply -f HPA_MANIFEST_FILE.yamlGanti
HPA_MANIFEST_FILEdengan nama file YAML.
Memecahkan masalah metrik yang diambil untuk penskalaan otomatis
Untuk memecahkan masalah terkait pengambilan metrik, Anda dapat meninjau log atau status resource kustom AutoscalingMetric.
Adaptor metrik penskalaan otomatis memiliki nol replika
Saat memeriksa deployment autoscaling-metrics-adapter di kube-system, Anda mungkin melihat bahwa deployment tersebut memiliki nol replika.
Secara default, adaptor berjalan dengan nol replika untuk menghemat resource cluster. Ini adalah perilaku yang diharapkan. Deployment hanya melakukan penskalaan hingga satu replika saat resource kustom AutoscalingMetric yang memerlukan pemrosesan PromQL ada di cluster.
Jika Anda mengonfigurasi objek AutoscalingMetric dengan kueri PromQL, tetapi adaptor belum di-scale up, pastikan objek berhasil dibuat di cluster.
Meninjau log
Untuk menemukan masalah pada pengontrol yang bertanggung jawab untuk mendapatkan metrik dari Cloud Monitoring, Anda dapat meninjau log-nya.
Anda dapat melihat log di konsol Google Cloud :
Buka halaman Logs Explorer:
Di panel kueri, masukkan kueri berikut:
resource.type="k8s_container" resource.labels.namespace_name="kube-system" resource.labels.container_name="autoscaling-metrics-adapter"
Atau, untuk melihat log menggunakan kubectl, jalankan perintah berikut:
kubectl logs deployment.apps/autoscaling-metrics-adapter -n kube-system
Tinjau status AutoscalingMetric
Anda dapat meninjau status resource kustom AutoscalingMetric untuk mencari error konfigurasi.
Periksa resource kustom AutoscalingMetric:
kubectl describe autoscalingmetric NAME -n NAMESPACEGanti kode berikut:
NAME: nama resource kustom AutoscalingMetric yang Anda buat.NAMESPACE: namespace resource kustom.
Untuk mengetahui detail tentang metrik yang dikonfigurasi, lihat kolom
Status. Detail ini mencakup peringatan tentang error konfigurasi dan nama persis metrik seperti yang seharusnya muncul dalam objek HorizontalPodAutoscaler.Berikut adalah contoh status yang valid:
Name: sample-metric Namespace: default Labels: <none> Annotations: <none> API Version: autoscaling.gke.io/v1beta1 Kind: AutoscalingMetric Metadata: Creation Timestamp: 2026-08-10T14:41:58Z Generation: 1 Resource Version: 1786372918604351020 UID: c3f012a9-8f25-4399-ac91-12ae8f4426d7 Spec: Metrics: Promql: Name: pubsub_unacked Query: sum(pubsub_subscription_num_undelivered_messages) Type: External Status: Metric Statuses: Hpa Name: autoscaling.gke.io|sample-metric|pubsub_unacked Name: pubsub_unacked Events: <none>Berikut adalah contoh status dengan error konfigurasi:
Name: bad-metric Namespace: default Labels: <none> Annotations: <none> API Version: autoscaling.gke.io/v1beta1 Kind: AutoscalingMetric Metadata: Creation Timestamp: 2026-08-10T14:42:40Z Generation: 1 Resource Version: 1786372960414079010 UID: a47d3ed4-f6f2-4c2c-9341-0de4e9752c3c Spec: Metrics: Promql: Name: duplicate_metric Query: sum(up) Type: External Promql: Name: duplicate_metric Query: avg(up) Type: External Status: Metric Statuses: Errors: Multiple metrics defined with the same name. Name: duplicate_metric Events: <none>
Memverifikasi kueri PromQL
Jika Anda mengambil metrik dari Cloud Monitoring menggunakan kueri PromQL, masalah pada kueri dapat menyebabkan error dalam pengambilan metrik, atau menyebabkan nilai yang tidak terduga diambil. Misalnya, jika Anda mengharapkan persentase ditampilkan sebagai nilai dari 1 hingga 100, tetapi menerima nilai dari 0 hingga 1 sebagai gantinya, penskalaan otomatis yang dihasilkan akan berperilaku tidak terduga.
Anda dapat menguji kueri PromQL di Cloud Monitoring untuk memverifikasi bahwa kueri tersebut menampilkan metrik yang diharapkan.
Untuk memverifikasi kueri, lakukan hal berikut:
Di konsol Google Cloud , buka halaman Metrics Explorer.
Di bagian atas panel Query builder, pilih tab PromQL.
Di editor kueri, masukkan kueri PromQL yang ingin Anda uji.
Klik Jalankan Kueri untuk melihat metrik pada diagram.
Langkah berikutnya
- Untuk mengetahui ringkasan tentang penskalaan otomatis berdasarkan metrik, lihat Tentang penskalaan otomatis workload berdasarkan metrik.
- Untuk melakukan penskalaan otomatis menggunakan metrik yang tidak dapat ditentukan dengan kueri PromQL, lihat Mengoptimalkan penskalaan otomatis Pod berdasarkan metrik.