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, utilizzi un adattatore di metriche gestito. Questa soluzione gestita è disponibile per le metriche in Cloud Monitoring su cui è possibile eseguire query con PromQL e per tutte le metriche personalizzate. Le metriche personalizzate sono metriche esposte dai pod in un endpoint HTTP, nel formato Prometheus.

In alternativa, per la scalabilità automatica utilizzando qualsiasi metrica, puoi recuperare la metrica configurando manualmente un adattatore di metriche per inviare le metriche a un gestore della scalabilità automatica. Questo flusso di lavoro prevede l'installazione di un adattatore di terze parti, come l' adattatore delle metriche personalizzate, e la configurazione delle autorizzazioni. Ad esempio, consulta il tutorial Ottimizzare la scalabilità automatica dei pod in base alle metriche.

Recuperare le metriche

Puoi recuperare le metriche nei seguenti modi:

  • Le metriche personalizzate 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 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 le funzionalità di PromQL, ad esempio il calcolo dei percentili o la lettura dei valori storici.
  • Le metriche esterne possono essere recuperate da Cloud Monitoring utilizzando una query PromQL.
  • Le metriche possono essere recuperate configurando manualmente un adattatore di metriche per inviare le metriche a un gestore della scalabilità automatica. Questo flusso di lavoro prevede l'installazione di strumenti di terze parti e la configurazione delle autorizzazioni. Ad esempio, consulta il tutorial Ottimizzare la scalabilità automatica dei pod in base alle metriche.

Dopo aver recuperato la metrica, fai riferimento alla metrica in un oggetto HorizontalPodAutoscaler. Per ulteriori informazioni, consulta la sezione Utilizzare le metriche nel gestore della scalabilità automatica orizzontale dei pod.

Per una panoramica sulla scalabilità automatica in base alle metriche, consulta Informazioni sulla scalabilità automatica dei carichi di lavoro in base alle metriche.

Recuperare le 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 da vLLM Engine.

Requisiti

I requisiti per i pod sono i seguenti:

I requisiti per le metriche sono i seguenti:

  • 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 Misuratore.
  • I nomi delle etichette nei selettori di etichette dei pod non devono contenere caratteri speciali. Sono supportate solo le lettere a-z (minuscole o maiuscole), i numeri, i trattini e i trattini bassi.
  • Quando utilizzi il filtro basato sulle 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).
  • È possibile esporre un massimo di 20 metriche univoche per cluster.

Definire la metrica

  1. Scegli una metrica da esporre. Puoi scegliere qualsiasi metrica esposta dal tuo carico di lavoro e che soddisfi anche i requisiti elencati nella sezione precedente.

    Se il tuo carico di lavoro espone più metriche con lo stesso nome ma etichette diverse, aggiungi un filtro di etichette per assicurarti che ne venga selezionata solo una.

  2. Aggiungi la seguente risorsa personalizzata, sostituendo i dettagli specifici della metrica e del 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 carico di lavoro:

    • 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 indica che il primo carattere deve essere una lettera minuscola e tutti i caratteri successivi devono essere trattini, lettere minuscole o numeri. 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 esposta dal pod non è conforme alle limitazioni dei nomi impostate dal gestore della scalabilità automatica.

      Per ulteriori informazioni sulle limitazioni dei nomi, consulta le limitazioni per la scalabilità automatica orizzontale dei pod.

  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. Esamina 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 ulteriori 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 al gestore della scalabilità automatica del carico di lavoro.

Recuperare metriche personalizzate o esterne da Cloud Monitoring

Puoi recuperare le metriche da Cloud Monitoring per scalare i tuoi carichi di lavoro. GKE supporta il recupero di due tipi di metriche da Cloud Monitoring:

  • Metriche personalizzate: utilizza questo tipo per applicare le funzionalità di PromQL, come 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.

In alternativa, recupera le metriche personalizzate dal cluster.

Requisiti

  • GKE versione 1.36.2-gke.2771000 o successive.
  • Le metriche devono essere archiviate in Cloud Monitoring. Ad esempio, puoi utilizzare Google Cloud Managed Service per Prometheus.
  • È supportato un massimo di 100 metriche per cluster. Questo limite è il totale combinato per le metriche personalizzate ed esterne.
  • Le metriche in Cloud Monitoring devono trovarsi nello stesso Cloud de Confiance by S3NS progetto del cluster di cui viene eseguita la scalabilità automatica.

Definire la metrica

Utilizza 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 carico di lavoro di cui vuoi eseguire la scalabilità.
    • 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 di cui è stata eseguita la scalabilità automatica, ad esempio una voce per ogni pod in un deployment.

    Puoi definire più di una metrica in un singolo manifest AutoscalingMetric aggiungendo altre 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 elencano i dettagli della risorsa (ad esempio il nome del pod, lo spazio dei nomi o le informazioni del 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 carico di lavoro di cui vuoi eseguire la scalabilità.
    • 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 i problemi relativi a comportamenti imprevisti in un secondo momento.

    Per verificare le query, consulta la sezione seguente: Verificare le 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. Esamina 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 ulteriori 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 a seconda del 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 carico di lavoro e della risorsa AutoscalingMetric.
    • DEPLOYMENT_NAME: il nome del deployment del carico di lavoro di cui vuoi eseguire la scalabilità.
    • 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 target della metrica 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 di esempio. Puoi anche eseguire la scalabilità automatica di qualsiasi oggetto supportato dagli oggetti HorizontalPodAutoscaler, ad esempio 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 autoscaling-metrics-adapter in kube-system, potresti notare che ha zero repliche.

Per impostazione predefinita, l'adattatore viene eseguito con zero repliche per conservare le risorse del cluster. Questo è un comportamento previsto. Il deployment viene scalato a una sola replica solo quando nel cluster esiste una risorsa personalizzata AutoscalingMetric che richiede l'elaborazione 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.

Esaminare i log

Per trovare i problemi relativi al controller responsabile del recupero delle metriche da Cloud Monitoring, puoi esaminarne i log.

Puoi visualizzare i log nella Cloud de Confiance console:

  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 il seguente comando:

kubectl logs deployment.apps/autoscaling-metrics-adapter -n kube-system

Esaminare lo stato di AutoscalingMetric

Puoi esaminare lo stato della risorsa personalizzata AutoscalingMetric per cercare errori di configurazione.

  1. Esamina 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, esamina 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 venga restituita una percentuale come valore da 1 a 100, ma ricevi un valore da 0 a 1, la scalabilità automatica 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:

  1. Nella Cloud de Confiance console, vai alla pagina Esplora metriche.

    Vai a Esplora metriche

  2. Nella parte superiore del riquadro Generatore di query, 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 sul grafico.

Passaggi successivi