Recopila registros de eventos del escalador automático horizontal de Pods

Autopilot Standard

En esta página, se proporciona información sobre los eventos de decisión que emite el escalador automático de Pods horizontal en Google Kubernetes Engine (GKE). Analizando estos eventos, puedes obtener información sobre cómo el controlador del escalador automático horizontal de Pods administra el escalamiento de tu carga de trabajo y comprender el proceso de toma de decisiones detrás de sus acciones.

El escalador automático de Pods horizontal emite eventos de decisión, que se almacenan como entradas de registro en Cloud Logging.

Antes de comenzar

Asegúrate de completar los siguientes requisitos previos:

Selecciona o crea un proyecto

Puedes usar un proyecto existente o crear uno nuevo para este instructivo.

Accede a tu cuenta de Google Cloud . Si es la primera vez que usas Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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 role (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 role (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.

Habilita las APIs

Habilita las APIs de GKE y Cloud Logging, si aún no están habilitadas.

Roles necesarios para habilitar las APIs

Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar las API

Configura Cloud Shell

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

En la consola de Google Cloud , activa Cloud Shell.

Activa Cloud Shell

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

Antes de ejecutar comandos en este instructivo, asegúrate de que tu proyecto predeterminado esté configurado como el ID del proyecto en el que deseas implementar la app de ejemplo. Si aún no está configurado, ejecuta el siguiente comando en Cloud Shell:

gcloud config set project PROJECT_ID

Reemplaza PROJECT_ID por el ID del proyecto.

Roles y permisos requeridos

Para obtener los permisos que necesitas para habilitar la generación de registros, y para acceder a ellos y procesarlos, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

• Para habilitar el registro de eventos del escalador automático de Pods horizontal en tu clúster, ve a: Administrador de clústeres de Kubernetes Engine (roles/container.clusterAdmin)
• Para acceder a los registros y usar el Explorador de registros y las Estadísticas de observabilidad: Visualizador de registros (roles/logging.viewer)

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.

Requisitos

• Tu clúster de GKE debe ejecutar la versión 1.31.5-gke.1090000 o una posterior, o bien la versión 1.32.1-gke.1260000 o una posterior.
• Habilita Cloud Logging en tu clúster de GKE. Se aplican los precios de Cloud Logging.
• Asegúrate de tener un escalador automático horizontal de Pods que quieras supervisar. Asegúrate de que los campos del escalador automático horizontal de Pods no incluyan datos sensibles.

Costos

Se aplican los precios de Cloud Logging cuando habilitas Cloud Logging y recopilas registros de decisiones del ajuste automático de escala horizontal de Pods.

Habilita los eventos de decisión del escalador automático horizontal de Pods

Precaución: Es posible que los clústeres existentes ya tengan configurados componentes de registro específicos. Cuando actualizas un clúster existente con Google Cloud CLI o una llamada a la API, debes incluir la configuración de registro existente en tu solicitud de actualización para evitar que se sobrescriban las configuraciones existentes.

Nota: Si eliges 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.

gcloud

Para crear un clúster nuevo con los registros de decisiones de 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 existente, ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

• CLUSTER_NAME: Es el nombre del clúster que deseas crear o actualizar.
• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• LOCATION: Son las regiones o zonas de procesamiento para tu clúster.

Terraform

Para habilitar los registros de decisiones de KCP_HPA con Terraform, actualiza tu recurso google_container_cluster. En el bloque logging_config, agrega el valor KCP_HPA a la lista para el campo enable_components:

resource "google_container_cluster" "primary" {
  name     = "CLUSTER_NAME"
  location = "LOCATION"

  # ... other configuration ...

  logging_config {
    enable_components = ["SYSTEM_COMPONENTS", "KCP_HPA"]
  }
}

Reemplaza lo siguiente:

• CLUSTER_NAME: Es el nombre del clúster que deseas crear.
• LOCATION: Región o zona de procesamiento de tu clúster.

Estos comandos permiten exportar los registros que genera KCP_HPA y guardarlos en el destino logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" dentro 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 es similar a lo siguiente:

SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER,KCP_HPA

Consulta los registros del escalador automático horizontal de Pods en la consola de Google Cloud

Puedes supervisar el comportamiento del Pod autoscaler horizontal en la consola deGoogle Cloud . Esta vista proporciona una forma conveniente de ver los mismos registros de recomendaciones atómicos y finales que están disponibles en Cloud Logging, sin salir del contexto de tu carga de trabajo.

Para ver los registros del escalador automático horizontal de Pods en la consola de Google Cloud , completa los siguientes pasos:

1. En la consola de Google Cloud , ve a la página Cargas de trabajo:

   Ir a Cargas de trabajo

2. Selecciona la carga de trabajo que administra el escalador automático horizontal de Pods.

3. Haz clic en la pestaña Ajuste de escala.

En esta pestaña, puedes encontrar información relacionada con el ajuste de escala, incluido el uso de recursos, los datos de eficiencia y los registros. Los datos de esta pestaña pueden ayudarte a identificar la configuración más eficaz para escalar automáticamente tus cargas de trabajo. En la sección Registros, puedes encontrar la misma información de los Registros y filtrarlos por tipo, incluidos "Evento", "Recomendación final" y "Recomendación atómica". Para obtener más detalles sobre los diferentes registros, consulta Tipos de registros.

Inhabilita los eventos de decisión del ajuste de escala automático horizontal de Pods

Precaución: Es posible que los clústeres existentes ya tengan componentes de registro específicos configurados. Cuando actualizas un clúster existente con Google Cloud CLI o una llamada a la API, debes incluir la configuración de registro existente en tu solicitud de actualización para evitar que se sobrescriban las configuraciones existentes.

Nota: Los registros del sistema son necesarios para la solución de problemas y la asistencia. Si inhabilitas los registros del sistema, la asistencia al cliente de GKE se ofrece según el criterio del mejor esfuerzo y es posible que se requiera un esfuerzo adicional de parte de tu equipo de ingeniería.

gcloud

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

Reemplaza lo siguiente:

• CLUSTER_NAME: Es el nombre del clúster que deseas crear o actualizar.
• PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
• LOCATION: Son las regiones o zonas de procesamiento para tu clúster.

Terraform

Para inhabilitar los registros de decisiones de KCP_HPA con Terraform, actualiza tu recurso google_container_cluster. En el bloque logging_config, quita el valor KCP_HPA de la lista para el campo enable_components:

resource "google_container_cluster" "primary" {
  name     = "CLUSTER_NAME"
  location = "LOCATION"

  # ... other configuration ...

  logging_config {
    enable_components = ["SYSTEM_COMPONENTS"]
  }
}

Reemplaza lo siguiente:

• CLUSTER_NAME: Es el nombre del clúster que deseas actualizar.
• LOCATION: Región o zona de procesamiento 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 revisa 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 es similar a lo siguiente:

SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER

Tipos de registros

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

Asegúrate de comprender las necesidades de almacenamiento de los posibles volúmenes de registros, además de las implicaciones de rendimiento o costo. En los siguientes ejemplos, se explica con qué frecuencia el escalador automático de Pods horizontal genera cada tipo de evento de decisión:

• Recomendación atómica: El escalador automático horizontal de Pods genera un evento de recomendación atómica cada 15 segundos para cada métrica que supervisa cada objeto HPA en tu clúster. Por ejemplo, si tienes dos objetos de HPA en tu clúster y cada objeto de HPA supervisa tres métricas, se registrarán seis recomendaciones atómicas cada 15 segundos.

• Recomendación final: El Horizontal Pod Autoscaler genera un evento de recomendación final cada 15 segundos para cada objeto HPA de tu clúster. Por ejemplo, si tienes dos objetos de HPA en tu clúster, se registrarán dos recomendaciones finales cada 15 segundos.

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

Recomendación atómica

Un registro de recomendación atómico describe una recomendación basada en una métrica individual especificada en tu escalador automático horizontal de Pods.

Un registro atómico incluye los siguientes campos:

Campo	Descripción
start_time	Indica cuándo el HPA comenzó a calcular una recomendación.
hpa	Es el nombre del objeto de HPA asociado con la recomendación.
pod_count	Indica la cantidad total de Pods asociados con el HPA cuando se realiza la recomendación. Este número también incluye los Pods listos, no listos y los ignorados.
metric	Proporciona información sobre la especificación y el estado de la métrica que se usa para la recomendación. El campo metric contiene los siguientes subcampos: index: Es el índice de la métrica en el array Spec metrics. type: Es el tipo de métrica con valores del MetricSourceType (por ejemplo, Recurso o Externa). spec: Es el nombre de la métrica y un objetivo establecido en esa métrica. status: Condiciones de estado con respecto a la escalabilidad y las limitaciones de escalamiento. newest_sample_time: Es la marca de tiempo de la muestra de métrica más reciente. newest_sample_age_seconds: Es la antigüedad de la muestra más reciente, medida en segundos, desde que comenzó 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 mostrará un mensaje de error. El campo summary contiene los siguientes subcampos: dampening: El HPA aplica una amortiguación a la recomendación y a su dirección para intentar reducir la magnitud de un posible ajuste. La amortiguación puede ocurrir de las siguientes maneras: up: Una dirección de amortiguación ascendente significa que el HPA asume que los Pods con métricas faltantes tienen un uso del 100% de la métrica. down: Una dirección de reducción de escala vertical significa que el HPA asume que los Pods con métricas faltantes o los Pods no listos consumen el 0% de la métrica. none: No se aplica ninguna estabilización. override: Es un mensaje que proporciona un motivo cuando no se aplica la recomendación propuesta por el HPA (por ejemplo, debido a la tolerancia) o none si no se produce ninguna anulación. result: Es el resultado de la recomendación. Propone una cantidad recomendada de réplicas 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 recomendación final describe una recomendación consolidada que propone el ajuste automático de escala horizontal de Pods. El escalador automático horizontal de Pods combina todas las recomendaciones atómicas de diferentes métricas para crear una recomendación final y la aplica. La activación significa que el HPA indica al Deployment que ajuste la cantidad de réplicas para que coincida con el valor recomendado. Si la recomendación final sugiere una cantidad de Pods diferente a la cantidad de Pods en ejecución, el escalador automático horizontal de Pods activa un evento de aumento o reducción de la escala para ajustar la Deployment según corresponda.

Un registro de recomendación final incluye los siguientes campos:

Campo	Descripción
start_time	Indica cuándo el HPA comenzó a calcular una recomendación.
hpa	Es el nombre del objeto HPA asociado con la recomendación.
target_ref	Indica el objeto ScaleTargetRef del HPA asociado con una recomendación.
configured_size	Es la última cantidad de réplicas registrada 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 el 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 que propuso HPA (por ejemplo, debido a la cantidad de réplicas que definen los campos MinReplicas o MaxReplicas en la especificación de HPA).
leading_metric_index	El índice de la métrica principal en el array Spec metrics es la métrica cuya recomendación atómica asociada se usa como la recomendación final.
normalization	Proporciona un resumen de la estabilización y la limitación de la siguiente manera, si está presente: stabilization: Describe el estado de estabilización si se aplicó. La estabilización se usa para restringir las fluctuaciones del recuento de réplicas cuando las métricas que se usan para el ajuste de escala siguen fluctuando. El campo stabilization consta de los siguientes subcampos: replicas: Es la cantidad de réplicas después de la estabilización. reason: Tipo de estabilización aplicada: scaleUp o scaleDown. stabilization_window: Es el período de estabilización asociado, en segundos. replicas_before_stabilization: Es la cantidad de réplicas recomendada antes de la estabilización. limitation: Describe cómo se manejan las limitaciones de escalamiento si se aplican. Este comportamiento modifica las recomendaciones propuestas por el HPA según las limitaciones vigentes. El campo limitation consta de los siguientes subcampos: replicas: Es la cantidad de réplicas después de la limitación. reason: Es el motivo por el que no se escala más allá de la cantidad mínima o máxima de réplicas. scaling_policy: Es la política de ajuste que se aplica. selectPolicy: Especifica cómo se selecciona una política cuando se ajusta en una dirección determinada. MaxChange corresponde a MaxChangePolicySelect; MinChange corresponde a MinChangePolicySelect. Si el ajuste no está habilitado, el campo selectPolicy no estará presente. replicas_before_limitation: Es la cantidad de réplicas recomendada antes de la limitación.
replicas	Es la cantidad de réplicas recomendada.
actuation_error	Es un mensaje de error asociado con la falla, si la activación falló.
actuation_time	Es la marca de tiempo de la activación cuando se realiza correctamente.
actuation_latency_seconds	Es el tiempo que transcurrió, en segundos, desde el inicio del cálculo de la recomendación hasta que se realizó la activación correctamente.

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"
}

Soluciona problemas

En esta sección, se describen los problemas y los pasos para resolverlos relacionados con los eventos del Horizontal Pod Autoscaler.

No hay eventos

Si no ves ningún evento de decisión del escalador automático horizontal de Pods, asegúrate de haber realizado todas las siguientes acciones:

• Habilitaste Cloud Logging para el clúster.
• Habilitaste los registros de KCP_HPA para el clúster.
• Implementaste al menos un objeto hpa configurado correctamente en tu clúster.

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

  kubectl describe hpa $HPA_NAME

Si aún no ves ningún registro de KCP_HPA, comunícate con el equipo de asistencia deGoogle Cloud .

¿Qué sigue?

• Consulta Acerca de los registros de GKE.
• Comprende tus registros de GKE.
• Aprende a encontrar registros específicos de GKE con consultas de muestra.
• Obtén más información sobre el escalado automático horizontal de Pods.