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 relacionados con el ajuste automático de escala horizontal de Pods, desde errores de configuración iniciales en tus objetos HorizontalPodAutoscaler hasta fallas más complejas dentro de la canalización de métricas. Si sigues estos pasos para solucionar problemas, puedes asegurarte de que tus aplicaciones se ajusten de manera eficiente y confiable según la demanda, lo que permite usar de forma eficaz el recurso HorizontalPodAutoscaler.

Esta información es importante para los desarrolladores de aplicaciones que configuran objetos HorizontalPodAutoscaler y deben asegurarse de que sus aplicaciones se ajusten correctamente. También ayuda a los administradores y operadores de la plataforma a solucionar problemas relacionados 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 ajuste de escala 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) para el 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 ajuste de escala 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 de <unknown> indica que HorizontalPodAutoscaler no recuperó la métrica o que la canalización de métricas está interrumpida.
  • Conditions: Muestra si HorizontalPodAutoscaler puede recuperar métricas (AbleToScale) y realizar cálculos de ajuste de escala (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. A menudo, es el primer lugar donde se pueden encontrar mensajes de error o motivos específicos, como FailedGetScale o FailedGetResourceMetric.

Verifica tu 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 se configura para que HorizontalPodAutoscaler la escale.
    • 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étricas más recientes que observó el HorizontalPodAutoscaler.
    • currentReplicas y desiredReplicas: 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 objetivo y sus métricas.
      • ScalingActive: Muestra si HorizontalPodAutoscaler puede calcular y realizar el ajuste de escala.
      • ScalingLimited: Muestra si HorizontalPodAutoscaler desea escalar, pero está limitado por la configuración de minReplicas o maxReplicas.

Cómo ver los registros de eventos

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

  • Visualiza los 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) para el 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, objetivos de métricas no válidos o configuraciones en conflicto.

No se encontró la carga de trabajo objetivo

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 una Deployment o un 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 de HorizontalPodAutoscaler para que apunte al nombre correcto.
  2. Confirma que la carga de trabajo existe: Verifica que la carga de trabajo de destino exista en el mismo espacio de nombres que 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 tu clúster. Si necesitas volver a crear la carga de trabajo, el HorizontalPodAutoscaler la encontrará automáticamente cuando esté disponible y el error se resolverá.
  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 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 comprueba que coincidan.

Después de que HorizontalPodAutoscaler localiza correctamente su objetivo, 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, su sección Events 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 del campo target debe ser averageUtilization.
  • Si type es AverageValue, el valor del campo target debe ser averageValue.

No se permite la etiqueta de métrica

Síntomas

Observarás 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 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 segmentan la misma carga de trabajo

Síntomas

No hay ningún Condition o Reason específico en el 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 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 trata de 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 ajuste a partir de su propio campo spec.metrics, por lo que la combinación permite que el objeto HorizontalPodAutoscaler elegido considere todos los factores, como la CPU y las solicitudes por segundo, de forma conjunta:

  1. Para identificar qué HorizontalPodAutoscalers segmentan la misma carga de trabajo, obtén el manifiesto YAML de 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 instancias en las que diferentes recursos de 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 tienen como objetivo 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 tenían como objetivo 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 ajuste de escala

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 la utilización de recursos como un porcentaje para escalar la carga de trabajo, pero no puede realizar este cálculo porque falta una definición de resources.requests para el recurso correspondiente (cpu o memory) en al menos un contenedor dentro de la especificación del Pod.

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 de Pod

Síntomas

Observarás 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 realizar el ajuste de escala en función del porcentaje de uso de recursos (como cpu o memory), cada contenedor dentro de los Pods a los que se dirige 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

Observarás 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 servicio y la carga de trabajo con ajuste de escala automático.

Solución

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

  1. Busca las etiquetas del 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 de la Deployment a la que se dirige 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 servicios del espacio de nombres para encontrar todos los servicios 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:

    • Para que el selector del servicio deseado sea único, agrega una etiqueta nueva y única al campo spec.template.metadata.labels de tu Deployment. Luego, actualiza el campo spec.selector del Servicio uno deseado para incluir esta nueva etiqueta.
    • Haz que otros selectores de Service sean más restrictivos. Para ello, cambia el campo spec.selector de todos los Services otros 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 actualizado de Service o Deployment.

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 distintas de la CPU o la memoria predeterminadas, pueden ocurrir problemas en la canalización de métricas personalizadas o externas. Esta canalización consta del controlador HorizontalPodAutoscaler, el servidor de la API de métricas 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 permisos, conectividad de red a la fuente de métricas o mensajes que indiquen que no se encontró 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 los 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 externa o personalizada 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 si el valor de matchLabels es incorrecto.

    • Error: Error from server (Service Unavailable): Por lo general, este error indica un problema de conectividad de red, que suele ser un problema de firewall en los clústeres que usan aislamiento de red.

      1. Identifica el servicio 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 el adaptador está escuchando:

        kubectl get service ADAPTER_SERVICE -n ADAPTER_NAMESPACE -o yaml

        Reemplaza lo siguiente:

        • ADAPTER_SERVICE: Es el nombre del servicio de Kubernetes asociado con el adaptador de métricas que implementaste. Este Service es el que encontraste en el paso anterior. Este servicio 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 al 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 llamadas a la API, autenticación o 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 fuente. 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 la métrica o el adaptador no está disponible

Síntomas

Observarás 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 se registraron 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 rendimiento de tu clúster.

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

        Ir a clústeres de Kubernetes

    2. Revisa 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 brevemente durante estos períodos.

    4. Revisa los Registros de auditoría de Cloud en busca de errores relacionados con los componentes del plano de control. Para obtener información sobre cómo ver estos registros, consulta Información de 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 tengan el estado Running y no se hayan reiniciado recientemente:

    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

Observarás 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 puntos de datos que coincidan con tu filtro (lo que es diferente a encontrar una métrica con un valor de 0). La causa más probable de este problema es que la aplicación o la carga de trabajo responsable de generar la métrica personalizada no escribieron datos en Cloud Monitoring durante el período en el 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 extremos de 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 del HorizontalPodAutoscaler.
  4. Investiga si hay errores: Revisa 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 correctos, 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 ajuste de escala no se producen según lo esperado.

HorizontalPodAutoscaler está en buen estado, pero no se ajusta la 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 ajuste.

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 está fuera del rango de 0.9 a 1.1. Por ejemplo, si el objetivo es el 85% de CPU y el uso actual es del 93%, la proporción es de aproximadamente 1.094 (93/85 ≈ 1.094). Como este valor es inferior a 1.1, HorizontalPodAutoscaler no realiza un ajuste de escala vertical.
  • Pods no listos: HorizontalPodAutoscaler solo incluye los Pods con un estado Ready en sus cálculos de ajuste de escala. Los Pods que se atascan con un estado Pending o no se convierten en Ready (debido a verificaciones de estado fallidas o problemas de recursos) se ignoran y pueden impedir el ajuste de escala.
  • Demora 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 entre 15 y 30 segundos entre el momento en que una métrica supera el umbral y el inicio de una acción de ajuste.
  • Latencia de métrica nueva: Cuando un HorizontalPodAutoscaler usa una métrica personalizada nueva por primera vez, es posible que veas una latencia única de varios minutos. Este retraso se produce porque el sistema de supervisión (como Cloud Monitoring) debe crear la nueva serie temporal cuando se escribe el primer punto de datos.
  • 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 ajusta para satisfacer las demandas de la métrica con las necesidades más altas. Por ejemplo, si las métricas de CPU calculan una necesidad de 9 réplicas, pero una métrica de solicitudes por segundo calcula una necesidad de 15, HorizontalPodAutoscaler ajusta la Deployment a 15 réplicas.

Solución

Prueba las siguientes soluciones:

  • Límites de réplicas: Verifica los valores de minReplicas y maxReplicas en el 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 ajuste 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, sondeos de disponibilidad con errores). Para obtener sugerencias sobre cómo solucionar problemas, consulta Depura Pods en la documentación de Kubernetes.
  • Retraso 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 la métrica personalizada.
  • Cálculo de varias métricas: Este es el comportamiento esperado. Si el aumento se basa en una métrica (como las solicitudes por segundo), se anula correctamente el cálculo inferior de otra métrica (como la CPU).

HorizontalPodAutoscaler no puede reducir la escala

Síntomas

El HorizontalPodAutoscaler escala correctamente 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 el escalamiento vertical rápido y el escalamiento vertical basado en información incompleta. Estos son los motivos principales:

  • Uso de varias métricas: El HorizontalPodAutoscaler se ajusta según la métrica que requiere la mayor cantidad de réplicas. Si tienes varias métricas, la carga de trabajo no se reducirá a menos que todas las métricas indiquen que se necesitan menos réplicas. Una métrica que exige un recuento de réplicas alto impide la reducción, incluso si otras son bajas.
  • Métricas no disponibles: Si alguna métrica deja de estar 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á dañada. Este problema es común con las métricas personalizadas basadas en la tasa (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.
  • Retraso en la reducción de escala de la política de ajuste de escala: El campo behavior de HorizontalPodAutoscaler te permite configurar políticas de ajuste de escala. 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, 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 sea más lenta de lo esperado.

Solución

Prueba las siguientes soluciones:

  1. En el caso de varias métricas y métricas 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 relacionados con las 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:

    • Cuando sea posible, usa métricas basadas en indicadores en lugar de métricas basadas en tasas. 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 datos.

  3. En el caso de los retrasos en la reducción de escala vertical de la política de escalamiento, si el período de estabilización predeterminado de cinco minutos para las reducciones de escala vertical es demasiado largo, personalízalo. Inspecciona la sección spec.behavior.scaleDown del manifiesto de HorizontalPodAutoscaler. Puedes reducir el valor de stabilizationWindowSeconds para permitir que el escalador automático reduzca la escala más rápido 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 cae 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 escalar a cero si solo usa métricas de CPU o memoria (Resource). Debes configurar al menos una métrica de External o Object.
  3. Verifica varias métricas: El HPA se ajusta según la métrica que requiere el recuento de réplicas más alto. Si configuras varias métricas, la carga de trabajo no se reducirá a cero, a menos que cada métrica supervisada se evalúe como cero.
  4. Espera a que se abra la ventana 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 pausa las operaciones de reducción para evitar una reducción prematura. Para obtener más información, consulta Soluciona problemas relacionados con la falla del ajuste de escala automático horizontal de Pods para reducir la escala.

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 de 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 el motivo ScalingDisabledReplicaCountZero, lo que indica que la carga de trabajo se redujo manualmente a cero. Por ejemplo, la carga de trabajo se ajustó manualmente 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 lentamente, el aprovisionamiento de nodos podría estar agregando una demora. Para garantizar que la capacidad de procesamiento en espera esté lista cuando se escale desde cero, considera usar búferes de capacidad.

¿Qué sigue?