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

Cuando el escalado automático horizontal de Pods no funciona según lo esperado 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 la CPU alta, que los valores de las métricas se muestran como <unknown> en el estado de HorizontalPodAutoscaler o que no se producen operaciones de ajuste de escala.

Usa este documento para diagnosticar y resolver problemas comunes 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 escale de manera eficiente y confiable según la demanda, lo que permite usar de manera eficaz el recurso HorizontalPodAutoscaler.

Esta información es importante para los desarrolladores de aplicaciones que configuran objetos HorizontalPodAutoscaler y necesitan 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 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 Cloud de Confiance by S3NS , 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 ajuste automático de escala 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) del clúster.
    • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance by S3NS .

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 Cloud de Confiance .

Describe el HorizontalPodAutoscaler

Para ver los cálculos en tiempo real y las decisiones de ajuste 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). El estado False en cualquiera de estas condiciones indica una falla.
  • Events: Registra las acciones de ajuste de escala, las advertencias y los errores recientes del controlador de HorizontalPodAutoscaler. A menudo, es el primer lugar donde se pueden encontrar mensajes o motivos de error 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 Cloud de Confiance , ve a la página Navegador de objetos.

    Ir al Navegador de objetos

  2. En la lista Object Kinds, selecciona la casilla de verificación HorizontalPodAutoscaler y haz clic en OK.

  3. Navega al grupo de APIs 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 una Deployment) que el HorizontalPodAutoscaler está configurado para escalar.
    • minReplicas y maxReplicas: Son los parámetros de configuración de réplicas mínimos y máximos.
    • metrics: Son las métricas configuradas para el ajuste de escala (por ejemplo, el uso de CPU o las métricas personalizadas).
  • status (el estado activo de 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 destino y sus métricas.
      • ScalingActive: Muestra si se permite que HorizontalPodAutoscaler calcule y realice el ajuste de escala.
      • ScalingLimited: Muestra si el HorizontalPodAutoscaler desea escalar, pero está limitado por la configuración de minReplicas o maxReplicas.

Cómo ver registros de eventos

Para obtener información más detallada sobre tu objeto HorizontalPodAutoscaler, usa los siguientes tipos de registros:

  • Cómo ver eventos de HorizontalPodAutoscaler en Cloud Logging: Usa un filtro de registros para encontrar todos los eventos de HorizontalPodAutoscaler de un clúster específico. Por ejemplo:

    1. En la consola de Cloud de Confiance , 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: el ID de tu proyecto

    3. Haz clic en Ejecutar consulta y revisa el resultado.

  • Ver eventos del escalador automático horizontal de Pods: Estos registros proporcionan registros estructurados y legibles que explican cómo el escalador automático horizontal de Pods 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 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 un 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 objetivo. 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 verificar esto 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 HorizontalPodAutoscaler y la carga de trabajo estén en el mismo espacio de nombres: 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 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, 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 tu 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

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 HorizontalPodAutoscaler.
  3. Para encontrar una clave de etiqueta válida que se pueda filtrar, 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, es posible que observes 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 ajuste de escala no parezcan corresponderse con 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 en función de 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 ajuste de escala en un solo objeto HorizontalPodAutoscaler. Cada HorizontalPodAutoscaler calcula las necesidades de ajuste de escala a partir de su propio campo spec.metrics, por lo que la combinación de ambos 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 relacionados con errores de cargas de trabajo y servicios

En las siguientes secciones, se abordan los errores causados por la carga de trabajo de destino o sus servicios 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 el uso 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 en 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 realizar el ajuste de escala 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 pueden 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 temporalmente cuando se inicia el servidor de métricas.

Causa

Para realizar el ajuste de escala en función del porcentaje de uso de los 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

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

Causa

Se configuró el ajuste de escala automático basado en el tráfico, pero más de un servicio de Kubernetes apunta al campo scaleTargetRef de 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. Encuentra 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 de la 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, {"app": "my-app"} y {"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 one 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 del servicio o la Deployment.

Soluciona problemas relacionados con la API de métricas y la disponibilidad de datos

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

Soluciona problemas relacionados con las 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 dentro de 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 del HPA que muestra los componentes: controlador del 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

Existe 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 con el servidor principal de la API de Kubernetes para publicar métricas. Esta acción es la forma más directa de verificar 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 tu adaptador se 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 la métrica o mensajes que indiquen que no se pudo encontrar la métrica.

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

  2. Consultar 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 métricas externas, ejecuta el siguiente comando:

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

    Para consultar métricas personalizadas del Pod, 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 se deba a un error de configuración en el 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 escucha el adaptador:

        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 entrantes 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 al ADAPTER_SERVICE en 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 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

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 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. Comprueba el estado del plano de control de Kubernetes:

    1. En la consola de Cloud de Confiance , consulta el estado y la condición 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 del registro 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 Cómo depurar 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 ninguna serie temporal

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 puntos de datos que coincidan con tu filtro (lo que es diferente a encontrar una métrica con un valor de 0). La razón 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 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 de 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 haya estado operativa y haya intentado 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 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 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 ajuste de escala en fluctuaciones menores de las métricas. El ajuste solo se produce si la proporción de la métrica actual con respecto a la métrica objetivo se encuentra 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. Se ignoran los Pods que se atascan con un estado Pending o que no se convierten en Ready (debido a fallas en las verificaciones de estado o problemas de recursos), lo que puede impedir el ajuste de escala.
  • Demora en el 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 nueva métrica personalizada 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 la cantidad de réplicas requerida 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, el HorizontalPodAutoscaler ajusta la cantidad de réplicas de la Deployment a 15.

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 ajuste de escala 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 Cómo depurar Pods en la documentación de Kubernetes.
  • Retraso en el período de sincronización y latencia de métrica nueva: 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 aumenta la carga de trabajo correctamente, 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 horizontal, o el escalamiento horizontal basado en información incompleta. Estos son los principales motivos:

  • 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 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 no funciona. Este problema es común con las métricas personalizadas basadas en la tasa (por ejemplo, messages_per_second), que pueden dejar de registrar 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.
  • Retraso en la reducción de la escala desde 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 la reducción vertical 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 el estado <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 externas y personalizadas.

  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 (algo 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 medición, 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 el HorizontalPodAutoscaler tome decisiones de escalamiento de manera 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 las demoras en la reducción de la escala de la política de ajuste de escala, si el período de estabilización predeterminado de cinco minutos para las reducciones 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.

¿Qué sigue?