Questo documento descrive come recuperare e utilizzare metriche personalizzate ed esterne per scalare orizzontalmente i pod.
Per recuperare le metriche, puoi utilizzare un adattatore delle metriche gestito da GKE. Questa soluzione gestita è disponibile sia per le metriche in Cloud Monitoring su cui è possibile eseguire query con PromQL, sia per alcune metriche personalizzate dei pod esposte in un endpoint HTTP nel formato Prometheus.
Il gestore della scalabilità automatica dei workload può quindi utilizzare questi dati per scalare i workload in modo più efficiente. Ad esempio, puoi utilizzare questa funzionalità per monitorare la profondità della coda o l'utilizzo della cache e poi consentire al gestore della scalabilità automatica di aumentare o diminuire il numero di pod. Dall'esempio di vLLM, una metrica che potrebbe essere utile per monitorare
l'utilizzo della cache è vllm:gpu_cache_usage_perc.
In alternativa all'adattatore delle metriche gestite, per eseguire la scalabilità automatica utilizzando qualsiasi metrica, puoi recuperare la metrica configurando manualmente un adattatore delle metriche per inviare le metriche a un gestore della scalabilità automatica. Questo flusso di lavoro prevede l'installazione di un adattatore di terze parti, ad esempio Stackdriver Adapter, e la configurazione delle autorizzazioni. Ad esempio, consulta il tutorial Ottimizza la scalabilità automatica dei pod in base alle metriche.
Il resto del documento si concentra sull'adattatore delle metriche gestite.
Recupera metriche
Puoi recuperare le metriche utilizzando l'adattatore delle metriche gestite nei seguenti modi:
- Le metriche personalizzate dei pod emesse dai pod possono essere recuperate all'interno del cluster. Queste metriche possono essere utilizzate per la scalabilità automatica senza dover transitare attraverso un sistema di monitoraggio come Cloud Monitoring.
- Le metriche personalizzate dei pod archiviate in Cloud Monitoring possono essere recuperate utilizzando una query PromQL. Queste metriche vengono emesse dai pod ed esportate in Cloud Monitoring, in genere utilizzando Google Cloud Managed Service per Prometheus. Rispetto al metodo precedente, questo approccio ti consente di utilizzare funzionalità PromQL come il calcolo dei percentili o la lettura dei valori storici.
- Le metriche esterne possono essere recuperate da Cloud Monitoring utilizzando una query PromQL.
Dopo aver recuperato la metrica, fai riferimento alla metrica in un oggetto HorizontalPodAutoscaler. Per saperne di più, consulta la sezione Utilizzare le metriche nel gestore della scalabilità automatica orizzontale dei pod.
Per una panoramica della scalabilità automatica basata sulle metriche, consulta Informazioni sulla scalabilità automatica dei workload in base alle metriche.
Recuperare metriche personalizzate all'interno del cluster
Le metriche personalizzate provengono dal servizio o dall'applicazione che stai eseguendo. Per un esempio di metriche esposte, consulta le metriche esposte dal motore vLLM.
Requisiti
I requisiti per i Pod sono i seguenti:
- GKE 1.35.1-gke.1396000 o versioni successive con cluster nel canale rapido.
- Utilizza la scalabilità automatica orizzontale dei pod con il profilo di rendimento.
I requisiti per le metriche sono i seguenti:
- Le metriche devono essere emesse dai pod nel workload di cui viene eseguita la scalabilità automatica.
- Le metriche devono essere accessibili su un endpoint HTTP. Il percorso dell'endpoint è
/metricsper impostazione predefinita. - Le metriche devono essere formattate in base allo standard Prometheus.
- Sono supportate solo le metriche di tipo indicatore.
- I nomi delle etichette nei selettori di etichette dei pod non devono contenere caratteri speciali. Sono supportate solo le lettere dalla a alla z (maiuscole o minuscole), i numeri, i trattini e i trattini bassi.
- Quando utilizzi il filtro in base alle etichette delle metriche, la chiave di etichetta deve corrispondere all'espressione regolare
^[a-zA-Z_][a-zA-Z0-9_]*(inizia con una lettera o un trattino basso e contiene solo lettere, numeri o trattini bassi). - Per cluster possono essere esposte un massimo di 20 metriche uniche.
Definisci la metrica
Scegli una metrica da esporre. Puoi scegliere qualsiasi metrica esposta dal tuo workload e che soddisfi anche i requisiti elencati nella sezione precedente.
Se il tuo workload espone più metriche con lo stesso nome ma etichette diverse, aggiungi un filtro per le etichette per assicurarti che ne venga selezionata solo una.
Aggiungi la seguente risorsa personalizzata, sostituendo i dettagli specifici per la metrica e il pod:
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_NAMESostituisci quanto segue in base al tuo workload:
NAME: il nome dell'oggetto AutoscalingMetric.NAMESPACE: lo spazio dei nomi in cui si trovano i pod.APP_LABEL_NAMEeAPP_LABEL_VALUE: il nome e il valore dell'etichetta corrispondenti ai pod che emettono la metrica.METRIC_PORT: il numero di porta.METRIC_PATH: il percorso della metrica. Verifica il percorso utilizzato dal tuo servizio o dalla tua applicazione; questo percorso è spesso/metrics.METRIC_NAME: il nome della metrica che stai esponendo. Il nome deve corrispondere all'espressione regolare^[a-z]([-a-z0-9]*[a-z0-9])?e avere una lunghezza massima di 63 caratteri. Questa espressione significa che il primo carattere deve essere una lettera minuscola e tutti i caratteri successivi devono essere trattini, lettere minuscole o cifre. Tuttavia, l'ultimo carattere non può essere un trattino.(Facoltativo)
METRIC_PROMETHEUS_NAME: il nome della metrica Prometheus esposta dal pod. Puoi utilizzare questo campo per rinominare la metrica, ad esempio perché il nome della metrica esposto dal pod non è conforme alle limitazioni dei nomi impostate dallo scalatore automatico.Per ulteriori informazioni sulle limitazioni dei nomi, consulta le limitazioni per la scalabilità automatica orizzontale dei pod. Puoi anche filtrare le metriche utilizzando le etichette delle metriche.
Applica il manifest utilizzando il seguente comando:
kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yamlSostituisci
FILE_NAME_AUTOSCALING_METRICcon il nome del file YAML.Verifica la definizione della metrica e recupera il nome della metrica da utilizzare per l'oggetto HorizontalPodAutoscaler:
Esegui il comando
kubectl describeper la risorsa personalizzata AutoscalingMetric:kubectl describe autoscalingmetric NAME -n NAMESPACESostituisci quanto segue:
NAME: il nome dell'oggetto AutoscalingMetric.NAMESPACE: lo spazio dei nomi dell'oggetto AutoscalingMetric.
Guarda il campo
Status. Se non sono elencati errori, l'oggetto è valido.Copia il nome nel campo
HPA Name. Questo è il nome che aggiungi all'oggetto HorizontalPodAutoscaler. Questo nome ha il seguente formato:autoscaling.gke.io|NAME|METRIC_NAME.
La metrica è ora definita nell'oggetto AutoscalingMetric. Per la scalabilità automatica con questa metrica, devi farvi riferimento in un oggetto HorizontalPodAutoscaler. Per maggiori informazioni, consulta la sezione Utilizzare le metriche nell'oggetto HorizontalPodAutoscaler.
Quando aggiungi la risorsa personalizzata, la metrica viene inviata all'API di scalabilità automatica. La metrica viene letta ogni pochi secondi e inviata allo scaler automatico del workload.
Filtrare le metriche utilizzando le etichette delle metriche
Il filtraggio delle metriche utilizzando le etichette delle metriche è disponibile su GKE 1.36.0-gke.1759000 o versioni successive.
Le metriche emesse dai tuoi workload spesso includono etichette. Le etichette sono coppie chiave-valore che ti consentono di aggiungere dimensioni a un valore. Ad esempio, una metrica che conteggia il numero di richieste a un endpoint HTTP suddiviso per metodo e ambiente potrebbe utilizzare le etichette per specificare questo contesto. Questo esempio potrebbe avere il seguente aspetto:
http_requests_total{method="GET", env="prod"} 11111
http_requests_total{method="PUT", env="staging"} 22222
Puoi utilizzare i filtri delle etichette per assicurarti che la specifica della metrica corrisponda esattamente a una metrica. Ad esempio, per selezionare solo la prima metrica nell'esempio precedente, utilizza la seguente specifica per la metrica 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
Le chiavi delle coppie chiave-valore matchLabels devono corrispondere all'espressione regolare
^[a-zA-Z_][a-zA-Z0-9_]*, ovvero iniziare con una lettera o un trattino basso e
contenere solo lettere, numeri o trattini bassi.
Recupera metriche personalizzate o esterne da Cloud Monitoring
Puoi recuperare le metriche da Cloud Monitoring per scalare i carichi di lavoro. GKE supporta il recupero di due tipi di metriche da Cloud Monitoring:
- Metriche personalizzate: utilizza questo tipo per applicare le funzionalità PromQL, ad esempio il calcolo dei percentili o la lettura dei valori storici, alle metriche emesse dai carichi di lavoro del cluster.
- Metriche esterne: utilizza questo tipo per scalare in base a un'entità esterna al cluster, ad esempio il numero di messaggi in attesa in una sottoscrizione Pub/Sub.
Altrimenti, recupera le metriche personalizzate dal cluster.
Requisiti
- GKE 1.36.2-gke.2771000 o versioni successive.
- Le metriche devono essere archiviate in Cloud Monitoring. Ad esempio, puoi utilizzare Google Cloud Managed Service per Prometheus.
- Sono supportate al massimo 100 metriche per cluster. Questo limite è il totale combinato per le metriche personalizzate ed esterne.
- Le metriche in Cloud Monitoring devono trovarsi nello stesso Google Cloud progetto del cluster di cui viene eseguita la scalabilità automatica.
Definisci la metrica
Utilizzi un file YAML per definire le metriche, inclusa la query PromQL specifica.
Scegli una delle seguenti configurazioni, a seconda che tu stia recuperando una metrica personalizzata o una metrica esterna:
Crea un oggetto AutoscalingMetric e definisci la metrica da recuperare.
Metrica personalizzata (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"Sostituisci quanto segue:
NAME: il nome dell'oggetto AutoscalingMetric.NAMESPACE: lo spazio dei nomi dell'oggetto AutoscalingMetric, che deve corrispondere allo spazio dei nomi del workload di cui vuoi scalare.METRIC_NAME: il nome della metrica utilizzata dall'oggetto HorizontalPodAutoscaler.PROMQL_QUERY: la query PromQL che esegue query sulla metrica. La query PromQL deve restituire un vettore con una voce per ogni pod nella risorsa con scalabilità automatica, ad esempio una voce per ogni pod in un deployment.
Puoi definire più di una metrica in un singolo manifest AutoscalingMetric aggiungendo ulteriori voci
promqlall'arraymetrics.In questo manifest, si applica quanto segue:
- Il campo
type: Podsindica che le metriche vengono emesse dai pod. (Facoltativo) I campi
metricLabelssono i nomi delle etichette nel risultato della query PromQL che elenca i dettagli della risorsa (ad esempio il nome del pod, lo spazio dei nomi o le informazioni sul cluster). La metrica personalizzata emessa da un pod deve includere un'etichetta corrispondente al campopodName, che specifica a quale pod è associata la metrica. Questa etichetta viene configurata automaticamente quando invii le metriche a Cloud Monitoring utilizzando Google Cloud Managed Service per Prometheus.Se questi campi non sono specificati nell'oggetto AutoscalingMetric, vengono utilizzati i seguenti valori predefiniti per trovare le informazioni nell'etichetta. Questi valori predefiniti sono gli stessi nomi delle etichette configurati da Google Cloud Managed Service per Prometheus:
podName: "pod"namespace: "namespace"clusterName: "cluster"location: "location"projectId: "project_id"
Metrica esterna
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'Sostituisci quanto segue:
NAME: il nome dell'oggetto AutoscalingMetric.NAMESPACE: lo spazio dei nomi dell'oggetto AutoscalingMetric, che deve corrispondere allo spazio dei nomi del workload di cui vuoi scalare.METRIC_NAME: il nome della metrica utilizzata da HPA.PROMQL_QUERY: la query PromQL che esegue query sulla metrica. La query PromQL deve restituire un valore scalare o un vettore con una voce univoca.
Verifica le query PromQL in Cloud Monitoring per assicurarti che restituiscano le metriche previste. È più facile verificare le query durante la configurazione che risolvere problemi di comportamento imprevisto in un secondo momento.
Per verificare le query, consulta la seguente sezione: Verifica delle query PromQL.
Applica il manifest AutoscalingMetric al cluster:
kubectl apply -f MANIFEST_FILE.yamlSostituisci
MANIFEST_FILEcon il nome del file YAML.Verifica la definizione della metrica e recupera il nome della metrica da utilizzare per l'oggetto HorizontalPodAutoscaler:
Esegui il comando
kubectl describeper la risorsa personalizzata AutoscalingMetric:kubectl describe autoscalingmetric NAME -n NAMESPACESostituisci quanto segue:
NAME: il nome dell'oggetto AutoscalingMetric.NAMESPACE: lo spazio dei nomi dell'oggetto AutoscalingMetric.
Guarda il campo
Status. Se non sono elencati errori, l'oggetto è valido.Copia il nome nel campo
HPA Name. Questo è il nome che aggiungi all'oggetto HorizontalPodAutoscaler. Questo nome ha il seguente formato:autoscaling.gke.io|NAME|METRIC_NAME.
La metrica è ora definita nell'oggetto AutoscalingMetric. Per la scalabilità automatica con questa metrica, devi farvi riferimento in un oggetto HorizontalPodAutoscaler. Per maggiori informazioni, consulta la sezione Utilizzare le metriche nell'oggetto HorizontalPodAutoscaler.
Utilizzare le metriche nell'oggetto HorizontalPodAutoscaler
Crea un oggetto HorizontalPodAutoscaler. Il tipo di metrica HorizontalPodAutoscaler deve corrispondere al valore del campo
typedefinito nella risorsa personalizzata AutoscalingMetric. Scegli una delle seguenti configurazioni in base al tipo di metrica:Opzione 1: metrica esterna
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_VALUEOpzione 2: metrica dei 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_VALUESostituisci quanto segue:
HPA_NAME: il nome dell'oggetto HorizontalPodAutoscaler.NAMESPACE: lo spazio dei nomi dell'oggetto HorizontalPodAutoscaler, che deve corrispondere allo spazio dei nomi del workload e della risorsa AutoscalingMetric.DEPLOYMENT_NAME: il nome del deployment del workload che vuoi scalare.MIN_REPLICAS: il numero minimo di pod in esecuzione.MAX_REPLICAS: il numero massimo di pod in esecuzione.NAME: il nome della risorsa personalizzata AutoscalingMetric che hai creato.METRIC_NAME: il nome della metrica definita nella risorsa AutoscalingMetric.AVERAGE_VALUE: il valore della metrica di destinazione in corrispondenza del quale il gestore della scalabilità automatica scala il carico di lavoro.
Quando crei il tuo oggetto HorizontalPodAutoscaler, tieni presente quanto segue:
- Gli oggetti AutoscalingMetric, Deployment e HorizontalPodAutoscaler devono trovarsi nello stesso spazio dei nomi.
- L'esempio precedente utilizza la coppia campo-valore
type: AverageValue. Tieni presente chetype: Valueè supportato anche per le metriche esterne. - L'esempio precedente utilizza un oggetto Deployment solo a titolo esemplificativo. Puoi anche scalare automaticamente qualsiasi oggetto supportato dagli oggetti HorizontalPodAutoscaler, come un oggetto ReplicaSet.
Applica il manifest HorizontalPodAutoscaler:
kubectl apply -f HPA_MANIFEST_FILE.yamlSostituisci
HPA_MANIFEST_FILEcon il nome del file YAML.
Risolvere i problemi relativi alle metriche recuperate per la scalabilità automatica
Per risolvere i problemi relativi al recupero delle metriche, puoi esaminare i log o lo stato della risorsa personalizzata AutoscalingMetric.
L'adattatore delle metriche di scalabilità automatica ha zero repliche
Quando esamini il deployment di autoscaling-metrics-adapter in kube-system, potresti notare che
non ha repliche.
Per impostazione predefinita, l'adattatore viene eseguito con zero repliche per risparmiare risorse del cluster. Questo è un comportamento previsto. Il deployment viene scalato fino a una replica solo quando nel cluster esiste una risorsa personalizzata AutoscalingMetric che richiede l'elaborazione di PromQL.
Se hai configurato un oggetto AutoscalingMetric con una query PromQL, ma l'adattatore non è stato scalato, verifica che l'oggetto sia stato creato correttamente nel cluster.
Esamina i log
Per trovare problemi relativi al controller responsabile dell'ottenimento delle metriche da Cloud Monitoring, puoi esaminare i relativi log.
Puoi visualizzare i log nella console Google Cloud :
Vai alla pagina Esplora log:
Nel riquadro della query, inserisci la seguente query:
resource.type="k8s_container" resource.labels.namespace_name="kube-system" resource.labels.container_name="autoscaling-metrics-adapter"
In alternativa, per visualizzare i log utilizzando kubectl, esegui questo comando:
kubectl logs deployment.apps/autoscaling-metrics-adapter -n kube-system
Esamina lo stato di AutoscalingMetric
Puoi esaminare lo stato della risorsa personalizzata AutoscalingMetric per verificare la presenza di errori di configurazione.
Ispeziona la risorsa personalizzata AutoscalingMetric:
kubectl describe autoscalingmetric NAME -n NAMESPACESostituisci quanto segue:
NAME: il nome della risorsa personalizzata AutoscalingMetric che hai creato.NAMESPACE: lo spazio dei nomi della risorsa personalizzata.
Per i dettagli sulle metriche configurate, consulta il campo
Status. Questi dettagli includono eventuali avvisi relativi a errori di configurazione e il nome esatto della metrica così come dovrebbe apparire nell'oggetto HorizontalPodAutoscaler.Di seguito è riportato un esempio di stato valido:
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>Di seguito è riportato un esempio di stato con un errore di configurazione:
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>
Verificare le query PromQL
Se recuperi le metriche da Cloud Monitoring utilizzando una query PromQL, un problema con la query può causare errori nel recupero della metrica o la restituzione di un valore imprevisto. Ad esempio, se prevedi che una percentuale venga restituita come valore da 1 a 100, ma ricevi un valore da 0 a 1 invece, lo scaling automatico risultante si comporta in modo imprevisto.
Puoi testare le query PromQL in Cloud Monitoring per verificare che restituiscano le metriche previste.
Per verificare le query, segui questi passaggi:
Nella console Google Cloud , vai alla pagina Esplora metriche.
Vai a Esplora metriche
Nella parte superiore del riquadro Query Builder, seleziona la scheda PromQL.
Nell'editor di query, inserisci la query PromQL che vuoi testare.
Fai clic su Esegui query per visualizzare le metriche nel grafico.
Passaggi successivi
- Per una panoramica della scalabilità automatica basata sulle metriche, consulta Informazioni sulla scalabilità automatica dei workload in base alle metriche.
- Per eseguire la scalabilità automatica utilizzando metriche che non possono essere definite con una query PromQL, consulta Ottimizza la scalabilità automatica dei pod in base alle metriche.