Soluciona problemas del ajuste de escala automático horizontal de Pods

Cuando el escalado automático horizontal de Pods no funciona como se espera en Google Kubernetes Engine (GKE), es posible que tus cargas de trabajo no se escalen correctamente. Este problema puede impedir que las aplicaciones controlen la carga, lo que puede causar problemas de rendimiento o interrupciones. Es posible que veas que los Pods no aumentan a pesar de que la CPU es alta, que los valores de las métricas se muestran como <unknown> en el estado de tu HorizontalPodAutoscaler o que no se realizan operaciones de escalamiento.

Usa este documento para diagnosticar y resolver problemas habituales con el escalado automático horizontal de Pods, que van desde errores de configuración iniciales en tus HorizontalPodAutoscalers hasta fallas más complejas en la canalización de métricas. Si sigues estos pasos para solucionar problemas, puedes asegurarte de que tus aplicaciones se escalen de manera eficiente y confiable según la demanda.

Esta información es importante para los desarrolladores de aplicaciones que configuran HorizontalPodAutoscalers y necesitan asegurarse de que sus aplicaciones se escalen correctamente. También ayuda a los administradores y operadores de la plataforma a solucionar problemas con la canalización de métricas o la configuración del clúster que afectan a todas las cargas de trabajo con ajuste de escala automático. Para obtener más información sobre los roles comunes y las tareas de ejemplo a las que hacemos referencia en el contenido de Google Cloud , consulta Roles y tareas comunes del usuario de GKE.

Antes de comenzar

  • Asegúrate de usar objetos HorizontalPodAutoscaler con cargas de trabajo escalables, como Deployments y StatefulSets. No puedes usar el escalado automático horizontal de Pods con cargas de trabajo que no se pueden escalar, por ejemplo, DaemonSets.
  • Para obtener los permisos que necesitas para solucionar problemas del escalado automático horizontal de Pods en GKE, lo que incluye inspeccionar objetos HorizontalPodAutoscaler y ver los registros del clúster, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

    Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

    También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

  • Configura la herramienta de línea de comandos de kubectl para que se comunique con tu clúster de GKE:

    gcloud container clusters get-credentials CLUSTER_NAME \
        --location LOCATION \
        --project PROJECT_ID
    

    Reemplaza lo siguiente:

    • CLUSTER_NAME: El nombre de tu clúster.
    • LOCATION: Es la región o zona de Compute Engine (por ejemplo, us-central1 o us-central1-a) del clúster.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

Diagnostica problemas de HorizontalPodAutoscaler

Para diagnosticar problemas con un HorizontalPodAutoscaler, inspecciona el estado y la configuración con los comandos de kubectl o la consola de Google Cloud .

Describe el HorizontalPodAutoscaler

Para ver los cálculos en tiempo real y las decisiones de escalamiento recientes, usa el comando kubectl describe hpa:

kubectl describe hpa HPA_NAME -n NAMESPACE_NAME

Reemplaza lo siguiente:

  • HPA_NAME: Es el nombre de tu objeto HorizontalPodAutoscaler.
  • NAMESPACE_NAME: Es el espacio de nombres de tu objeto HorizontalPodAutoscaler.

El resultado es similar a lo siguiente:

Name:                                                  php-apache-hpa
Namespace:                                             default
Reference:                                             Deployment/php-apache
Metrics: ( current / target )
  resource cpu on pods (as a percentage of request):   1% (1m) / 50%
Min replicas:                                          1
Max replicas:                                          10
Conditions:
  Type            Status  Reason              Message
  ----            ------  ------              -------
  AbleToScale     True    ReadyForNewScale    recommended size matches current size
  ScalingActive   True    ValidMetricFound    the HorizontalPodAutoscaler was able to successfully calculate a replica count
Events:
  Type     Reason              Age   From                       Message
  ----     ------              ----  ----                       -------
  Normal   SuccessfulRescale   39m   horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization...
  Normal   SuccessfulRescale   26m   horizontal-pod-autoscaler  New size: 1; reason: cpu resource utilization...

En el resultado, las siguientes tres secciones te ayudan a diagnosticar el problema:

  • Metrics: Muestra los valores actuales de las métricas en comparación con sus objetivos. Un valor de métrica <unknown> indica que HorizontalPodAutoscaler no recuperó la métrica o que la canalización de métricas está dañada.
  • Conditions: Muestra si el HorizontalPodAutoscaler puede recuperar métricas (AbleToScale) y realizar cálculos de escalamiento (ScalingActive). Un estado False en cualquiera de estas condiciones indica una falla.
  • Events: Registra las acciones de escalamiento, las advertencias y los errores recientes del controlador de HorizontalPodAutoscaler. Suele ser el primer lugar donde se encuentran mensajes de error o motivos específicos, como FailedGetScale o FailedGetResourceMetric.

Verifica el manifiesto de HorizontalPodAutoscaler

El manifiesto YAML de tu objeto HorizontalPodAutoscaler te permite ver información sobre su configuración y su estado actual.

Para ver el manifiesto YAML, selecciona una de las siguientes opciones:

Console

  1. En la consola de Google Cloud , ve a la página Navegador de objetos.

    Ir al Navegador de objetos

  2. En la lista Tipos de objetos, selecciona la casilla de verificación HorizontalPodAutoscaler y haz clic en Aceptar.

  3. Navega al grupo de API autoscaling y, luego, haz clic en la flecha de expansión de HorizontalPodAutoscaler.

  4. Haz clic en el nombre del objeto HorizontalPodAutoscaler que deseas inspeccionar.

  5. Revisa la sección YAML, que muestra la configuración completa del objeto HorizontalPodAutoscaler.

kubectl

Ejecuta el comando siguiente:

kubectl get hpa HPA_NAME -n NAMESPACE_NAME -o yaml

Reemplaza lo siguiente:

  • HPA_NAME: Es el nombre de tu objeto HorizontalPodAutoscaler.
  • NAMESPACE_NAME: Es el espacio de nombres de tu objeto HorizontalPodAutoscaler.

Después de recuperar el manifiesto, busca estas secciones clave:

  • spec (tu configuración):
    • scaleTargetRef: Es la carga de trabajo (como un Deployment) que el HorizontalPodAutoscaler está configurado para escalar.
    • minReplicas y maxReplicas: Son los parámetros de configuración de réplica mínimos y máximos.
    • metrics: Son las métricas configuradas para el escalamiento (por ejemplo, el uso de CPU o las métricas personalizadas).
  • status (el estado en vivo del HorizontalPodAutoscaler):
    • currentMetrics: Son los valores de métrica más recientes que observó el HorizontalPodAutoscaler.
    • currentReplicas y desiredReplicas: Es la cantidad actual de Pods y la cantidad a la que el HorizontalPodAutoscaler desea escalar.
    • conditions: Muestra el estado del HorizontalPodAutoscaler:
      • AbleToScale: Indica si el HorizontalPodAutoscaler puede encontrar su destino y sus métricas.
      • ScalingActive: Muestra si el HorizontalPodAutoscaler puede calcular y realizar el escalamiento.
      • ScalingLimited: Muestra si el HorizontalPodAutoscaler quiere escalar, pero se limita por la configuración de minReplicas o maxReplicas.

Visualiza los registros de eventos

Para obtener estadísticas más detalladas sobre tu objeto HorizontalPodAutoscaler, usa los siguientes tipos de registros:

  • Visualiza eventos de HorizontalPodAutoscaler en Cloud Logging: Usa un filtro de registro para encontrar todos los eventos de HorizontalPodAutoscaler de un clúster específico. Por ejemplo:

    1. En la consola de Google Cloud , accede a la página Explorador de registros.

      Ve al Explorador de registros

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

      resource.type="k8s_cluster"
      resource.labels.cluster_name="CLUSTER_NAME"
      resource.labels.location="LOCATION"
      logName="projects/PROJECT_ID/logs/events"
      jsonPayload.involvedObject.kind="HorizontalPodAutoscaler"
      

      Reemplaza lo siguiente:

      • CLUSTER_NAME: Es el nombre del clúster al que pertenece el HorizontalPodAutoscaler.
      • LOCATION: Es la región o zona de Compute Engine (por ejemplo, us-central1 o us-central1-a) del clúster.
      • PROJECT_ID: Es el ID del proyecto.
    3. Haz clic en Ejecutar consulta y revisa el resultado.

  • Visualiza eventos de escalado automático horizontal de Pods: Estos registros proporcionan registros estructurados y legibles por humanos que explican cómo el HorizontalPodAutoscaler calcula una recomendación, lo que ofrece información detallada sobre su proceso de toma de decisiones.

Soluciona problemas de errores de configuración de HorizontalPodAutoscaler

En las siguientes secciones, se abordan los errores de configuración en el manifiesto de HorizontalPodAutoscaler, como campos con errores de escritura, destinos de métricas no válidos o parámetros de configuración en conflicto.

No se encontró la carga de trabajo de destino

Síntomas

La sección Events tiene una condición de FailedGetScale con un mensaje similar al siguiente:

the HorizontalPodAutoscaler controller was unable to get the target's current scale: WORKLOAD_TYPE.apps "TARGET_WORKLOAD" not found

En esta salida, se incluyen los siguientes valores:

  • WORKLOAD_TYPE: Es el tipo de carga de trabajo, como Deployment o StatefulSet.
  • TARGET_WORKLOAD: Es el nombre de la carga de trabajo.

Causa

El controlador HorizontalPodAutoscaler no puede encontrar la carga de trabajo (como un Deployment o StatefulSet) que está configurado para administrar. Este problema se produce debido a un error de configuración en el campo scaleTargetRef dentro del manifiesto de HorizontalPodAutoscaler. Es posible que el recurso especificado no exista, se haya borrado o tenga un error ortográfico.

Solución

Prueba las siguientes soluciones:

  1. Verifica el campo scaleTargetRef del manifiesto de HorizontalPodAutoscaler: Asegúrate de que los valores de name, kind y apiVersion en el campo scaleTargetRef coincidan exactamente con los metadatos correspondientes de tu carga de trabajo de destino. Si el nombre de la carga de trabajo es incorrecto, actualiza el campo scaleTargetRef del HorizontalPodAutoscaler para que apunte al nombre correcto.
  2. Confirma que la carga de trabajo exista: Verifica que la carga de trabajo de destino exista en el mismo espacio de nombres que el HorizontalPodAutoscaler. Puedes verificarlo con un comando como kubectl get deployment DEPLOYMENT_NAME. Si borraste la carga de trabajo de forma intencional, borra el objeto HorizontalPodAutoscaler correspondiente para limpiar el clúster. Si necesitas volver a crear la carga de trabajo, el HorizontalPodAutoscaler la encuentra automáticamente después de que esté disponible y se resuelva el error.
  3. Verifica que el HorizontalPodAutoscaler y la carga de trabajo estén en el mismo espacio de nombres: El HorizontalPodAutoscaler y su carga de trabajo de destino deben estar en el mismo espacio de nombres. Si olvidas especificar un espacio de nombres cuando creas un objeto con comandos de kubectl, Kubernetes coloca el objeto en el espacio de nombres default. Este comportamiento puede causar una discrepancia si tu HorizontalPodAutoscaler está en el espacio de nombres default y tu carga de trabajo está en otro, o viceversa. Verifica el espacio de nombres de ambos objetos y asegúrate de que coincidan.

Después de que el HorizontalPodAutoscaler ubica correctamente su destino, la condición AbleToScale se convierte en True y el mensaje cambia a the HorizontalPodAutoscaler controller was able to get the target's current scale.

Métricas no válidas

Síntomas

Si el HorizontalPodAutoscaler no puede calcular las réplicas necesarias debido a un problema de configuración, en su sección Events, se muestra un motivo de FailedComputeMetricsReplicas con un mensaje similar al siguiente:

invalid metrics (1 invalid out of 1)

Causa

Por lo general, este error significa que hay una discrepancia entre la métrica type y el target que definiste en el manifiesto de HorizontalPodAutoscaler. Por ejemplo, es posible que hayas especificado un type de Utilization, pero proporcionaste un valor objetivo de averageValue en lugar de averageUtilization.

Solución

Corrige el manifiesto de HorizontalPodAutoscaler para que el valor del campo target se alinee con la métrica type:

  • Si type es Utilization, el valor en el campo target debe ser averageUtilization.
  • Si type es AverageValue, el valor en el campo target debe ser averageValue.

No se permite la etiqueta de métrica

Síntomas

Observas el siguiente error:

unable to fetch metrics from external metrics API: googleapi: Error 400: Metric label: 'LABEL_NAME' is not allowed

En este resultado, LABEL_NAME es el nombre de la etiqueta incorrecta.

Causa

El manifiesto de HorizontalPodAutoscaler especifica una clave de etiqueta no válida en la sección metric.selector.matchLabels, y Cloud Monitoring no reconoce ni permite esta clave para la métrica.

Solución

Para solucionar este problema, haz lo siguiente:

  1. Identifica el nombre de la etiqueta no permitida en el mensaje de error.
  2. Quita o corrige esta clave de etiqueta en la sección metric.selector.matchLabels del manifiesto de tu HorizontalPodAutoscaler.
  3. Para encontrar una clave de etiqueta válida y filtrable, consulta la documentación de Cloud Monitoring para esa métrica.

Varios HorizontalPodAutoscalers se orientan a la misma carga de trabajo

Síntomas

No hay un Condition o Reason específico dentro del estado de un HorizontalPodAutoscaler que indique directamente este conflicto. En su lugar, puedes observar los siguientes síntomas:

  • El recuento de réplicas de la carga de trabajo puede fluctuar de forma inesperada.
  • Es posible que las decisiones de escalamiento no parezcan corresponder a las métricas definidas en ningún HorizontalPodAutoscaler individual.
  • Cuando veas los eventos, es posible que veas eventos SuccessfulRescale alternados o contradictorios de diferentes objetos HorizontalPodAutoscaler.

Causa

Este problema se produce porque más de un objeto HorizontalPodAutoscaler dentro del mismo espacio de nombres especifica exactamente la misma carga de trabajo en el campo spec.scaleTargetRef. Cada HorizontalPodAutoscaler calcula de forma independiente los recuentos de réplicas y, luego, intenta escalar la carga de trabajo según su propio conjunto de métricas y objetivos. Kubernetes no bloquea esta configuración, pero genera ajustes de escalamiento erráticos porque los HorizontalPodAutoscalers compiten entre sí.

Solución

Para evitar conflictos, define todas las métricas de escalamiento en un solo objeto HorizontalPodAutoscaler. Cada HorizontalPodAutoscaler calcula las necesidades de escalamiento desde su propio campo spec.metrics, por lo que combinarlos permite que el objeto HorizontalPodAutoscaler elegido considere todos los factores, como la CPU y las solicitudes por segundo, juntos:

  1. Para identificar qué HorizontalPodAutoscalers se orientan a la misma carga de trabajo, obtén el manifiesto YAML para cada objeto HorizontalPodAutoscaler. Presta mucha atención al campo spec.scaleTargetRef en el resultado.

    kubectl get hpa -n NAMESPACE_NAME -o yaml
    

    Reemplaza NAMESPACE_NAME por el espacio de nombres de tu objeto HorizontalPodAutoscaler.

    Busca cualquier instancia en la que diferentes recursos HorizontalPodAutoscaler tengan los mismos valores para apiVersion, kind y name dentro de su campo scaleTargetRef.

  2. Consolida las métricas en un solo objeto HorizontalPodAutoscaler:

    1. Elige un objeto HorizontalPodAutoscaler para conservar. Este HorizontalPodAutoscaler será el que modifiques.
    2. Examina la sección spec.metrics en el manifiesto de cada uno de los otros objetos HorizontalPodAutoscaler que se orientan a la misma carga de trabajo.
    3. Copia las definiciones de métricas que deseas conservar de las secciones spec.metrics de los objetos HorizontalPodAutoscaler duplicados.
    4. Pega estas definiciones de métricas copiadas en el array spec.metrics del HorizontalPodAutoscaler que decidiste conservar.
  3. Aplica los cambios:

    kubectl apply -f MANIFEST_NAME
    

    Reemplaza MANIFEST_NAME por el nombre del manifiesto de HorizontalPodAutoscaler que decidiste conservar.

  4. Borra los otros objetos HorizontalPodAutoscaler que se orientaban a la misma carga de trabajo:

    kubectl delete hpa DUPLICATE_MANIFEST_NAME -n NAMESPACE_NAME
    

    Reemplaza DUPLICATE_MANIFEST_NAME por el nombre del objeto HorizontalPodAutoscaler redundante que deseas borrar.

Soluciona problemas de errores de cargas de trabajo y Service

En las siguientes secciones, se abordan los errores causados por la carga de trabajo de destino o sus Services asociados, en lugar del objeto HorizontalPodAutoscaler en sí.

Faltan solicitudes de recursos para el cálculo del escalamiento

Síntomas

La condición ScalingActive es False con un Reason de FailedGetResourceMetric. Por lo general, también verás un mensaje similar al siguiente:

the HorizontalPodAutoscaler was unable to compute the replica count

Causa

El HorizontalPodAutoscaler necesita calcular el uso de recursos como un porcentaje para escalar la carga de trabajo, pero no puede realizar este cálculo porque al menos un contenedor dentro de la especificación del Pod no tiene una definición de resources.requests para el recurso correspondiente (cpu o memory).

Solución

Para resolver este problema, actualiza el manifiesto del Pod dentro de tu Deployment, StatefulSet o cualquier otro controlador para incluir un campo resources.requests para el recurso (cpu o memory) en el que el HorizontalPodAutoscaler intenta escalar para todos los contenedores del Pod. Por ejemplo:

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
# Multiple lines are omitted here
spec:
  containers:
  - name: example-container
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"

No se pudieron recuperar las métricas del Pod

Síntomas

Observas un mensaje persistente similar al siguiente:

unable to fetch pod metrics for pod

Es normal ver este mensaje de forma temporal cuando se inicia el servidor de métricas.

Causa

Para escalar según el porcentaje de uso de recursos (como cpu o memory), cada contenedor dentro de los Pods a los que se orienta el objeto HorizontalPodAutoscaler debe tener definido el campo resources.requests para ese recurso específico. De lo contrario, el HorizontalPodAutoscaler no puede realizar los cálculos que necesita y no realiza ninguna acción en relación con esa métrica.

Solución

Si estos mensajes de error persisten y notas que los Pods no se escalan para tu carga de trabajo, verifica que hayas especificado solicitudes de recursos para cada contenedor en tu carga de trabajo.

Varios servicios seleccionan el mismo destino

Síntomas

Observas el siguiente error:

multiple services selecting the same target of HPA_NAME: SERVICE_NAME

En esta salida, se incluyen los siguientes valores:

  • HPA_NAME: Es el nombre del HorizontalPodAutoscaler.
  • SERVICE_NAME: Es el nombre de un Service.

Causa

El ajuste de escala automático basado en el tráfico está configurado, pero más de un Service de Kubernetes está orientado al campo scaleTargetRef del HorizontalPodAutoscaler. El ajuste de escala automático basado en el tráfico solo admite una relación uno a uno entre el Service y la carga de trabajo con ajuste de escala automático.

Solución

Para solucionar este problema, asegúrate de que solo un selector de etiquetas del Service coincida con los Pods de tu carga de trabajo:

  1. Busca las etiquetas de Pod de tu carga de trabajo:

    kubectl get deployment HPA_TARGET_DEPLOYMENT \
        -n NAMESPACE \
        -o jsonpath='{.spec.template.metadata.labels}'
    

    Reemplaza lo siguiente:

    • HPA_TARGET_DEPLOYMENT: Es el nombre del Deployment al que se orienta el HorizontalPodAutoscaler.
    • NAMESPACE: Es el espacio de nombres del Deployment.

    El resultado es similar a lo siguiente:

    {"app":"my-app", "env":"prod"}
    
  2. Revisa el campo spec.selector de todos los Services del espacio de nombres para encontrar todos los que coincidan con esas etiquetas.

    kubectl get services -n NAMESPACE -o yaml
    

    Identifica cada Service cuyo selector coincida con las etiquetas del paso anterior. Por ejemplo, tanto {"app": "my-app"} como {"app": "my-app", "env": "prod"} coinciden con las etiquetas de Pod de ejemplo.

  3. Para resolver el conflicto, elige una de las siguientes opciones:

    • Agrega una etiqueta nueva y única al campo spec.template.metadata.labels de tu Deployment para que el selector del Service previsto sea único. Luego, actualiza el campo spec.selector del Service único previsto para incluir esta etiqueta nueva.
    • Haz que otros selectores de Service sean más restrictivos cambiando el campo spec.selector de todos los demás Services en conflicto para que sean más restrictivos y ya no coincidan con los Pods de tu carga de trabajo.
  4. Aplica los cambios:

    kubectl apply -f MANIFEST_NAME
    

    Reemplaza MANIFEST_NAME por el nombre del archivo YAML que contiene el manifiesto de Service o Deployment actualizado.

Soluciona problemas relacionados con la API de Metrics y la disponibilidad de los datos

En las siguientes secciones, se explica cómo resolver los errores que se producen cuando el HorizontalPodAutoscaler intenta comunicarse con una API de Metrics o consultar un backend de métricas.

Soluciona problemas de métricas personalizadas y externas

Cuando tu HorizontalPodAutoscaler depende de métricas de fuentes que no sean la CPU o la memoria predeterminadas, pueden ocurrir problemas dentro de la canalización de métricas personalizadas o externas. Esta canalización consta del controlador HorizontalPodAutoscaler, el servidor de la API de Metrics de Kubernetes, el adaptador de métricas y la fuente de métricas (por ejemplo, Cloud Monitoring o Prometheus), como se muestra en el siguiente diagrama:

Canalización de métricas de HPA
que muestra los componentes: controlador de HPA, servidor de la API de Kubernetes, adaptador de métricas
y fuente de métricas.

Síntomas

Los síntomas más comunes de un problema en la canalización de métricas son los siguientes:

  • El valor de la métrica se muestra como <unknown>.
  • Los eventos de HorizontalPodAutoscaler muestran errores como FailedGetExternalMetric o FailedGetCustomMetric.

Causa

Hay un problema en la canalización de métricas personalizadas o externas.

Solución

Sigue estos pasos para depurar la canalización:

  1. Verifica si el adaptador de métricas está registrado y disponible: El adaptador de métricas debe registrarse en el servidor de la API principal de Kubernetes para entregar métricas. Esta acción es la forma más directa de ver si el adaptador se está ejecutando y si el servidor de la API puede acceder a él:

    kubectl get apiservice | grep -E 'NAME|metrics.k8s.io'
    

    En el resultado, deberías ver las entradas v1beta1.custom.metrics.k8s.io o v1beta1.external.metrics.k8s.io y un valor de True en la columna Available. Por ejemplo:

    NAME                   SERVICE                      AVAILABLE   AGE
    v1beta1.metrics.k8s.io kube-system/metrics-server   True        18d
    
    • Si el valor de la columna Available es False o falta, es probable que el adaptador haya fallado o esté mal configurado. Verifica los registros del Pod del adaptador en el espacio de nombres kube-system o custom-metrics para detectar errores relacionados con los permisos, la conectividad de red con la fuente de la métrica o los mensajes que indican que no se pudo encontrar la métrica.

    • Si el valor es True, continúa con el siguiente paso.

  2. Consulta la API de métricas directamente: Si el adaptador está disponible, omite el HorizontalPodAutoscaler y solicita tu métrica directamente a la API de Kubernetes. Este comando prueba toda la canalización, desde el servidor de la API hasta el adaptador de métricas y la fuente de datos.

    Para consultar las métricas externas, ejecuta el siguiente comando:

    kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/NAMESPACE_NAME/METRIC_NAME" | jq .
    

    Para consultar las métricas personalizadas de Pods, ejecuta el siguiente comando:

    kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/NAMESPACE_NAME/pods/*/METRIC_NAME" | jq .
    

    Reemplaza lo siguiente:

    • NAMESPACE_NAME: Es el espacio de nombres en el que se ejecutan tus Pods.
    • METRIC_NAME: Es el nombre de la métrica personalizada o externa que intentas consultar. Por ejemplo, requests_per_second o queue_depth.
  3. Analiza el resultado del comando: El resultado de los comandos anteriores te indica dónde está el problema. Elige la situación que coincida con tu resultado:

    • Respuesta JSON correcta con un valor: La canalización de métricas funciona correctamente. Es probable que el problema sea un error de configuración en tu manifiesto de HorizontalPodAutoscaler. Verifica si hay errores ortográficos en el nombre de la métrica o un matchLabels incorrecto.
    • Error: Error from server (Service Unavailable): Este error suele indicar un problema de conectividad de red, que, a menudo, es un problema de firewall en los clústeres que usan aislamiento de red.

      1. Identifica el Service del adaptador de métricas. Por lo general, se encuentra en el espacio de nombres custom-metrics o kube-system:

        kubectl get service -n custom-metrics,kube-system | grep -E 'adapter|metrics'
        
      2. Busca el puerto en el que escucha el adaptador:

        kubectl get service ADAPTER_SERVICE -n ADAPTER_NAMESPACE -o yaml
        

        Reemplaza lo siguiente:

        • ADAPTER_SERVICE: Es el nombre del Service de Kubernetes asociado con el adaptador de métricas que implementaste. Este Service es el que encontraste en el paso anterior. Este Service expone la funcionalidad del adaptador a otras partes del clúster, incluido el servidor de la API de Kubernetes.
        • ADAPTER_NAMESPACE: Es el espacio de nombres en el que reside el servicio del adaptador (por ejemplo, custom-metrics o kube-system).
      3. Busca las reglas de firewall de entrada para el plano de control de tu clúster:

        gcloud compute firewall-rules list \
            --filter="name~gke-CLUSTER_NAME-[0-9a-z]*-master"
        

        Reemplaza CLUSTER_NAME por el nombre de tu clúster.

      4. Agrega el targetPort del adaptador a la regla:

        1. Describe la regla actual para ver los puertos permitidos existentes:

          gcloud compute firewall-rules describe FIREWALL_RULE_NAME
          

          Reemplaza FIREWALL_RULE_NAME por el nombre de la regla de firewall que rige el tráfico de red hacia el plano de control de tu clúster de Kubernetes.

        2. Actualiza la regla para agregar el puerto del adaptador a la lista:

          gcloud compute firewall-rules update FIREWALL_RULE_NAME \
              --allow tcp:443,tcp:10250,tcp:ADAPTER_PORT
          

          Reemplaza ADAPTER_PORT por el puerto de red en el que escucha el adaptador de métricas.

      5. Asegúrate de que las políticas de red de Kubernetes no bloqueen el tráfico a los Pods del adaptador de métricas:

        kubectl get networkpolicy -n custom-metrics,kube-system
        

        Revisa las políticas para verificar que permitan el tráfico de entrada desde el plano de control o el servidor de la API hasta el ADAPTER_SERVICE en el ADAPTER_PORT.

    • Una lista vacía []: este resultado significa que el adaptador se está ejecutando, pero no puede recuperar la métrica específica, lo que indica un problema con la configuración del adaptador o con la fuente de la métrica.

      • Problemas con el Pod del adaptador: Inspecciona los registros del Pod o los Pods del adaptador de métricas para detectar errores relacionados con las llamadas a la API, la autenticación o la recuperación de métricas. Para inspeccionar los registros, haz lo siguiente:

        1. Busca el nombre del Pod del adaptador:

          kubectl get pods -n ADAPTER_NAMESPACE
          
        2. Consulta sus registros:

          kubectl logs ADAPTER_POD_NAME \
              -n ADAPTER_NAMESPACE
          

          Reemplaza lo siguiente:

          • ADAPTER_POD_NAME: Es el nombre del Pod del adaptador que identificaste en el paso anterior.
          • ADAPTER_NAMESPACE: Es el espacio de nombres en el que reside el Pod del adaptador (por ejemplo, custom-metrics o kube-system).
      • No hay datos en la fuente: Es posible que la métrica no exista en el sistema de origen. Usa una herramienta de supervisión, como el Explorador de métricas, para confirmar que la métrica existe y tiene el nombre y las etiquetas correctos.

No se encontraron versiones de métricas o el adaptador no está disponible

Síntomas

Observas el siguiente error:

unable to fetch metrics from custom metrics API: no known available metric versions found

Causa

Este error indica una interrupción de la comunicación dentro del clúster, no un problema con la fuente de métricas (como Cloud Monitoring). Entre las causas comunes, se incluyen las siguientes:

  • El servidor de la API de Kubernetes no está disponible temporalmente (por ejemplo, durante una actualización del clúster o una reparación del plano de control).
  • Los Pods del adaptador de métricas (por ejemplo, custom-metrics-stackdriver-adapter) no están en buen estado, no se están ejecutando o no están registrados correctamente en el servidor de la API.

Solución

Este problema suele ser temporal. Si el problema persiste, prueba las siguientes soluciones:

  1. Verifica el estado del plano de control de Kubernetes:

    1. En la consola de Google Cloud , consulta el estado y el estado de tu clúster.

      1. Ir a la página Clústeres de Kubernetes

        Ir a clústeres de Kubernetes

    2. Verifica las columnas Estado y Notificaciones de tu clúster.

    3. Haz clic en Notificaciones para buscar operaciones en curso, como actualizaciones o reparaciones. Es posible que el servidor de la API no esté disponible durante estos períodos.

    4. Revisa los Registros de auditoría de Cloud para ver si hay errores relacionados con los componentes del plano de control. Para obtener información sobre cómo ver estos registros, consulta Información sobre los registros de auditoría de GKE.

  2. Verifica el estado y los registros de los Pods del adaptador de métricas: Asegúrate de que los Pods del adaptador de métricas estén en el estado Running y no tengan reinicios recientes:

    kubectl get pods -n custom-metrics,kube-system -o wide
    

    Si el estado de un Pod es diferente de Running o tiene un recuento de reinicios alto, investiga el Pod para encontrar la causa raíz. Para obtener sugerencias sobre cómo solucionar problemas, consulta Depura Pods en la documentación de Kubernetes.

  3. Verifica que las APIs de métricas estén registradas y disponibles:

    kubectl get apiservice | grep metrics.k8s.io
    

    Si las APIs de métricas están en buen estado, el resultado es similar al siguiente:

    NAME                            SERVICE                                             AVAILABLE   AGE
    v1beta1.custom.metrics.k8s.io   custom-metrics/custom-metrics-stackdriver-adapter   True        18d
    v1beta1.external.metrics.k8s.io custom-metrics/custom-metrics-stackdriver-adapter   True        18d
    v1beta1.metrics.k8s.io          kube-system/metrics-server                          True        18d
    

    Si la columna AVAILABLE tiene un valor de False, la columna Message en el manifiesto completo de APIService podría proporcionar más detalles.

    Puedes ver el manifiesto completo con el siguiente comando:

    kubectl get apiservice API_SERVICE_NAME -o yaml
    

    Reemplaza API_SERVICE_NAME por el nombre del objeto APIService, como v1beta1.custom.metrics.k8s.io.

La consulta de métricas no devuelve series temporales

Síntomas

Observas el siguiente error:

unable to fetch metrics from custom or external metrics API: googleapi: Error
400: The supplied filter [...] query will not return any time series

Causa

La consulta enviada a Cloud Monitoring era válida, pero no devolvió datos. Esto significa que no existen datos que coincidan con tu filtro (lo que es diferente de encontrar una métrica con un valor de 0). El motivo más probable de este problema es que la aplicación o la carga de trabajo responsable de generar la métrica personalizada no escribía datos en Cloud Monitoring durante el tiempo en que se informaron los errores.

Solución

Prueba las siguientes soluciones:

  1. Verifica la configuración: Asegúrate de que los nombres y las etiquetas de las métricas en tu objeto HorizontalPodAutoscaler coincidan exactamente con los que emite la aplicación.
  2. Verifica los permisos: Confirma que la aplicación esté configurada correctamente con los permisos y los endpoints de la API necesarios para publicar métricas en Cloud Monitoring.
  3. Confirma la actividad de la aplicación: Verifica que la aplicación responsable de la métrica estuviera operativa y que intentara enviar datos a Cloud Monitoring durante el período en el que se produjeron las advertencias de HorizontalPodAutoscaler.
  4. Investiga si hay errores: Verifica los registros de la aplicación del mismo período para detectar errores explícitos relacionados con la emisión de métricas, como fallas de conexión, credenciales no válidas o problemas de formato.

Soluciona problemas de comportamientos de escalamiento en buen estado, pero inesperados

En las siguientes secciones, se abordan situaciones en las que la configuración de HorizontalPodAutoscaler es válida y las métricas están disponibles, pero las acciones de escalamiento no se producen como se espera.

HorizontalPodAutoscaler está en buen estado, pero no escala

Síntomas

El HorizontalPodAutoscaler parece estar en buen estado, sus condiciones informan True y no muestra errores en sus eventos. Sin embargo, aún no realiza ninguna acción de escalamiento.

Causa

Varios factores pueden causar este comportamiento esperado:

  • Límites de réplicas: La cantidad actual de réplicas ya se encuentra en el límite establecido por el campo minReplicas o maxReplicas en la configuración de HorizontalPodAutoscaler.
  • Período de tolerancia: Kubernetes usa un período de tolerancia predeterminado del 10% para evitar el escalamiento en fluctuaciones menores de las métricas. El escalamiento solo se produce si la proporción entre la métrica actual y la métrica objetivo queda fuera del rango de 0.9 a 1.1. Por ejemplo, si el objetivo es un 85% de CPU y el uso actual es del 93%, la proporción es de aproximadamente 1.094 (93/85≈1.094). Debido a que este valor es menor que 1.1, el HorizontalPodAutoscaler no escala verticalmente.
  • Pods no listos: HorizontalPodAutoscaler incluye solo Pods con un estado Ready en sus cálculos de escalamiento. Los Pods que se encuentran bloqueados con un estado Pending o que no se convierten en Ready (debido a fallas en las verificaciones de estado o problemas de recursos) se ignoran y pueden impedir el escalamiento.
  • Retraso del período de sincronización: El controlador de HorizontalPodAutoscaler verifica las métricas de forma periódica. Es normal que haya una demora de 15 a 30 segundos entre el momento en que una métrica cruza el umbral y el inicio de una acción de escalamiento.
  • Latencia de métricas nuevas: Cuando un HorizontalPodAutoscaler usa una métrica personalizada nueva por primera vez, es posible que veas una latencia única de varios minutos. Esta demora se produce porque el sistema de supervisión (como Cloud Monitoring) debe crear la serie temporal nueva cuando se escribe el primer dato.
  • Cálculo de varias métricas: Cuando configuras varias métricas, el HorizontalPodAutoscaler calcula el recuento de réplicas requerido para cada métrica de forma independiente y, luego, elige el valor calculado más alto como la cantidad final de réplicas. Debido a este comportamiento, tu carga de trabajo se escala para satisfacer las demandas de la métrica con las necesidades más altas. Por ejemplo, si las métricas de CPU calculan que se necesitan 9 réplicas, pero una métrica de solicitudes por segundo calcula que se necesitan 15, el HorizontalPodAutoscaler escala la Deployment a 15 réplicas.

Solución

Prueba las siguientes soluciones:

  • Límites de réplicas: Verifica los valores minReplicas y maxReplicas en tu manifiesto de HorizontalPodAutoscaler o en el resultado del comando kubectl describe. Ajusta estos límites si impiden el escalamiento necesario.
  • Ventana de tolerancia: Si se requiere un escalamiento dentro de la tolerancia predeterminada, configura un valor de tolerancia diferente. De lo contrario, espera a que la métrica se mueva fuera de la proporción de 0.9 a 1.1.
  • Pods no listos: Investiga por qué los Pods están en estado Pending o no están en estado Ready y resuelve los problemas subyacentes (por ejemplo, restricciones de recursos o fallas en los sondeos de preparación). Para obtener sugerencias sobre cómo solucionar problemas, consulta Depura Pods en la documentación de Kubernetes.
  • Demora en el período de sincronización y latencia de métricas nuevas: Estas latencias son normales. Espera a que se complete el período de sincronización o a que se cree la nueva serie temporal de métricas personalizadas.
  • Cálculo de varias métricas: Este es el comportamiento esperado. Si el escalamiento vertical se produce en función de una métrica (como las solicitudes por segundo), se anula correctamente el cálculo más bajo de otra métrica (como la CPU).

HorizontalPodAutoscaler no puede reducir la escala

Síntomas

El HorizontalPodAutoscaler escala de forma correcta la carga de trabajo, pero no logra reducirla, incluso cuando las métricas, como el uso de CPU, son bajas.

Causa

Este comportamiento está diseñado para evitar que se aumente o reduzca la escala verticalmente con rapidez o que se reduzca la escala verticalmente en función de información incompleta. Estos son los motivos principales:

  • Uso de varias métricas: El HorizontalPodAutoscaler escala según la métrica que requiere la mayor cantidad de réplicas. Si tienes varias métricas, la carga de trabajo no reducirá la escala verticalmente, a menos que todas las métricas indiquen que se necesitan menos réplicas. Una métrica que exige un recuento alto de réplicas evita la reducción de escala, incluso si otras son bajas.
  • Métricas no disponibles: Si alguna métrica no está disponible (a menudo, se muestra como <unknown>), el HorizontalPodAutoscaler se niega de forma conservadora a reducir la escala de la carga de trabajo. No puede determinar si falta la métrica porque el uso es realmente cero o porque la canalización de métricas está rota. Este problema es común con las métricas personalizadas basadas en tasas (por ejemplo, messages_per_second), que pueden dejar de informar datos cuando no hay actividad, lo que hace que HorizontalPodAutoscaler vea la métrica como no disponible y detenga las operaciones de reducción de escala vertical.
  • Demora de reducción de escala vertical de la política de escalamiento: El campo behavior de HorizontalPodAutoscaler te permite configurar políticas de escalamiento. La política predeterminada para reducir la escala verticalmente incluye un período de estabilización de 300 segundos (cinco minutos). Durante este período, el HorizontalPodAutoscaler no reducirá el recuento de réplicas, incluso cuando los valores de las métricas hayan caído por debajo del umbral objetivo. Esta ventana evita las fluctuaciones rápidas, pero puede hacer que la reducción de escala sea más lenta de lo esperado.

Solución

Prueba las siguientes soluciones:

  1. En el caso de las métricas múltiples y no disponibles, diagnostica la métrica que causa problemas:

    kubectl describe hpa HPA_NAME -n NAMESPACE_NAME
    

    En el resultado, busca en la sección Metrics cualquier métrica con un estado de <unknown> y, en la sección Events, advertencias como FailedGetCustomMetric o FailedGetExternalMetric. Para obtener información detallada sobre la depuración de canalizaciones, consulta la sección Soluciona problemas de métricas personalizadas y externas.

  2. En el caso de las métricas no disponibles, si una métrica deja de estar disponible durante períodos de tráfico bajo (común con las métricas basadas en tasas), prueba una de las siguientes soluciones:

    • Usa métricas basadas en indicadores en lugar de métricas basadas en tasas siempre que sea posible. Una métrica de indicador, como la cantidad total de mensajes en una cola (por ejemplo, subscription o num_undelivered_messages), informa un valor de forma coherente, incluso si ese valor es 0, lo que permite que HorizontalPodAutoscaler tome decisiones de escalamiento de forma confiable.
    • Asegúrate de que tu fuente de métricas informe valores cero. Si controlas la métrica personalizada, configúrala para que publique un 0 durante los períodos de inactividad en lugar de no enviar ningún dato.
  3. En el caso de los retrasos en la reducción de escala de la política de escalamiento, si el período de estabilización predeterminado de cinco minutos para las reducciones de escala es demasiado largo, personalízalo. Inspecciona la sección spec.behavior.scaleDown del manifiesto de HorizontalPodAutoscaler. Puedes reducir el stabilizationWindowSeconds para permitir que el escalador automático reduzca la escala verticalmente con mayor rapidez después de que disminuyan las métricas. Para obtener más información sobre la configuración de estas políticas, consulta Políticas de escalamiento en la documentación de Kubernetes.

Soluciona problemas de escalamiento de cargas de trabajo de GKE hacia y desde cero con HPA

Esta sección te ayuda a diagnosticar problemas cuando configuras cargas de trabajo para escalar a cero y desde cero con HPA (minReplicas: 0) en GKE 1.37 o versiones posteriores.

La carga de trabajo no se reduce a cero

Si tu carga de trabajo permanece en una o más réplicas cuando la demanda disminuye a cero, verifica lo siguiente:

  1. Verifica minReplicas: Asegúrate de que el par campo-valor minReplicas: 0 esté configurado en tu manifiesto de HorizontalPodAutoscaler.
  2. Verifica los tipos de métricas: El HPA no puede reducir la escala a cero si solo usa métricas de CPU o memoria (Resource). Debes configurar al menos una métrica External o Object.
  3. Verifica varias métricas: El HPA escala según la métrica que requiere el mayor recuento de réplicas. Si configuras varias métricas, la carga de trabajo no se reduce a cero, a menos que todas las métricas supervisadas se evalúen como cero.
  4. Espera a que se complete el período de estabilización de reducción de escala: De forma predeterminada, GKE espera cinco minutos (scaleDown.stabilizationWindowSeconds: 300) de demanda cero continua antes de reducir la escala de una a cero réplicas.
  5. Verifica si hay métricas no disponibles: Si el valor de alguna métrica se muestra como <unknown>, el HPA detiene las operaciones de reducción de escala para evitar una reducción prematura. Para obtener más información, consulta Soluciona problemas del Horizontal Pod Autoscaler que no puede reducir la escala verticalmente.

La carga de trabajo no escala verticalmente desde cero

Si tu carga de trabajo permanece en cero réplicas cuando aumenta la demanda, verifica lo siguiente:

  1. Inspecciona el HorizontalPodAutoscaler: Ejecuta el comando kubectl describe hpa HPA_NAME y verifica las siguientes secciones en el resultado:

    • Sección Métricas: Verifica que el valor de la métrica sea mayor que cero y que no se muestre como <unknown>. Si falta la métrica o no se actualiza, verifica que la fuente externa (como Pub/Sub) publique eventos y que Cloud Monitoring los reciba.
    • Sección Condiciones:
      • Estado correcto de cero réplicas: Verifica que las condiciones muestren AbleToScale: True, ScalingActive: True y ScaledToZero: True (con el motivo ScaledToZero). En este estado, GKE escala automáticamente la carga de trabajo cuando aumenta la demanda.
      • Se detectó una anulación externa: Verifica si el valor de la condición ScalingActive es False con el motivo ScalingDisabledExternalScaleToZero o ScalingDisabledReplicaCountZero, lo que indica que la carga de trabajo se redujo manualmente a cero. Por ejemplo, la carga de trabajo se escaló de forma manual con el comando kubectl scale, que pausa el ajuste de escala automático para evitar cambios conflictivos.
    • Resolución: Para reanudar el ajuste de escala automático, vuelve a escalar de forma manual el Deployment a una o más réplicas:

      kubectl scale deployment DEPLOYMENT_NAME --replicas=1
      
  2. Verifica la latencia de inicio en frío: Si la carga de trabajo se inicia con lentitud, es posible que el aprovisionamiento de nodos agregue un retraso. Para garantizar que la capacidad de procesamiento en espera esté lista cuando se escale desde cero, considera usar búferes de capacidad.

¿Qué sigue?