Ayude a mejorar esta página

Para contribuir a esta guía del usuario, elija el enlace Edit this page on GitHub que se encuentra en el panel derecho de cada página.

Reversión de un clúster a una versión anterior de Kubernetes

Con la reversión de la versión de Kubernetes, puede revertir el plano de control de Kubernetes de su clúster a la versión secundaria anterior después de llevar a cabo una actualización in situ. Si detecta algún problema después de la actualización, como incompatibilidades entre aplicaciones, un uso obsoleto de la API o un comportamiento inesperado, puede revertirla para restaurar el clúster a un estado en buen funcionamiento conocido.

Durante una reversión, Amazon EKS revierte el servidor de la API de Kubernetes y los componentes del plano de control a la versión anterior mientras conserva todos los datos de etcd, las cargas de trabajo de los clientes y los volúmenes persistentes.

Qué se revierte

Se revierten los siguientes componentes:

Qué NO se revierte

No se revierten los siguientes componentes:

Requisitos previos

Antes de poder revertir un clúster, deben cumplirse todas las condiciones siguientes:

Además de los requisitos anteriores, hay algunas condiciones que imposibilitan la reversión incluso con el indicador --force. Estas condiciones incluyen las siguientes: el clúster se creó con la versión actual, han pasado más de 7 días desde la actualización, el clúster ya se ha actualizado de nuevo a una versión más reciente o se ha habilitado una característica de EKS incompatible con versiones anteriores en el límite de la versión actual.

Resumen

A continuación, se ofrece un resumen general del proceso de reversión del clúster de Amazon EKS:

Paso 1: revisión de la información de preparación para la reversión

Amazon EKS evalúa automáticamente el clúster en función de un conjunto de comprobaciones de preparación para la reversión en un momento dado y detecta cualquier problema a través de la información del clúster en la categoría ROLLBACK_READINESS. Esta información aparece después de llevar a cabo una actualización y está disponible durante el periodo de 7 días en el que se puede revertir.

Visualización de la información de preparación para la reversión

Consola de AWS:

AWS CLI:

aws eks list-insights \
  --cluster-name my-cluster \
  --region us-west-2 \
  --filter '{"categories": ["ROLLBACK_READINESS"]}'

Para obtener detalles sobre una información específica:

aws eks describe-insight \
  --cluster-name my-cluster \
  --region us-west-2 \
  --id <insight-id>

Actualización de la información

Amazon EKS actualiza la información cada 24 horas. Para activar manualmente una actualización después de resolver los problemas, elija el botón Actualizar en la consola de Amazon EKS o con la CLI:

aws eks start-insights-refresh \
  --cluster-name my-cluster \
  --region us-west-2

Comportamiento del estado de la información

En la siguiente tabla, se describe el significado de cada estado de la información y su efecto en la reversión:

La información con el estado de ERROR o DESCONOCIDO bloquea la reversión. La información con el estado de APROBADO o ADVERTENCIA no le impiden efectuar la reversión.

Comprobaciones de preparación para la reversión

Amazon EKS lleva a cabo una serie de comprobaciones como parte de la información de preparación para la reversión. Estas comprobaciones evalúan la compatibilidad de uso de la API (incluida la detección de cambios de campos), el estado del clúster, el sesgo de las versiones de kubelet, el sesgo de las versiones de kube-proxy y la compatibilidad de las versiones de los complementos. En el caso de los clústeres que ejecutan el modo automático de EKS, las comprobaciones adicionales evalúan los presupuestos de interrupción de NodePool, las anotaciones do-not-disrupt y las configuraciones de PodDisruptionBudget.

Uso del indicador --force

Si la información de preparación para la reversión muestra el estado de ERROR y quiere continuar sin resolver los problemas, puede utilizar el indicador --force para omitir todas las comprobaciones de información:

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --force \
  --region us-west-2

El indicador --force solo omite las comprobaciones de información. No omite las validaciones de requisitos previos, como el plazo de 7 días, la comprobación de la versión de creación o la comprobación secuencial de la reversión. Para los clústeres del modo automático, --force no anula los controles de interrupción. Se continúan respetando los presupuestos de interrupción de NodePool, los PDB y las anotaciones do-not-disrupt.

Paso 2: preparación de los nodos de trabajo

Antes de revertir el plano de control, asegúrese de que los nodos de trabajo sean compatibles con la versión de destino. La política de sesgo de versiones de Kubernetes exige que los nodos de trabajo no puedan ejecutar una versión más reciente que la del plano de control.

Modo automático de EKS

No hay que hacer nada. Al iniciar la reversión, Amazon EKS revierte automáticamente los nodos del modo automático antes del plano de control. Para obtener más información, consulte Reversión de clústeres del modo automático de EKS.

Grupos de nodos administrados (MNG)

Debe revertir los grupos de nodos administrados a la versión anterior antes de revertir el plano de control. Utilice la API UpdateNodegroupVersion:

aws eks update-nodegroup-version \
  --cluster-name my-cluster \
  --nodegroup-name my-nodegroup \
  --kubernetes-version 1.30 \
  --region us-west-2

La actualización del grupo de nodos respeta los ajustes de actualización configurados (maxUnavailable o maxUnavailablePercentage) y la estrategia de actualización (continua o forzada).

Nodos autoadministrados y nodos híbridos

Usted es responsable de revertir los nodos autoadministrados y los nodos híbridos. Actualice las AMI o las configuraciones de los nodos para usar la versión anterior de Kubernetes antes de revertir el plano de control.

Fargate

La reversión de la versión no es compatible con los nodos de trabajo de Fargate. Puede revertir el plano de control de un clúster que utilice Fargate, pero los pods de Fargate que ejecutan la misma versión de Kubernetes que el plano de control activan la información de sesgo de la versión de kubelet con el estado de ERROR.

Amazon EKS no puede revertir automáticamente los pods de Fargate a una versión anterior de kubelet.

Solución alternativa: si tiene pods de Fargate que ejecutan la misma versión de Kubernetes que el plano de control, elimínelos antes de iniciar la reversión. A continuación, revierta el plano de control. Los pods restantes se lanzarán con la versión revertida cuando los vuelva a implementar.

Como alternativa, utilice --force para omitir la comprobación de información. Sin embargo, continuar con una infracción del sesgo de la versión de kubelet podría provocar un comportamiento inesperado en las cargas de trabajo de Fargate hasta que se sustituyan esos pods.

Paso 3: reversión del plano de control del clúster

Puede iniciar una reversión con la consola de AWS, la AWS CLI o la API de EKS.

Reversión de un clúster con la consola de AWS

La reversión tarda varios minutos en completarse. Para los clústeres del modo automático, la fase de reversión de nodos puede tardar más. Para obtener más información, consulte Reversión de clústeres del modo automático de EKS.

Reversión de un clúster con la AWS CLI

Utilice el comando update-cluster-version existente con la versión anterior (N-1) de Kubernetes:

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --region us-west-2

Respuesta de ejemplo:

{
    "update": {
        "id": "e4091a28-ea14-48fd-a8c7-975aeb469e8a",
        "status": "InProgress",
        "type": "VersionRollback",
        "params": [
            {
                "type": "Version",
                "value": "1.30"
            },
            {
                "type": "PlatformVersion",
                "value": "eks.16"
            }
        ],
        "createdAt": "2026-05-12T16:56:01.082000-04:00",
        "errors": []
    }
}

Paso 4: supervisión del progreso de la reversión

Puede supervisar el estado de la reversión del clúster desde la consola de Amazon EKS o la AWS CLI.

AWS CLI:

aws eks describe-update \
  --name my-cluster \
  --region us-west-2 \
  --update-id e4091a28-ea14-48fd-a8c7-975aeb469e8a

Consola de AWS:

Transiciones de estado

Para clústeres estándar (sin el modo automático):

InProgress → Successful
InProgress → Failed

Para los clústeres del modo automático, el estado del clúster permanece como ACTIVE mientras los nodos se revierten y cambia a UPDATING solo cuando comienza la reversión del plano de control. Utilice describe-update para hacer un seguimiento del progreso general de la reversión. Para obtener más información, consulte Reversión de clústeres del modo automático de EKS.

Cuando se muestra el estado Successful, la reversión se ha completado.

Consideraciones y advertencias

La información es óptima y en un momento determinado

La información del clúster se evalúa en el momento en que se activa la reversión. Si hace cambios en el clúster después de comprobar la información, pero antes de que se complete la reversión (por ejemplo, al crear recursos con nuevas API), la comprobación inicial de la información no captura esos cambios y podrían provocar problemas una vez finalizada la reversión.

Conservación de datos de etcd

Amazon EKS conserva los datos de etcd durante la reversión. Los recursos incompatibles omitidos con el indicador --force permanecen persistentes y no se recopilan como elementos no utilizados.

Precios del soporte extendido

Si revierte de una versión con soporte estándar a una versión con soporte extendido, el clúster comienza a generar cargos por soporte extendido. Por ejemplo, si actualiza de la versión 1.30 (soporte extendido) a la 1.31 (soporte estándar) y, a continuación, revierte a la versión 1.30, los cargos por soporte extendido se reanudarán.

Modelo de responsabilidad compartida para la reversión

Amazon EKS revierte el plano de control de Kubernetes a la versión deseada. Como parte del modelo de responsabilidad compartida, usted es responsable de verificar la compatibilidad de la aplicación con la versión anterior:

Comportamiento de reversión de las pilas de CloudFormation

Si se produce un error en una actualización de pilas de AWS CloudFormation y se activa una reversión de pilas, la reversión a una versión anterior de la plantilla que especifique una versión inferior de Kubernetes no activa ninguna reversión de la versión del clúster. La reversión de la versión debe iniciarse de forma explícita a través de la API UpdateClusterVersion, la CLI o la consola.

Reversión y complementos

Amazon EKS no revierte automáticamente las versiones de los complementos durante la reversión de la versión de clúster. Debe administrar las versiones de los complementos por separado.

Antes de revertir el plano de control:

Recursos relacionados