Soluciona problemas de actualizaciones de clústeres

Si falla la actualización del plano de control o del grupo de nodos de Google Kubernetes Engine (GKE), se detiene o provoca un comportamiento inesperado de la carga de trabajo, es posible que debas solucionar problemas del proceso. Mantener actualizados el plano de control y los grupos de nodos es fundamental para la seguridad y el rendimiento, y resolver cualquier problema ayuda a garantizar que tu entorno permanezca estable.

Para resolver problemas comunes de actualización, un buen primer paso es supervisar el proceso de actualización del clúster. Luego, puedes encontrar sugerencias para resolver el problema:

Esta información es importante para los administradores y operadores de la plataforma que desean diagnosticar las causas raíz de las actualizaciones atascadas o fallidas, administrar las políticas de mantenimiento y resolver las incompatibilidades de versiones. Los desarrolladores de aplicaciones pueden encontrar orientación para resolver problemas de cargas de trabajo posteriores a la actualización y comprender cómo las configuraciones de cargas de trabajo, como PodDisruptionBudgets, pueden afectar la duración de la actualización. 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 de usuario y tareas comunes de GKE.

Supervisa el proceso de actualización del clúster

Para resolver los problemas de actualización de manera más eficaz, primero debes comprender qué sucedió durante el proceso de actualización. GKE proporciona varias herramientas que te brindan visibilidad sobre este proceso.

En la consola de Google Cloud , el panel de actualización ofrece una vista de todo el proyecto de todas las actualizaciones de clúster en curso, un cronograma de eventos recientes y advertencias sobre posibles bloqueadores, como exclusiones de mantenimiento activas o bajas de versiones próximas. Para las verificaciones automatizadas o de línea de comandos, puedes usar el comando gcloud container operations list para obtener el estado de operaciones de actualización específicas. Para obtener más información, consulta Cómo obtener visibilidad de las actualizaciones del clúster.

Para una investigación más detallada, Cloud Logging es tu principal fuente de información. GKE registra información detallada sobre los procesos de actualización del plano de control y del grupo de nodos en Cloud Logging. Esto incluye registros de auditoría de alto nivel que hacen un seguimiento de las principales operaciones de actualización, así como registros más detallados, como los eventos de Kubernetes y los registros de los componentes de los nodos, que pueden mostrarte más información sobre errores específicos.

En las siguientes secciones, se explica cómo consultar estos registros con el Explorador de registros o gcloud CLI. Para obtener más información, consulta Cómo verificar los registros de actualización.

Identifica la operación de actualización con los registros de auditoría

Si no sabes qué operación de actualización falló, puedes usar los registros de auditoría de GKE. Los registros de auditoría hacen un seguimiento de las acciones administrativas y proporcionan un registro autorizado de cuándo se inició una actualización y su estado final. Usa las siguientes consultas en el Explorador de registros para encontrar la operación pertinente.

Tipo de evento Consulta de registro
Actualización automática del plano de control 
resource.type="gke_cluster"
protoPayload.methodName="google.container.internal.ClusterManagerInternal.UpdateClusterInternal"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.metadata.operationType="UPGRADE_MASTER"
resource.labels.cluster_name="CLUSTER_NAME"

Reemplaza CLUSTER_NAME por el nombre del clúster que deseas investigar.

Esta consulta muestra la versión del plano de control de destino y la versión anterior del plano de control.
Actualización manual del plano de control 
resource.type="gke_cluster"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.response.operationType="UPGRADE_MASTER"
resource.labels.cluster_name="CLUSTER_NAME"

 
Actualización automática del grupo de nodos (solo versión de destino) 
resource.type="gke_nodepool"
protoPayload.methodName="google.container.internal.ClusterManagerInternal.UpdateClusterInternal"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.metadata.operationType="UPGRADE_NODES"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.nodepool_name="NODEPOOL_NAME"

Reemplaza NODEPOOL_NAME por el nombre del grupo de nodos que pertenece al clúster.
Actualización manual del grupo de nodos 
resource.type="gke_nodepool"
protoPayload.methodName="google.container.v1.ClusterManager.UpdateNodePool"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.response.operationType="UPGRADE_NODES"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.nodepool_name="NODEPOOL_NAME"

Para encontrar la versión anterior del grupo de nodos, revisa los registros de la API de Kubernetes:

resource.type="k8s_cluster"
resource.labels.cluster_name="CLUSTER_NAME"
protoPayload.methodName="nodes.patch"

Cómo encontrar mensajes de error detallados en los registros de GKE

Después de que el registro de auditoría te muestre qué operación falló y cuándo, puedes buscar mensajes de error más detallados de los componentes de GKE alrededor del mismo tiempo. Estos registros pueden contener los motivos específicos de una falla en la actualización, como un objeto PodDisruptionBudget mal configurado.

Por ejemplo, después de encontrar una operación UPGRADE_NODES fallida en los registros de auditoría, puedes usar su marca de tiempo para acotar la búsqueda. En el Explorador de registros, ingresa la siguiente consulta y, luego, usa el selector de intervalo de tiempo para enfocarte en el momento en que ocurrió la falla:

resource.type="k8s_node"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.node_name="NODE_NAME"
severity=ERROR

Reemplaza lo siguiente:

  • CLUSTER_NAME: El nombre de tu clúster.
  • NODE_NAME: Es el nombre del nodo dentro del clúster en el que deseas verificar si hay errores.

Usa gcloud CLI para ver los eventos de actualización

Además del Explorador de registros, puedes usar los comandos de gcloud CLI para revisar los eventos de actualización.

Para buscar actualizaciones del plano de control, ejecuta el siguiente comando:

gcloud container operations list --filter="TYPE=UPGRADE_MASTER"

El resultado es similar a este:

NAME: operation-1748588803271-cfd407a2-bfe7-4b9d-8686-9f1ff33a2a96
TYPE: UPGRADE_MASTER
LOCATION: LOCATION
TARGET: CLUSTER_NAME
STATUS_MESSAGE:
STATUS: DONE
START_TIME: 2025-05-30T07:06:43.271089972Z
END_TIME: 2025-05-30T07:18:02.639579287Z

En esta salida, se incluyen los siguientes valores:

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

Para buscar actualizaciones del grupo de nodos, ejecuta el siguiente comando:

gcloud container operations list --filter="TYPE=UPGRADE_NODES"

El resultado es similar a este:

NAME: operation-1748588803271-cfd407a2-bfe7-4b9d-8686-9f1ff33a2a96
TYPE: UPGRADE_NODES
LOCATION: LOCATION
TARGET: CLUSTER_NAME
STATUS_MESSAGE:
STATUS: DONE
START_TIME: 2025-05-30T07:06:43.271089972Z
END_TIME: 2025-05-30T07:18:02.639579287Z

Ejemplo: Usa registros para solucionar problemas relacionados con las actualizaciones del plano de control

En el siguiente ejemplo, se muestra cómo usar los registros para solucionar problemas relacionados con una actualización fallida del plano de control:

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

    Ir al Explorador de registros

  2. En el panel de consultas, filtra los registros de actualización del plano de control ingresando la siguiente consulta:

    resource.type="gke_cluster"
protoPayload.metadata.operationType=~"(UPDATE_CLUSTER|UPGRADE_MASTER)"
resource.labels.cluster_name="CLUSTER_NAME"

    Reemplaza CLUSTER_NAME por el nombre del clúster que deseas investigar.

  3. Haz clic en Ejecutar consulta.

  4. Revisa el resultado del registro para obtener la siguiente información:

  5. Confirma que se inició la actualización: Busca eventos UPGRADE_MASTER recientes cerca del momento en que iniciaste la actualización. La presencia de estos eventos confirma que tú o GKE activaron el proceso de actualización.

    • Verifica las versiones: Comprueba los siguientes campos para confirmar las versiones anterior y de destino:

      • protoPayload.metadata.previousMasterVersion: Muestra la versión del plano de control antes de la actualización.

      • protoPayload.metadata.currentMasterVersion: Muestra la versión a la que GKE intentó actualizar el plano de control.

        Por ejemplo, si querías actualizar a la versión 1.30.1-gke.1234, pero especificaste por error 1.30.2-gke.4321 (una versión más reciente y potencialmente incompatible con tus cargas de trabajo), revisar estos dos campos destacaría esta discrepancia. Como alternativa, si el campo currentMasterVersion sigue mostrando la versión anterior después de un período prolongado, este hallazgo indica que la actualización no pudo aplicar la versión nueva.

    • Busca errores: Verifica si hay eventos UPGRADE_MASTER repetidos o algún otro mensaje de error. Si el registro de operaciones se detiene sin indicar que se completó o falló, este hallazgo indica un problema.

Después de identificar un error o comportamiento específico en los registros, puedes usar esa información para encontrar la solución adecuada en esta guía.

Soluciona problemas de actualizaciones de grupos de nodos que tardan más de lo habitual

Si la actualización del grupo de nodos demora más de lo esperado, prueba las siguientes soluciones:

  1. Verifica el valor de terminationGracePeriodSeconds en el manifiesto de tus Pods. Este valor define el tiempo máximo que Kubernetes espera a que un Pod se cierre correctamente. Un valor alto (por ejemplo, unos minutos) puede extender significativamente la duración de las actualizaciones, ya que Kubernetes espera el período completo para cada Pod. Si este retraso causa problemas, considera reducir el valor.

  2. Verifica tus objetos PodDisruptionBudget. Cuando se desvía un nodo, GKE espera como máximo una hora por nodo para desalojar correctamente sus cargas de trabajo. Si tu objeto PodDisruptionBudget es demasiado restrictivo, puede impedir que una expulsión correcta se realice. En este caso, GKE usa todo el período de gracia de una hora para intentar agotar el nodo antes de que finalmente se agote el tiempo de espera y se fuerce la actualización. Este retraso, cuando se repite en varios nodos, es una causa común de una actualización general lenta del clúster. Para confirmar si un objeto PodDisruptionBudget restrictivo es la causa de las actualizaciones lentas, usa el Explorador de registros:

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

      Ir al Explorador de registros

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

      resource.type=("gke_cluster" OR "k8s_cluster")
resource.labels.cluster_name="CLUSTER_NAME"
protoPayload.response.message="Cannot evict pod as it would violate the pod's disruption budget."
log_id("cloudaudit.googleapis.com/activity")

    3. Haz clic en Ejecutar consulta.

    4. Revisa el resultado del registro. Si el objeto PodDisruptionBudget es la causa del problema, el resultado es similar al siguiente:

      resourceName: "core/v1/namespaces/istio-system/pods/POD_NAME/eviction"

response: {
  @type: "core.k8s.io/v1.Status"
  apiVersion: "v1"
  code: 429
  details: {
  causes: [
    0: {
    message: "The disruption budget istio-egressgateway needs 1 healthy pods and has 1 currently"
    reason: "DisruptionBudget"
    }
  ]
  }
  kind: "Status"
  message: "Cannot evict pod as it would violate the pod's disruption budget."
  metadata: {
  }
  reason: "TooManyRequests"
  status: "Failure"
}

    5. Después de confirmar que un objeto PodDisruptionBudget es la causa, enumera todos los objetos PodDisruptionBudget y asegúrate de que la configuración sea adecuada:

      kubectl get pdb --all-namespaces

      El resultado es similar a este:

      NAMESPACE        NAME          MIN AVAILABLE   MAX UNAVAILABLE   ALLOWED DISRUPTIONS   AGE
example-app-one  one_pdb       3               0                 1                     12d

      En este ejemplo, el PodDisruptionBudget llamado one_pdb requiere un mínimo de tres Pods disponibles. Dado que expulsar un Pod durante la actualización dejaría solo dos Pods disponibles, la acción incumple el presupuesto y provoca que la actualización se detenga.

      Si tu objeto PodDisruptionBudget funciona como deseas, no es necesario que realices ninguna acción. Si no es así, considera relajar la configuración de PodDisruptionBudget durante el período de actualización.

  3. Verifica las afinidades de los nodos. Las reglas restrictivas pueden ralentizar las actualizaciones, ya que impiden que los Pods se reprogramen en nodos disponibles si estos no coinciden con las etiquetas requeridas. Este problema es especialmente grave durante las actualizaciones repentinas, ya que las afinidades de nodos pueden limitar la cantidad de nodos que se pueden actualizar de forma simultánea si los nodos con las etiquetas correctas no tienen suficiente capacidad de clúster para alojar los Pods nuevos.

  4. Verifica si usas la estrategia de actualización de corta duración. GKE usa la estrategia de actualización de corta duración para los nodos de inicio flexible y para los nodos que solo usan el aprovisionamiento en cola en clústeres que ejecutan la versión 1.32.2-gke.1652000 o posterior de GKE. Si usas esta estrategia de actualización, la operación puede tardar hasta siete días.

  5. Comprueba si usas Pods de duración extendida (disponibles para clústeres de Autopilot). Durante una actualización, GKE debe vaciar todos los Pods de un nodo antes de que se complete el proceso. Sin embargo, durante una actualización iniciada por GKE, GKE no expulsa los Pods de duración extendida durante un máximo de siete días. Esta protección evita que el nodo se drene. GKE finaliza de forma forzosa el Pod solo después de que finaliza este período, y esta demora significativa de varios días para un solo nodo puede retrasar más actualizaciones de nodos en el clúster de Autopilot.

  6. Los volúmenes persistentes adjuntos pueden hacer que un proceso de actualización tarde más de lo habitual debido al tiempo que lleva administrar el ciclo de vida de estos volúmenes.

  7. Verifica el estado de la actualización automática del clúster. Si el motivo es SYSTEM_CONFIG, las actualizaciones automáticas se detienen temporalmente por motivos técnicos o comerciales. Si ves este motivo, te recomendamos que no realices una actualización manual, a menos que sea necesario.

Soluciona problemas de actualizaciones de grupos de nodos incompletas

En ocasiones, GKE no puede completar la actualización de un grupo de nodos, lo que hace que el grupo de nodos se actualice parcialmente. Existen varios motivos por los que las actualizaciones pueden ser incompletas:

  • Se canceló la actualización de forma manual.
  • La actualización falló debido a un problema, como la imposibilidad de registrar nodos nuevos, el agotamiento de direcciones IP o cuotas de recursos insuficientes.
  • GKE pausó la actualización. Esta pausa puede ocurrir, por ejemplo, para evitar una actualización a una versión con problemas conocidos o durante ciertos períodos de mantenimiento iniciados por Google.
  • Si usas actualizaciones automáticas, un período de mantenimiento finalizó antes de que se pudiera completar la actualización. Como alternativa, es posible que haya comenzado un período de exclusión de mantenimiento antes de que se pudiera completar la actualización. Para obtener más información, consulta El período de mantenimiento impide que se complete la actualización del nodo.

Cuando un grupo de nodos se actualiza parcialmente, los nodos se ejecutan en diferentes versiones. Para resolver este problema y verificar que todos los nodos del grupo de nodos se ejecuten en la misma versión, reanuda la actualización o revierte la actualización.

Sin embargo, la estrategia de actualizaciones de aumento y la estrategia de actualizaciones azul-verde interactúan con los períodos de mantenimiento de manera diferente:

  • Actualizaciones de aumento: La operación de actualización se pausa si se ejecuta más allá del período de mantenimiento. La actualización se reanuda automáticamente durante el siguiente período de mantenimiento programado.
  • Actualizaciones azul-verde: La operación de actualización continúa hasta que se completa, incluso si supera el período de mantenimiento. Las actualizaciones azul-verde ofrecen un control detallado sobre el ritmo de actualización con funciones como los tiempos de permanencia de lotes y grupos de nodos, y el grupo de nodos adicional ayuda a garantizar que las cargas de trabajo sigan operativas.

Soluciona problemas relacionados con el comportamiento inesperado de la actualización automática

A veces, las actualizaciones automáticas de clústeres no se realizan de la manera que esperas. En las siguientes secciones, se te ayudará a resolver los siguientes problemas:

No se pueden actualizar los clústeres cuando está habilitada la actualización automática de nodos

Si no inhabilitaste la actualización automática de nodos, pero no se produce una actualización, prueba las siguientes soluciones:

  1. Si usas un canal de versiones, verifica que las actualizaciones automáticas de nodos no estén bloqueadas. En el caso de los clústeres inscritos en un canal de versiones, tu maintenancePolicy es la forma principal de controlar las actualizaciones automáticas. Puede impedir que se inicie una actualización o interrumpir una que ya esté en curso. Una exclusión de mantenimiento activa puede bloquear una actualización por completo, y el momento de un período de mantenimiento puede causar una interrupción. Revisa tu maintenancePolicy para determinar si alguno de estos parámetros de configuración es la causa del problema:

    gcloud container clusters describe CLUSTER_NAME \
    --project PROJECT_ID  \
    --location LOCATION

    Reemplaza lo siguiente:

    • CLUSTER_NAME: Es el nombre del clúster del grupo de nodos que se describirá.
    • PROJECT_ID: El ID del proyecto del clúster.
    • LOCATION: Es la región o zona de Compute Engine (por ejemplo, us-central1 o us-central1-a) para el clúster.

    El resultado es similar a este:

    …
maintenancePolicy:
  maintenanceExclusions:
  - exclusionName: critical-event-q4-2025
    startTime: '2025-12-20T00:00:00Z'
    endTime: '2026-01-05T00:00:00Z'
    scope:
      noUpgrades: true # This exclusion blocks all upgrades
  window:
    dailyMaintenanceWindow:
      startTime: 03:00 # Daily window at 03:00 UTC
…

    En el resultado, revisa la sección maintenancePolicy para verificar las siguientes dos condiciones:

    • Para ver si se bloqueó una actualización, busca un maintenanceExclusion activo con un alcance de NO_MINOR_OR_NODE_UPGRADES. Por lo general, este parámetro de configuración evita que GKE inicie una nueva actualización.
    • Para ver si se interrumpió una actualización, consulta el programa de tu dailyMaintenanceWindow o maintenanceExclusions. Si una actualización se ejecuta más allá del período programado, GKE la pausa, lo que genera una actualización parcial. Para obtener más información sobre las actualizaciones parciales, consulta la sección Soluciona problemas de actualizaciones incompletas.

    Para resolver estos problemas, puedes esperar a que finalice una exclusión, quitarla o ajustar tus períodos de mantenimiento para permitir que se completen las actualizaciones.

  2. Si no usas un canal de versiones, verifica que la actualización automática siga habilitada para el grupo de nodos:

    gcloud container node-pools describe NODE_POOL_NAME \
    --cluster CLUSTER_NAME \
    --location LOCATION

    Reemplaza NODE_POOL_NAME por el nombre del grupo de nodos que deseas describir.

    Si las actualizaciones automáticas del grupo de nodos están habilitadas para este grupo de nodos, el resultado en el campo autoUpgrade es el siguiente:

    management:
  autoUpgrade: true

    Si autoUpgrade está establecido en false o el campo no está presente, habilita las actualizaciones automáticas.

  3. Es posible que la actualización no se haya lanzado en la región o zona en la que se encuentra tu clúster, incluso si se mencionó en las notas de la versión. Las actualizaciones de GKE se lanzan de forma progresiva durante varios días (por lo general, cuatro o más). Una vez que la actualización llega a tu región o zona, solo se inicia durante los períodos de mantenimiento aprobados. Por ejemplo, un lanzamiento podría llegar a la zona de tu clúster el primer día del lanzamiento, pero el siguiente período de mantenimiento del clúster no será hasta el séptimo día. En este caso, GKE no actualizará el clúster hasta el séptimo día. Para obtener más información, consulta el programa de lanzamientos de GKE.

Los clústeres se actualizan automáticamente cuando no está habilitada la actualización automática

Para ayudar a mantener la confiabilidad, la disponibilidad, la seguridad y el rendimiento de tu entorno de GKE, es posible que GKE actualice automáticamente tus clústeres, incluso si no usas las actualizaciones automáticas.

GKE podría omitir tus períodos de mantenimiento, exclusiones o actualizaciones automáticas inhabilitadas del grupo de nodos para realizar las actualizaciones necesarias por varios motivos críticos, como los siguientes:

  • Clústeres cuyos planos de control ejecutan una versión de GKE que alcanzó su fecha de finalización de la asistencia. Para confirmar que tu clúster se acerca a la fecha del final de la compatibilidad, consulta el Programa estimado para los canales de versiones.
  • Nodos dentro de un clúster que ejecutan una versión de GKE que alcanzó su fecha de final de asistencia.
  • Clústeres que están en estado de ejecución, pero no muestran actividad durante un período prolongado. Por ejemplo, GKE podría considerar que un clúster sin llamadas a la API, sin tráfico de red y sin uso activo de subredes está abandonado.
  • Clústeres que muestran inestabilidad persistente y que cambian de estado operativo de forma reiterada. Por ejemplo, los estados que se repiten de en ejecución a degradado, en reparación o suspendido y de vuelta a en ejecución sin una resolución.

Si observas una actualización automática inesperada y te preocupa el efecto que podría tener en tu clúster, comunícate con Atención al cliente de Cloud para obtener ayuda.

Soluciona problemas de actualizaciones con errores

Cuando falla la actualización, GKE produce mensajes de error. En las siguientes secciones, se explican las causas y las soluciones de los siguientes errores:

Error: kube-apiserver no está en buen estado

A veces, es posible que veas el siguiente mensaje de error cuando inicies una actualización manual del plano de control de la versión de GKE de tu clúster:

FAILED: All cluster resources were brought up, but: component
"KubeApiserverReady" from endpoint "readyz of kube apiserver is not successful"
is unhealthy.

Este mensaje aparece en gcloud CLI y en las entradas de registro de los tipos de recursos gke_cluster y gke_nodepool.

Este problema se produce cuando algunos webhooks de admisión implementados por el usuario impiden que los componentes del sistema creen los roles de RBAC permisivos que se requieren para funcionar correctamente.

Durante una actualización del plano de control, GKE vuelve a crear el componente del servidor de la API de Kubernetes (kube-apiserver). Si un webhook bloquea el rol de RBAC para el componente del servidor de la API, este no se iniciará y la actualización del clúster no se completará. Incluso si un webhook funciona correctamente, puede provocar un error en la actualización del clúster porque es posible que el plano de control recién creado no pueda acceder al webhook.

Kubernetes concilia automáticamente los roles de RBAC del sistema predeterminados con las políticas predeterminadas en la última versión secundaria. Las políticas predeterminadas para las funciones del sistema a veces cambian en las nuevas versiones de Kubernetes.

Para realizar esta conciliación, GKE crea o actualiza los ClusterRoles y ClusterRoleBindings en el clúster. Si tienes un webhook que intercepta y rechaza las solicitudes de creación o actualización debido al alcance de los permisos que usan las políticas de RBAC predeterminadas, el servidor de la API no puede funcionar en la versión secundaria nueva.

Para identificar el webhook con errores, verifica tus registros de auditoría de GKE para las llamadas de RBAC con la siguiente información:

protoPayload.resourceName="RBAC_RULE"
protoPayload.authenticationInfo.principalEmail="system:apiserver"

En este resultado, RBAC_RULE es el nombre completo del rol de RBAC, como rbac.authorization.k8s.io/v1/clusterroles/system:controller:horizontal-pod-autoscaler.

El nombre del webhook con errores se muestra en el registro con el siguiente formato:

admission webhook WEBHOOK_NAME denied the request

Para resolver este problema, prueba con las siguientes soluciones:

  1. Revisa tus ClusterRoles para asegurarte de que no sean demasiado restrictivos. Tus políticas no deben bloquear las solicitudes de GKE para crear o actualizar los ClusterRoles con el prefijo system: predeterminado.
  2. Ajusta el webhook con el fin de no interceptar solicitudes para crear y actualizar roles de RBAC del sistema.
  3. Inhabilita el webhook.

Error: No se pudo ejecutar DeployPatch

A veces, la operación de actualización del clúster falla con el siguiente error:

DeployPatch failed

Este error puede ocurrir si el plano de control de Kubernetes permanece en mal estado durante más de 20 minutos.

Este error suele ser transitorio porque el plano de control vuelve a intentar la operación hasta que se realiza correctamente. Si la actualización sigue fallando con este error, comunícate con Atención al cliente de Cloud.

Soluciona problemas después de una actualización completada

Si observas un comportamiento inesperado después de que se complete la actualización, en las siguientes secciones, se ofrece orientación para solucionar los siguientes problemas comunes:

Comportamiento inesperado debido a cambios rotundos

Si la actualización se completó correctamente, pero observas un comportamiento inesperado después de una actualización, consulta las notas de la versión de GKE para obtener información sobre errores y cambios rotundos relacionados con la versión a la que se actualizó el clúster.

Cargas de trabajo expulsadas después de la actualización del clúster estándar

Es posible que las cargas de trabajo estén en riesgo de expulsión después de la actualización del clúster si se cumplen todas las condiciones siguientes:

  • Las cargas de trabajo del sistema requieren más espacio cuando el plano de control del clúster ejecuta la versión nueva de GKE.
  • Tus nodos existentes no tienen suficientes recursos para ejecutar las nuevas cargas de trabajo del sistema y tus cargas de trabajo existentes.
  • El escalador automático de clúster está inhabilitado para el clúster.

Para resolver este problema, prueba con las siguientes soluciones:

  1. Habilita el ajuste de escala automático para grupos de nodos existentes.
  2. Habilita el aprovisionamiento automático de nodos.
  3. Crea un grupo de nodos nuevo.
  4. Escala verticalmente un grupo de nodos existente.

Los Pods quedaron en el estado Pending después de configurar la asignación de nodos

Si configuraste Node Allocatable, a veces, una actualización de la versión del nodo puede hacer que los Pods que tenían un estado Running queden atascados en un estado Pending. Por lo general, este cambio se produce porque el nodo actualizado consume recursos del sistema ligeramente diferentes o porque los Pods que se reprogramaron ahora deben ajustarse a los límites de Node Allocatable en los nodos nuevos o modificados, posiblemente en condiciones más estrictas.

Si tus Pods tienen el estado Pending después de una actualización, prueba las siguientes soluciones:

  1. Verifica que las solicitudes de CPU y memoria para tus Pods no excedan su uso máximo. Cuando GKE reserva CPU y memoria para la sobrecarga, los Pods no pueden solicitar estos recursos. Los Pods que solicitan más CPU o memoria de la que usan evitan que otros Pods soliciten estos recursos y es posible que dejen el clúster con poco uso. Para obtener más información, consulta Cómo se programan los pods con solicitudes de recursos en la documentación de Kubernetes.
  2. Considera aumentar el tamaño de tu clúster.
  3. Para verificar si la actualización es la causa de este problema, revierte la actualización cambiando a una versión anterior de tus grupos de nodos.
  4. Configura tu clúster para enviar métricas del programador de Kubernetes a Cloud Monitoring y consulta las métricas del programador. Si supervisas estas métricas, puedes determinar si hay suficientes recursos para que se ejecuten los Pods.

Soluciona problemas de versión y compatibilidad

Mantener versiones compatibles y admitidas para todos los componentes del clúster es fundamental para la estabilidad y el rendimiento. En las siguientes secciones, se brinda orientación para identificar y resolver problemas de versiones y compatibilidad que pueden afectar el proceso de actualización.

Verifica si hay incompatibilidad entre la versión del plano de control y la del nodo

El sesgo de versiones entre el plano de control y los nodos puede causar inestabilidad en el clúster. La política de sesgo de versiones de GKE establece que un plano de control solo es compatible con nodos de hasta dos versiones secundarias anteriores. Por ejemplo, un plano de control 1.19 funciona con nodos 1.19, 1.18 y 1.17.

Si tus nodos no se encuentran dentro de este período admitido, corres el riesgo de tener problemas de compatibilidad críticos. Estos problemas suelen estar relacionados con la API. Por ejemplo, una carga de trabajo en un nodo anterior podría usar una versión de la API que se haya dejado de usar o se haya quitado en el plano de control más reciente. Esta incompatibilidad también puede provocar fallas más graves, como una ruta de red interrumpida que impide que los nodos se registren en el clúster si una carga de trabajo incompatible interrumpe la comunicación.

El equipo de GKE realiza actualizaciones periódicas del plano de control del clúster por ti. Los planos de control se actualizan a versiones estables más nuevas de Kubernetes. Para garantizar que tus nodos sigan siendo compatibles con el plano de control actualizado, también deben mantenerse actualizados. De forma predeterminada, GKE controla esta actualización porque los nodos de un clúster tienen habilitada la actualización automática, y te recomendamos que no la inhabilite. Si la actualización automática está inhabilitada para los nodos de un clúster y no los actualizas manualmente, el plano de control dejará de ser compatible con tus nodos.

Para confirmar si las versiones del plano de control y de los nodos son incompatibles, verifica qué versión de Kubernetes ejecutan el plano de control y los grupos de nodos de tu clúster:

gcloud container clusters describe CLUSTER_NAME \
    --project PROJECT_ID  \
    --location LOCATION

Reemplaza lo siguiente:

  • CLUSTER_NAME: Es el nombre del clúster del grupo de nodos que se describirá.
  • PROJECT_ID: El ID del proyecto del clúster.
  • LOCATION: Es la región o zona de Compute Engine (por ejemplo, us-central1 o us-central1-a) para el clúster.

El resultado es similar a este:

…
currentMasterVersion: 1.32.3-gke.1785003
…
currentNodeVersion: 1.26.15-gke.1090000
…

En este ejemplo, la versión del plano de control y la versión del grupo de nodos son incompatibles.

Para resolver este problema, actualiza manualmente la versión del grupo de nodos a una versión compatible con el plano de control.

Si te preocupa que el proceso de actualización genere interrupciones en las cargas de trabajo que se ejecutan en los nodos afectados, completa los siguientes pasos para migrar tus cargas de trabajo a un grupo de nodos nuevo:

  1. Crea un grupo de nodos nuevo con una versión compatible.
  2. Acordona los nodos del grupo de nodos existente.
  3. Opcional: Actualiza las cargas de trabajo que se ejecutan en el grupo de nodos existente para agregar un nodeSelector para la etiqueta cloud.google.com/gke-nodepool:NEW_NODE_POOL_NAME. Reemplaza NEW_NODE_POOL_NAME por el nombre del grupo de nodos nuevo. Esta acción garantiza que GKE coloque esas cargas de trabajo en nodos en el grupo de nodos nuevo.
  4. Desvía el grupo de nodos existente.
  5. Comprueba que las cargas de trabajo se ejecuten de forma correcta en el grupo de nodos nuevo. Si es así, puedes borrar el grupo de nodos anterior. Si observas interrupciones en la carga de trabajo, reprograma las cargas de trabajo en los nodos existentes. Para ello, desacordona los nodos en el grupo de nodos existente y agota los nodos nuevos.

El uso de CPU del nodo es más alto de lo esperado

Es posible que surja algún problema en el que algunos nodos hacen un uso de CPU más alto que el esperado de los Pods en ejecución.

Este problema puede ocurrir si usas actualizaciones manuales y tus clústeres o nodos no se actualizaron para ejecutar una versión compatible. Revisa las notas de la versión para asegurarte de que las versiones que usas estén disponibles y sean compatibles.

¿Qué sigue?