Ajusta la escala automática de Pods con métricas personalizadas o externas

En este documento, se describe cómo recuperar y usar métricas personalizadas y externas para escalar pods de forma horizontal.

Para recuperar las métricas, usas un adaptador de métricas administrado. Esta solución administrada está disponible para las métricas de Cloud Monitoring que se pueden consultar con PromQL y todas las métricas personalizadas. Las métricas personalizadas son métricas expuestas por los pods en un extremo HTTP, en formato Prometheus.

Como alternativa, para realizar el ajuste de escala automático con cualquier métrica, puedes recuperar la métrica configurando de forma manual un adaptador de métricas para enviar métricas a un escalador automático. Este flujo de trabajo implica instalar un adaptador de terceros, como el adaptador de métricas personalizadas, y configurar permisos. Por ejemplo, consulta el instructivo Optimiza el ajuste de escala automático de Pods en función de las métricas.

Recupera métricas

Puedes recuperar métricas de las siguientes maneras:

  • Las métricas personalizadas que emiten los pods se pueden recuperar dentro del clúster. Estas métricas se pueden usar para el ajuste de escala automático sin necesidad de pasar por un sistema de supervisión como Cloud Monitoring.
  • Las métricas de pods almacenadas en Cloud Monitoring se pueden recuperar con una consulta de PromQL. Esas métricas son emitidas por los pods y exportadas a Cloud Monitoring, por lo general, con Google Cloud Managed Service para Prometheus. En comparación con el método anterior, este enfoque te permite usar funciones de PromQL, como calcular percentiles o leer valores históricos.
  • Las métricas externas se pueden recuperar de Cloud Monitoring con una consulta de PromQL.
  • Las métricas se pueden recuperar configurando de forma manual un adaptador de métricas para enviar métricas a un escalador automático. Este flujo de trabajo implica instalar herramientas de terceros y configurar permisos. Por ejemplo, consulta el instructivo Optimiza el ajuste de escala automático de Pods en función de las métricas.

Después de recuperar la métrica, debes hacer referencia a ella en un objeto HorizontalPodAutoscaler. Para obtener más información, consulta la sección Usa las métricas en el escalador automático horizontal de Pods.

Para obtener una descripción general sobre el ajuste de escala automático basado en métricas, consulta Acerca del ajuste de escala automático de las cargas de trabajo según las métricas.

Recupera métricas personalizadas dentro del clúster

Las métricas personalizadas provienen del servicio o la aplicación que estás ejecutando. Para ver un ejemplo de métricas expuestas, consulta las métricas que expone el motor vLLM.

Requisitos

Los requisitos para los pods son los siguientes:

Los requisitos para las métricas son los siguientes:

  • Se debe poder acceder a las métricas en un extremo HTTP. La ruta de acceso del extremo es /metrics de forma predeterminada.
  • Las métricas deben tener el formato según el estándar de Prometheus.
  • Solo se admiten métricas de indicador.
  • Los nombres de las etiquetas en los selectores de etiquetas de pods no deben contener caracteres especiales. Solo se admiten letras de la a a la z (minúsculas o mayúsculas), números, guiones y guiones bajos.
  • Cuando usas el filtrado basado en etiquetas de métricas, la clave de etiqueta debe coincidir con la expresión regular ^[a-zA-Z_][a-zA-Z0-9_]* (comenzar con una letra o un guion bajo, y contener solo letras, números o guiones bajos).
  • Se puede exponer un máximo de 20 métricas únicas por clúster.

Define la métrica

  1. Elige una métrica para exponer. Puedes elegir cualquier métrica que exponga tu carga de trabajo y que también cumpla con los requisitos que se indican en la sección anterior.

    Si tu carga de trabajo expone varias métricas con el mismo nombre, pero diferentes etiquetas, agrega un filtro de etiquetas para asegurarte de que solo se seleccione una.

  2. Agrega el siguiente recurso personalizado y reemplaza los detalles que son específicos de tu métrica y 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

    Reemplaza lo siguiente para que coincida con tu carga de trabajo:

    • NAME: el nombre del objeto AutoscalingMetric
    • NAMESPACE: el espacio de nombres en el que se encuentran los pods
    • APP_LABEL_NAME y APP_LABEL_VALUE: el nombre y el valor de la etiqueta que coinciden con los pods que emiten la métrica
    • METRIC_PORT: el número de puerto
    • METRIC_PATH: la ruta de acceso a la métrica Verifica la ruta de acceso que usa tu servicio o aplicación. Esta ruta de acceso suele ser /metrics.
    • METRIC_NAME: el nombre de la métrica que expones El nombre debe coincidir con la expresión regular ^[a-z]([-a-z0-9]*[a-z0-9])? y tener una longitud de no más de 63 caracteres. Esta expresión significa que el primer carácter debe ser una letra minúscula y todos los caracteres siguientes deben ser guiones, letras minúsculas o dígitos. Sin embargo, el último carácter no puede ser un guion.

    • Opcional: METRIC_PROMETHEUS_NAME: el nombre de la métrica de Prometheus que expone el pod Puedes usar este campo para cambiar el nombre de la métrica, por ejemplo, porque el nombre de la métrica que expone el pod no cumple con las restricciones de nombre que establece el escalador automático.

      Para obtener más información sobre las restricciones de nombres, consulta las limitaciones del ajuste de escala automático horizontal de Pods.

  3. Aplica el manifiesto con el siguiente comando:

    kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yaml

    Reemplaza FILE_NAME_AUTOSCALING_METRIC por el nombre del archivo YAML.

  4. Verifica la definición de la métrica y recupera el nombre de la métrica para usarlo en el objeto HorizontalPodAutoscaler:

    1. Ejecuta el comando kubectl describe para el recurso personalizado AutoscalingMetric:

      kubectl describe autoscalingmetric NAME -n NAMESPACE

      Reemplaza lo siguiente:

      • NAME: el nombre del objeto AutoscalingMetric
      • NAMESPACE: el espacio de nombres del objeto AutoscalingMetric

    2. Observa el campo Status. Si no aparece ningún error, el objeto es válido.

    3. Copia el nombre en el campo HPA Name. Este es el nombre que agregas al objeto HorizontalPodAutoscaler. Este nombre tiene el siguiente formato: autoscaling.gke.io|NAME|METRIC_NAME.

Ahora la métrica se define en el objeto AutoscalingMetric. Para realizar el ajuste de escala automático con esta métrica, debes hacer referencia a ella en un objeto HorizontalPodAutoscaler. Para obtener más información, consulta la sección Usa las métricas en el objeto HorizontalPodAutoscaler.

Cuando agregas el recurso personalizado, la métrica se envía a la API de ajuste de escala automático. La métrica se lee cada pocos segundos y se envía al escalador automático de la carga de trabajo.

Recupera métricas personalizadas o externas de Cloud Monitoring

Puedes recuperar métricas de Cloud Monitoring para escalar tus cargas de trabajo. GKE admite la recuperación de dos tipos de métricas de Cloud Monitoring:

  • Métricas personalizadas: Usa este tipo para aplicar funciones de PromQL, como calcular percentiles o leer valores históricos, a las métricas que emiten las cargas de trabajo de tu clúster.
  • Métricas externas: Usa este tipo para escalar en función de una entidad fuera de el clúster, como la cantidad de mensajes pendientes en una suscripción a Pub/Sub.

De lo contrario, recupera métricas personalizadas del clúster.

Requisitos

  • GKE versión 1.36.2-gke.2771000 o posterior
  • Las métricas deben almacenarse en Cloud Monitoring. Por ejemplo, puedes usar Google Cloud Managed Service para Prometheus.
  • Se admite un máximo de 100 métricas por clúster. Este límite es el total combinado de las métricas personalizadas y externas.
  • Las métricas de Cloud Monitoring deben estar en el mismo Cloud de Confiance by S3NS proyecto que el clúster que se ajusta automáticamente.

Define la métrica

Usas un archivo YAML para definir las métricas, incluida la consulta de PromQL específica.

Elige una de las siguientes configuraciones, según si recuperas una métrica personalizada o una métrica externa:

  1. Crea un objeto AutoscalingMetric y define la métrica que se recuperará.

    Métrica personalizada (pods) 

    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"

    Reemplaza lo siguiente:

    • NAME: el nombre del objeto AutoscalingMetric
    • NAMESPACE: el espacio de nombres del objeto AutoscalingMetric, que debe coincidir con el espacio de nombres de la carga de trabajo que deseas escalar
    • METRIC_NAME: el nombre de la métrica que usa el objeto HorizontalPodAutoscaler
    • PROMQL_QUERY: la consulta de PromQL que consulta la métrica La consulta de PromQL debe mostrar un vector con una entrada por pod en el recurso con ajuste de escala automático, por ejemplo, una entrada por pod en una Deployment.

    Puedes definir más de una métrica en un solo manifiesto AutoscalingMetric si agregas entradas promql adicionales al array metrics.

    En este manifiesto, se aplica lo siguiente:

    • El campo type: Pods indica que las métricas son emitidas por los pods.

    • Opcional: Los campos metricLabels son los nombres de las etiquetas en el resultado de la consulta de PromQL que muestran los detalles del recurso (como el nombre del pod, el espacio de nombres o la información del clúster). La métrica personalizada que emite un pod debe incluir una etiqueta que coincida con el campo podName y que especifique con qué pod está asociada la métrica. Esta etiqueta se configura automáticamente cuando envías métricas a Cloud Monitoring con Google Cloud Managed Service para Prometheus.

      Si estos campos no se especifican en el objeto AutoscalingMetric, se usan los siguientes valores predeterminados para encontrar la información en la etiqueta. Estos valores predeterminados son los mismos nombres de etiquetas que configura Google Cloud Managed Service para Prometheus:

      • podName: "pod"
      • namespace: "namespace"
      • clusterName: "cluster"
      • location: "location"
      • projectId: "project_id"

    Métrica externa 

    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'

    Reemplaza lo siguiente:

    • NAME: el nombre del objeto AutoscalingMetric
    • NAMESPACE: el espacio de nombres del objeto AutoscalingMetric, que debe coincidir con el espacio de nombres de la carga de trabajo que deseas escalar
    • METRIC_NAME: el nombre de la métrica que usa el HPA
    • PROMQL_QUERY: la consulta de PromQL que consulta la métrica La consulta de PromQL debe mostrar un valor escalar o un vector con una entrada única.

  2. Verifica las consultas de PromQL en Cloud Monitoring para asegurarte de que muestren las métricas esperadas. Es más fácil verificar las consultas a medida que las configuras que solucionar problemas de comportamientos inesperados más adelante.

    Para verificar las consultas, consulta la siguiente sección: Verifica las consultas de PromQL.

  3. Aplica el manifiesto AutoscalingMetric al clúster:

    kubectl apply -f MANIFEST_FILE.yaml

    Reemplaza MANIFEST_FILE por el nombre del archivo YAML.

  4. Verifica la definición de la métrica y recupera el nombre de la métrica para usarlo en el objeto HorizontalPodAutoscaler:

    1. Ejecuta el comando kubectl describe para el recurso personalizado AutoscalingMetric:

      kubectl describe autoscalingmetric NAME -n NAMESPACE

      Reemplaza lo siguiente:

      • NAME: el nombre del objeto AutoscalingMetric
      • NAMESPACE: el espacio de nombres del objeto AutoscalingMetric

    2. Observa el campo Status. Si no aparece ningún error, el objeto es válido.

    3. Copia el nombre en el campo HPA Name. Este es el nombre que agregas al objeto HorizontalPodAutoscaler. Este nombre tiene el siguiente formato: autoscaling.gke.io|NAME|METRIC_NAME.

Ahora la métrica se define en el objeto AutoscalingMetric. Para realizar el ajuste de escala automático con esta métrica, debes hacer referencia a ella en un objeto HorizontalPodAutoscaler. Para obtener más información, consulta la sección Usa las métricas en el objeto HorizontalPodAutoscaler.

Usa las métricas en el objeto HorizontalPodAutoscaler

  1. Crea un objeto HorizontalPodAutoscaler. El tipo de métrica HorizontalPodAutoscaler debe coincidir con el valor del campo type definido en el recurso personalizado AutoscalingMetric. Elige una de las siguientes configuraciones según tu tipo de métrica:

    Opción 1: Métrica externa

    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

    Opción 2: Métrica de pods

    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

    Reemplaza lo siguiente:

    • HPA_NAME: el nombre del objeto HorizontalPodAutoscaler
    • NAMESPACE: el espacio de nombres del objeto HorizontalPodAutoscaler, que debe coincidir con el espacio de nombres de la carga de trabajo y el recurso AutoscalingMetric
    • DEPLOYMENT_NAME: el nombre de la Deployment de la carga de trabajo que deseas escalar
    • MIN_REPLICAS: la cantidad mínima de pods en ejecución
    • MAX_REPLICAS: la cantidad máxima de pods en ejecución
    • NAME: el nombre del recurso personalizado AutoscalingMetric que creaste
    • METRIC_NAME: el nombre de la métrica definida en el recurso AutoscalingMetric
    • AVERAGE_VALUE: el valor objetivo de la métrica en el que el escalador automático escala la carga de trabajo

    Cuando crees tu propio objeto HorizontalPodAutoscaler, ten en cuenta lo siguiente:

    • Los objetos AutoscalingMetric, Deployment y HorizontalPodAutoscaler deben estar en el mismo espacio de nombres.
    • En el ejemplo anterior, se usa el par clave-valor type: AverageValue. Ten en cuenta que type: Value también se admite para métricas externas.
    • En el ejemplo anterior, se usa un objeto Deployment solo como ejemplo. También puedes realizar el ajuste de escala automático de cualquier objeto compatible con objetos HorizontalPodAutoscaler, como un objeto ReplicaSet.

  2. Aplica el manifiesto HorizontalPodAutoscaler:

    kubectl apply -f HPA_MANIFEST_FILE.yaml

    Reemplaza HPA_MANIFEST_FILE por el nombre del archivo YAML.

Soluciona problemas de las métricas que se recuperan para el ajuste de escala automático

Para solucionar problemas con la recuperación de métricas, puedes revisar los registros o el estado del recurso personalizado AutoscalingMetric.

El adaptador de métricas de ajuste de escala automático tiene cero réplicas

Cuando inspeccionas la implementación autoscaling-metrics-adapter en kube-system, es posible que notes que tiene cero réplicas.

De forma predeterminada, el adaptador se ejecuta con cero réplicas para conservar los recursos del clúster. Se prevé que esto suceda. La implementación solo se escala a una réplica cuando existe en el clúster un recurso personalizado AutoscalingMetric que requiere procesamiento de PromQL.

Si configuraste un objeto AutoscalingMetric con una consulta de PromQL, pero el adaptador no se escaló, verifica que el objeto se haya creado correctamente en el clúster.

Revisa los registros

Para encontrar problemas con el controlador responsable de obtener métricas de Cloud Monitoring, puedes revisar sus registros.

Puedes ver los registros en la Cloud de Confiance consola de:

  1. Ve a la página Explorador de registros:

    Ir al Explorador de registros

  2. En el panel de consultas, ingresa la consulta siguiente:

    resource.type="k8s_container"
resource.labels.namespace_name="kube-system"
resource.labels.container_name="autoscaling-metrics-adapter"

Como alternativa, para ver los registros con kubectl, ejecuta el siguiente comando:

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

Revisa el estado de AutoscalingMetric

Puedes revisar el estado del recurso personalizado AutoscalingMetric para buscar errores de configuración.

  1. Inspecciona el recurso personalizado AutoscalingMetric:

    kubectl describe autoscalingmetric NAME -n NAMESPACE

    Reemplaza lo siguiente:

    • NAME: el nombre del recurso personalizado AutoscalingMetric que creaste
    • NAMESPACE: el espacio de nombres del recurso personalizado

  2. Para obtener detalles sobre las métricas configuradas, observa el campo Status. Estos detalles incluyen cualquier advertencia sobre errores de configuración y el nombre exacto de la métrica tal como debería aparecer en el objeto HorizontalPodAutoscaler.

    A continuación, se muestra un ejemplo de un estado válido:

    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>

    A continuación, se muestra un ejemplo de un estado con un error de configuración:

    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>

Verifica las consultas de PromQL

Si recuperas métricas de Cloud Monitoring con una consulta de PromQL, un problema con la consulta puede causar errores en la recuperación de la métrica o hacer que se recupere un valor inesperado. Por ejemplo, si esperas que se muestre un porcentaje como un valor de 1 a 100, pero recibes un valor de 0 a 1, el ajuste de escala automático resultante se comporta de forma inesperada.

Puedes probar las consultas de PromQL en Cloud Monitoring para verificar que muestren las métricas esperadas.

Para verificar las consultas, haz lo siguiente:

  1. En la Cloud de Confiance consola de, ve a la página Explorador de métricas.

    Dirígete al Explorador de métricas

  2. En la parte superior del panel Generador de consultas, selecciona la pestaña PromQL.

  3. En el editor de consultas, ingresa la consulta de PromQL que deseas probar.

  4. Haz clic en Run Query para ver las métricas en el gráfico.

¿Qué sigue?