2026年11月12日

Actualizar un clúster de Kubernetes: kubeadm y servicios gestionados

Docker y contenedores

Este artículo es una edición localizada del original en japonés. Leer el original en japonés

Un clúster de Kubernetes se actualiza subiendo una versión menor cada vez, en este orden: plano de control, complementos (add-ons) y nodos. El procedimiento en sí es corto, pero la mayoría de los bloqueos se deben a comprobaciones previas insuficientes. Los casos típicos son manifiestos que usan APIs eliminadas, Pods de los que no se puede vaciar un nodo y copias de seguridad de etcd que se olvidaron. Este artículo explica qué comprobar antes de actualizar, el procedimiento para un clúster creado con kubeadm, cómo sustituir los nodos de uno en uno y cómo es el proceso en servicios gestionados como EKS.

Kubernetes publica aproximadamente tres versiones menores al año y cada una recibe soporte durante unos 14 meses (a octubre de 2026). Si lo dejas un año sin tocar, el fin del soporte se acerca, así que lo realista es planificar la actualización como una tarea periódica.

Qué comprobar antes de actualizar

1. Versión de destino y orden

El plano de control no admite saltarse versiones menores. Si quieres pasar de la 1.31 a la 1.33, debes pasar por la 1.32. Las versiones de parche (por ejemplo, de la 1.32.3 a la 1.32.8) sí puedes saltártelas.

Comprueba además las reglas sobre la diferencia de versiones entre componentes (desfase de versiones o version skew).

kubelet no debe ser más reciente que kube-apiserver. Con los más antiguos se permite una diferencia dentro de un margen (según la política actual, hasta 3 versiones menores).
kubectl puede diferir de kube-apiserver como máximo en una versión menor, hacia arriba o hacia abajo.

Por estas reglas el orden es primero el plano de control y después los nodos. El margen permitido ha cambiado en el pasado, así que consúltalo en la página «Version Skew Policy» de la versión a la que vas a actualizar.

2. Que no uses APIs que se eliminan

Al subir una versión menor, a veces se eliminan versiones de API que estaban obsoletas. Los manifiestos o los charts de Helm escritos con una versión de API eliminada dejan de poder ejecutar apply después de la actualización.

Para comprobarlo, lo más eficiente es consultar en la guía oficial «Deprecated API Migration Guide» qué APIs se eliminan en la versión de destino y luego usar una herramienta que inspeccione tus manifiestos. Herramientas como pluto o kubent (kube-no-trouble) buscan el uso de APIs antiguas en los manifiestos, en los recursos del clúster y en las releases de Helm.

# Comprueba las «peticiones a APIs obsoletas» que registra kube-apiserver
kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis

Lo que aparezca en esta métrica es prueba de que algo dentro del clúster está llamando realmente a una API antigua. A veces las llamadas no vienen del repositorio de manifiestos, sino de CI/CD, de operadores o de herramientas de monitorización.

3. Que se puedan vaciar los nodos

Al actualizar un nodo, se mueven sus Pods a otro nodo (drain). En ese momento, si hay Pods como los siguientes, el proceso puede bloquearse o el servicio puede interrumpirse.

Un Deployment con una sola réplica: el servicio se detiene mientras se mueve.
Un PodDisruptionBudget (PDB) demasiado estricto: si minAvailable es igual al número de réplicas, no se puede evacuar ninguna y el drain no avanza.
Pods con datos en el disco local del nodo (emptyDir): al evacuarlos, el contenido se pierde.

Para las aplicaciones importantes, usa dos o más réplicas y define con un PDB cuántas pueden estar detenidas a la vez.

4. Copia de seguridad de etcd

En general, no se puede volver atrás en la versión del plano de control. El último recurso cuando algo sale mal es restaurar desde una instantánea de etcd, así que haz una justo antes de empezar. En un clúster creado con kubeadm, ejecútala en el nodo del plano de control como se muestra a continuación (las rutas de los certificados son las predeterminadas de kubeadm).

sudo ETCDCTL_API=3 etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save /var/backups/etcd-$(date +%Y%m%d).db

Copia también la instantánea a otro servidor. Haz además una copia de seguridad aparte de los datos de las aplicaciones (volúmenes persistentes y bases de datos). etcd solo contiene las definiciones de los recursos de Kubernetes.

5. Prueba primero en un entorno de pruebas

Si tienes un clúster de pruebas con la misma configuración, actualízalo primero y comprueba que las aplicaciones funcionan. Revisa también en las notas de versión de cada uno si los complementos (CNI, controlador de Ingress, cert-manager, etc.) son compatibles con la nueva versión.

Procedimiento para un clúster creado con kubeadm

Aquí se explica para Ubuntu/Debian, suponiendo que instalas los paquetes desde el repositorio pkgs.k8s.io. Este repositorio está dividido por versión menor, así que debes cambiar la URL al repositorio de la versión de destino antes de actualizar. El repositorio antiguo apt.kubernetes.io ya no se puede usar, por lo que no uses tal cual los comandos de manuales antiguos.

Plano de control (primer nodo)

# Después de cambiar la versión del repositorio
sudo apt-get update
sudo apt-mark unhold kubeadm
sudo apt-get install -y kubeadm='1.33.x-*'   # x es el número de parche disponible
sudo apt-mark hold kubeadm

kubeadm version
sudo kubeadm upgrade plan
sudo kubeadm upgrade apply v1.33.x

kubeadm upgrade plan muestra a qué versiones se puede actualizar desde la actual y cómo cambiará cada componente. Si aparecen errores o advertencias, resuélvelos antes de pasar a apply. Además de actualizar los Pods estáticos como kube-apiserver, apply sustituye también CoreDNS y kube-proxy por la nueva versión.

En el segundo plano de control y los siguientes, ejecuta sudo kubeadm upgrade node en lugar de apply.

kubelet y kubectl de cada nodo

Incluidos los nodos del plano de control, avanza de uno en uno con el siguiente flujo.

# Desde el equipo de trabajo: evacúa los Pods y excluye el nodo de la planificación
kubectl drain <nombre-del-nodo> --ignore-daemonsets --delete-emptydir-data

# En el nodo de destino:
# (en un nodo de trabajo, aquí se actualiza kubeadm y se ejecuta sudo kubeadm upgrade node)
sudo apt-mark unhold kubelet kubectl
sudo apt-get install -y kubelet='1.33.x-*' kubectl='1.33.x-*'
sudo apt-mark hold kubelet kubectl
sudo systemctl daemon-reload
sudo systemctl restart kubelet

# Desde el equipo de trabajo: vuelve a incluir el nodo en la planificación
kubectl uncordon <nombre-del-nodo>
kubectl get nodes

Si añades --delete-emptydir-data, el contenido de emptyDir se perderá. Antes de añadirlo, comprueba que no haya Pods con datos que no puedas perder. Si el drain no termina, busca con kubectl get pdb -A el PDB que impide la evacuación. Cuando un nodo termine y vuelva a Ready, comprueba que las aplicaciones funcionan con normalidad antes de pasar al siguiente.

Sustituir los nodos por otros nuevos

En lugar de actualizar los nodos existentes, también puedes añadir nodos con la nueva versión y hacer drain y eliminar los antiguos uno tras otro. En los clústeres en la nube es lo más habitual. Permite cambiar de una vez el sistema operativo y el runtime de contenedores a una imagen nueva y, si algo falla, puedes eliminar los nodos nuevos y volver a los antiguos.

Para ir con aún más cautela, también puedes crear aparte un clúster completo con la nueva versión, migrar las aplicaciones y cambiar el tráfico con el DNS o el balanceador de carga (blue-green). Da más trabajo, pero si surge un problema en el plano de control puedes volver al clúster original.

Servicios gestionados

En EKS, GKE y AKS, la actualización del plano de control se hace con un solo comando o desde la consola. Sin embargo, el criterio para las comprobaciones previas y el orden de actualizar los nodos después son los mismos. Si gestionas EKS con eksctl, el flujo es el siguiente.

eksctl upgrade cluster --name wp-cluster --version 1.33 --approve
eksctl upgrade nodegroup --cluster wp-cluster --name ng-general --kubernetes-version 1.33

Después del plano de control, actualiza también los complementos como vpc-cni y coredns a versiones compatibles con la nueva. EKS también dispone de una función que avisa, antes de actualizar, del uso de APIs obsoletas y similares, que puedes consultar en la consola o con la CLI. GKE puede actualizarse automáticamente según el canal de lanzamientos y AKS se actualiza con az aks upgrade. Las funciones y el comportamiento predeterminado de cada servicio pueden cambiar, así que consulta la documentación oficial cada vez que vayas a trabajar.

Comprobaciones después de actualizar

Con kubectl get nodes: que todos los nodos estén en Ready y que la versión sea la esperada.
Con kubectl get pods -A: que no haya Pods en CrashLoopBackOff o Pending.
Que la aplicación se abra a través de Ingress (en el caso de WordPress, la página de inicio y el panel de administración).
Que los agentes de monitorización y de recogida de registros sigan enviando datos.

Para los Pods con problemas, busca la causa en Events de kubectl describe pod y con kubectl logs --previous.

Resumen

Sube las versiones menores de una en una, en este orden: plano de control, complementos y nodos. No dejes kubelet por delante de kube-apiserver.
Busca de antemano las APIs que se eliminan con la guía y las herramientas, y comprueba también quién las llama realmente con apiserver_requested_deprecated_apis.
Revisa los PDB y el número de réplicas para que el drain no interrumpa el servicio.
Justo antes de empezar, haz una copia de seguridad de la instantánea de etcd y de los datos de las aplicaciones. En general, no se puede volver a una versión anterior.
Con kubeadm, cambia al repositorio de pkgs.k8s.io de cada versión y después ejecuta kubeadm upgrade plan / apply.

¿Dudas sobre WordPress? Quien publica este sitio está en Japón y responde en japonés. Contacto (en japonés)