Scalare automaticamente i pod utilizzando metriche personalizzate o esterne

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:

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 è /metrics per 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

  1. 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.

  2. 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_NAME
    

    Sostituisci 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_NAME e APP_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.

  3. Applica il manifest utilizzando il seguente comando:

    kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yaml
    

    Sostituisci FILE_NAME_AUTOSCALING_METRIC con il nome del file YAML.

  4. Verifica la definizione della metrica e recupera il nome della metrica da utilizzare per l'oggetto HorizontalPodAutoscaler:

    1. Esegui il comando kubectl describe per la risorsa personalizzata AutoscalingMetric:

      kubectl describe autoscalingmetric NAME -n NAMESPACE
      

      Sostituisci quanto segue:

      • NAME: il nome dell'oggetto AutoscalingMetric.
      • NAMESPACE: lo spazio dei nomi dell'oggetto AutoscalingMetric.
    2. Guarda il campo Status. Se non sono elencati errori, l'oggetto è valido.

    3. 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:

  1. 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 promql all'array metrics.

    In questo manifest, si applica quanto segue:

    • Il campo type: Pods indica che le metriche vengono emesse dai pod.
    • (Facoltativo) I campi metricLabels sono 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 campo podName, 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.
  2. 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.

  3. Applica il manifest AutoscalingMetric al cluster:

    kubectl apply -f MANIFEST_FILE.yaml
    

    Sostituisci MANIFEST_FILE con il nome del file YAML.

  4. Verifica la definizione della metrica e recupera il nome della metrica da utilizzare per l'oggetto HorizontalPodAutoscaler:

    1. Esegui il comando kubectl describe per la risorsa personalizzata AutoscalingMetric:

      kubectl describe autoscalingmetric NAME -n NAMESPACE
      

      Sostituisci quanto segue:

      • NAME: il nome dell'oggetto AutoscalingMetric.
      • NAMESPACE: lo spazio dei nomi dell'oggetto AutoscalingMetric.
    2. Guarda il campo Status. Se non sono elencati errori, l'oggetto è valido.

    3. 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

  1. Crea un oggetto HorizontalPodAutoscaler. Il tipo di metrica HorizontalPodAutoscaler deve corrispondere al valore del campo type definito 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_VALUE
    

    Opzione 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_VALUE
    

    Sostituisci 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 che type: 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.
  2. Applica il manifest HorizontalPodAutoscaler:

    kubectl apply -f HPA_MANIFEST_FILE.yaml
    

    Sostituisci HPA_MANIFEST_FILE con 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 :

  1. Vai alla pagina Esplora log:

    Vai a Esplora log

  2. 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.

  1. Ispeziona la risorsa personalizzata AutoscalingMetric:

    kubectl describe autoscalingmetric NAME -n NAMESPACE
    

    Sostituisci quanto segue:

    • NAME: il nome della risorsa personalizzata AutoscalingMetric che hai creato.
    • NAMESPACE: lo spazio dei nomi della risorsa personalizzata.
  2. 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:

  1. Nella console Google Cloud , vai alla pagina Esplora metriche.

    Vai a Esplora metriche

  2. Nella parte superiore del riquadro Query Builder, seleziona la scheda PromQL.

  3. Nell'editor di query, inserisci la query PromQL che vuoi testare.

  4. Fai clic su Esegui query per visualizzare le metriche nel grafico.

Passaggi successivi