Ver eventos de la herramienta de adaptación dinámica horizontal de pods

Autopilot Standard

En esta página se proporciona información sobre los eventos de decisión emitidos por el Horizontal Pod Autoscaler en Google Kubernetes Engine (GKE). Al analizar estos eventos, puedes obtener información valiosa sobre cómo gestiona el controlador de la herramienta de adaptación dinámica horizontal de pods el escalado de tu carga de trabajo y comprender el proceso de toma de decisiones que hay detrás de sus acciones.

La herramienta de escalado automático horizontal de pods emite eventos de decisión, que se almacenan como entradas de registro en Cloud Logging.

Antes de empezar

Asegúrate de cumplir los siguientes requisitos previos:

Seleccionar o crear un proyecto

Puedes usar un proyecto que ya tengas o crear uno para este tutorial.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Habilitar las APIs

Enable the GKE, and Cloud Logging APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Configurar Cloud Shell

En este tutorial, usarás Cloud Shell para ejecutar los comandos gcloud y kubectl. Cloud Shell es un entorno de shell para gestionar recursos alojados en Google Cloud. Viene preinstalado con la CLI de Google Cloud y la herramienta de línea de comandos kubectl.

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

Se abrirá una sesión de Cloud Shell en un marco de la parte inferior de la consola.

Antes de ejecutar los comandos de este tutorial, asegúrate de que el proyecto predeterminado sea el ID del proyecto en el que quieras desplegar la aplicación de ejemplo. Si aún no lo has hecho, ejecuta el siguiente comando en Cloud Shell:

gcloud config set project PROJECT_ID

Sustituye PROJECT_ID por el ID de tu proyecto.

Roles y permisos necesarios

Para obtener los permisos que necesitas para habilitar la generación de registros, así como para acceder a los registros y procesarlos, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en el proyecto:

• Para habilitar el registro de eventos de Horizontal Pod Autoscaler en tu clúster, sigue estos pasos: Administrador del clúster de Kubernetes Engine (roles/container.clusterAdmin)
• Para acceder a los registros y usar Explorador de registros y Analíticas de registros, sigue estos pasos: Visualizador de registros (roles/logging.viewer)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Requisitos

• Tu clúster de GKE debe tener la versión 1.31.5-gke.1090000 o una posterior, o la 1.32.1-gke.1260000 o una posterior.
• Habilita Cloud Logging en tu clúster de GKE. Se aplican los precios de Cloud Logging.

Habilitar eventos de decisión de la herramienta de adaptación dinámica horizontal de pods

Precaución: Es posible que los clústeres ya tengan componentes de registro específicos configurados. Cuando actualices un clúster con la CLI de Google Cloud o una llamada a la API, debes incluir la configuración de registro en tu solicitud de actualización para evitar que se sobrescriban las configuraciones.
Nota: Si decides enviar registros a Cloud Logging, debes enviar registros del sistema. Asegúrate de habilitar el componente de registros del sistema cuando habilites los registros de fuentes adicionales, como KCP_HPA.

Para crear un clúster con los registros de decisiones KCP_HPA habilitados, ejecuta el siguiente comando:

gcloud container clusters create CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --logging=SYSTEM,KCP_HPA

Para habilitar los registros de decisiones de KCP_HPA en un clúster, ejecuta el siguiente comando:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --logging=SYSTEM,KCP_HPA

Haz los cambios siguientes:

• CLUSTER_NAME: nombre del clúster que quieras crear o actualizar.
• PROJECT_ID: tu ID de proyecto Google Cloud .
• LOCATION: regiones o zonas de cálculo de tu clúster.

Estos comandos permiten exportar los registros generados por KCP_HPA y guardarlos en el destino logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" de Cloud Logging.

Recupera la configuración de registro actualizada del clúster y revisa la lista de registros para asegurarte de que el registro KCP_HPA está habilitado:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=loggingConfig \
    --format='csv[delimiter=",",no-heading](componentConfig.enableComponents)'

El resultado debería ser similar al siguiente:

SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER,KCP_HPA

Inhabilitar los eventos de decisión de la herramienta de adaptación dinámica de pods horizontales

Precaución: Es posible que los clústeres ya tengan componentes de registro específicos configurados. Cuando actualices un clúster con la CLI de Google Cloud o una llamada a la API, debes incluir la configuración de registro que ya tengas en la solicitud de actualización para evitar que se sobrescriba.
Nota: Los registros del sistema son necesarios para solucionar problemas y obtener asistencia. Si inhabilitas los registros del sistema, el servicio de asistencia de GKE se ofrecerá en la medida de lo posible y puede que tu equipo de ingeniería tenga que hacer un esfuerzo adicional.

Actualiza un clúster para quitar el componente KCP_HPA de la marca --logging:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --logging=SYSTEM

Haz los cambios siguientes:

• CLUSTER_NAME: nombre del clúster que quieras crear o actualizar.
• PROJECT_ID: tu ID de proyecto Google Cloud .
• LOCATION: regiones o zonas de cálculo de tu clúster.

Este comando inhabilita la exportación de los registros generados por KCP_HPA. No puedes recuperarlos con el filtro logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" en Cloud Logging.

Recupera la configuración de registro actualizada del clúster y consulta la lista de registros para asegurarte de que el registro KCP_HPA está inhabilitado:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=loggingConfig \
    --format='csv[delimiter=",",no-heading](componentConfig.enableComponents)'

El resultado debería ser similar al siguiente:

SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER

Tipos de registros

Los eventos de decisión de la herramienta de adaptación dinámica horizontal de pods se almacenan en Cloud Logging, en la ubicación logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" del bucket _Default del mismo proyecto que tu clúster de GKE. Todos los eventos registrados tienen el formato JSON y se pueden encontrar en el campo jsonPayload de una entrada de registro.

Asegúrate de que conoces las necesidades de almacenamiento de los posibles volúmenes de registros, así como las implicaciones en cuanto al rendimiento o los costes. En los siguientes ejemplos se explica con qué frecuencia la herramienta de escalado automático horizontal de pods genera cada tipo de evento de decisión:

• Recomendación atómica: la herramienta de adaptación dinámica horizontal de pods genera un evento de recomendación atómico cada 15 segundos para cada métrica monitorizada por cada objeto HPA de tu clúster. Por ejemplo, si tienes dos objetos HPA en tu clúster y cada objeto HPA monitoriza tres métricas, se registrarán seis recomendaciones atómicas cada 15 segundos.

• Recomendación final: la herramienta de autoescalado horizontal de pods genera un evento de recomendación final cada 15 segundos para cada objeto HPA de tu clúster. Por ejemplo, si tienes dos objetos HPA en tu clúster, se registrarán dos recomendaciones finales cada 15 segundos.

En total, con dos objetos HPA que monitorizan tres métricas cada uno, tu registro KCP_HPA recibirá ocho entradas de eventos de decisión cada 15 segundos.

Recomendación atómica

Un registro de recomendaciones atómico describe una recomendación basada en una métrica individual especificada en tu herramienta de autoescalado horizontal de pods.

Un registro atómico incluye los siguientes campos:

Campo	Descripción
start_time	Indica cuándo ha empezado HPA a calcular una recomendación.
hpa	Nombre del objeto HPA asociado a la recomendación.
pod_count	Indica el número total de pods asociados al HPA al hacer la recomendación. Este número también incluye los pods listos, no listos e ignorados.
metric	Proporciona información sobre la especificación y el estado de la métrica utilizada en la recomendación. El campo metric contiene los siguientes subcampos: index: índice de la métrica en la matriz Spec metrics. type: tipo de métrica con valores de MetricSourceType (por ejemplo, Resource o External). spec: nombre de la métrica y un objetivo definido para esa métrica. status: Condiciones de estado en relación con la escalabilidad y las limitaciones de escalado. newest_sample_time: marca de tiempo de la muestra de métrica más reciente. newest_sample_age_seconds: antigüedad de la muestra más reciente, medida en segundos, desde que se inició el cálculo de la recomendación. Un valor negativo significa que la muestra de métricas es anterior al inicio del cálculo.
summary	El campo de resumen contiene información sobre el resultado de la recomendación, incluido el número de réplicas sugerido. Si no se puede proponer una recomendación, se muestra un mensaje de error. El campo summary contiene los siguientes subcampos: dampening: HPA aplica una atenuación a la recomendación y a su dirección para intentar reducir la magnitud de una posible escala. La atenuación puede producirse de las siguientes formas: up: una dirección de amortiguación ascendente significa que HPA asume que los pods con métricas que faltan tienen un uso del 100% de la métrica. down: una dirección de amortiguación hacia abajo significa que HPA asume que los pods de métricas que faltan o los pods no preparados consumen un 0% del uso de la métrica. none: no se aplica ninguna atenuación. override: mensaje que indica el motivo por el que no se aplica la recomendación propuesta por HPA (por ejemplo, debido a la tolerancia) o none si no se produce ninguna anulación. result: resultado de la recomendación. Propone un número de réplicas recomendado o muestra un mensaje de error si no se puede calcular la recomendación.

Ejemplo de registro de recomendación atómica:

{
  "insertId": "xiu4bty9k5b279wu",
  "jsonPayload": {
    "instance": {
      "vm_name": "my-unique-vm-identifier",
      "zone": "us-central1-a"
    },
    "atomicRecommendation": {
      "startTime": "2025-02-06T20:07:00.573419526Z",
      "hpa": "gke-managed-cim/kube-state-metrics",
      "metric": {
        "newestSampleAgeSeconds": -39.573419526,
        "status": {
          "averageValue": "25849856"
        },
        "newestSampleTime": "2025-02-06T20:06:21Z",
        "type": "Resource",
        "spec": {
          "target": {
            "averageValue": "400Mi"
          },
          "name": "memory"
        }
      },
      "podCount": {
        "ready": 1,
        "total": 1
      },
      "summary": {
        "override": "none",
        "replicas": 1,
        "dampening": "none"
      }
    }
  },
  "resource": {
    "type": "k8s_control_plane_component",
    "labels": {
      "project_id": "my-project-id",
      "cluster_name": "my-cluster",
      "location": "us-central1-a",
      "component_location": "us-central1-a",
      "component_name": "hpa-controller"
    }
  },
  "timestamp": "2025-02-06T20:07:00.593777835Z",
  "severity": "INFO",
  "labels": {
    "compute.googleapis.com/resource_name": "my-unique-vm-identifier"
  },
  "logName": "projects/my-project-id/logs/container.googleapis.com%2Fhpa-controller",
  "sourceLocation": {
    "file": "event_logger.go",
    "line": "61"
  },
  "receiveTimestamp": "2025-02-06T20:07:05.284753647Z"
}

Recomendación final

Un registro de recomendaciones final describe una recomendación consolidada propuesta por el escalador automático horizontal de pods. El escalado automático horizontal de pods combina todas las recomendaciones atómicas de diferentes métricas para crear una recomendación final y la aplica. Activación significa que el HPA indica a la implementación que ajuste el número de réplicas para que coincida con el valor recomendado. Si la recomendación final sugiere un número de pods diferente al número de pods en ejecución, el autoescalador de pods horizontal activa un evento de escalado vertical u horizontal para ajustar la implementación en consecuencia.

Un registro de recomendaciones finales incluye los siguientes campos:

Campo	Descripción
start_time	Indica cuándo ha empezado HPA a calcular una recomendación.
hpa	Nombre del objeto HPA asociado a la recomendación.
target_ref	Indica el objeto ScaleTargetRef de HPA asociado a una recomendación.
configured_size	El último número de réplicas registrado antes de que HPA calcule y aplique esta recomendación.
top_level_override	Proporciona un motivo si no se aplica la recomendación propuesta por HPA (por ejemplo, debido a la tolerancia) o none si no se produce ninguna anulación.
top_level_limit	Proporciona un motivo si es necesario ajustar la recomendación propuesta por HPA (por ejemplo, debido al número de réplicas que se definen en los campos MinReplicas o MaxReplicas de la especificación de HPA).
leading_metric_index	El índice de métrica principal de la matriz Spec metrics es la métrica cuya recomendación atómica asociada se usa como recomendación final.
normalization	Proporciona un resumen de la estabilización y las limitaciones de la siguiente manera, si las hay: stabilization: describe el estado de estabilización si se ha aplicado. La estabilización se usa para restringir las fluctuaciones del recuento de réplicas cuando las métricas usadas para el escalado cambian constantemente. El campo stabilization consta de los siguientes subcampos: replicas: número de réplica después de la estabilización. reason: tipo de estabilización aplicado (scaleUp o scaleDown). stabilization_window: periodo de estabilización asociado, en segundos. replicas_before_stabilization: número de réplicas recomendado antes de la estabilización. limitation: describe cómo se gestionan las limitaciones de escalado si se aplican. Este comportamiento modifica las recomendaciones propuestas por el HPA en función de las limitaciones vigentes. El campo limitation consta de los siguientes subcampos: replicas: número de réplica después de la limitación. reason: motivo por el que no se ha escalado más allá del número mínimo o máximo de réplicas. scaling_policy: la política de escalado que se aplica. selectPolicy: especifica cómo se selecciona una política al reducir la escala en una dirección determinada. MaxChange corresponde a MaxChangePolicySelect y MinChange corresponde a MinChangePolicySelect. Si el escalado está inhabilitado, el campo selectPolicy no estará presente. replicas_before_limitation: número de réplicas recomendado antes de la limitación.
replicas	Número de réplicas recomendado.
actuation_error	Mensaje de error asociado al fallo, si la activación no se ha realizado correctamente.
actuation_time	Marca de tiempo de la activación correcta.
actuation_latency_seconds	Tiempo transcurrido, en segundos, desde el inicio del cálculo de la recomendación hasta que se ha completado la acción.

Ejemplo de registro de recomendación final:

{
  "insertId": "qzyv7alfv1sm19ns",
  "jsonPayload": {
    "finalRecommendation": {
      "actuationTime": "2025-02-06T20:06:57.487786873Z",
      "targetRef": {
        "name": "kube-state-metrics",
        "kind": "StatefulSet",
        "apiVersion": "apps/v1"
      },
      "topLevelLimit": "none",
      "hpa": "gke-managed-cim/kube-state-metrics",
      "topLevelOverride": "noRecommendation",
      "replicas": 1,
      "configuredSize": 1,
      "actuationLatencySeconds": 0.003722451,
      "startTime": "2025-02-06T20:06:57.484064422Z"
    },
    "instance": {
      "vm_name": "my-unique-vm-identifier",
      "zone": "us-central1-a"
    }
  },
  "resource": {
    "type": "k8s_control_plane_component",
    "labels": {
      "cluster_name": "my-cluster",
      "component_location": "us-central1-a",
      "component_name": "hpa-controller",
      "location": "us-central1-a",
      "project_id": "my-project-id"
    }
  },
  "timestamp": "2025-02-06T20:06:57.488193527Z",
  "severity": "INFO",
  "labels": {
    "compute.googleapis.com/resource_name": "my-unique-vm-identifier"
  },
  "logName": "projects/my-project-id/logs/container.googleapis.com%2Fhpa-controller",
  "sourceLocation": {
    "file": "event_logger.go",
    "line": "61"
  },
  "receiveTimestamp": "2025-02-06T20:06:57.844898727Z"
}

Solución de problemas

En esta sección se describen los problemas y los pasos para resolverlos relacionados con los eventos de escalado automático horizontal de pods.

No hay eventos

Si no ves ningún evento de decisión de la herramienta de adaptación dinámica horizontal de pods, asegúrate de haber hecho lo siguiente:

• Has habilitado Cloud Logging en el clúster.
• Has habilitado los registros KCP_HPA del clúster.
• Has desplegado al menos un objeto hpa correctamente configurado en tu clúster.

Para ver la configuración del objeto hpa, ejecuta el siguiente comando:

  kubectl describe hpa $HPA_NAME

Si sigues sin ver ningún registro de KCP_HPA, ponte en contacto con el Google Cloud equipo de Asistencia.

Siguientes pasos

• Consulta Acerca de los registros de GKE.
• Consulta tus registros de GKE.
• Consulta cómo encontrar registros de GKE específicos mediante consultas de ejemplo.
• Consulta cómo optimizar el autoescalado de pods en función de las métricas.