En la lección anterior levantamos clústeres desechables en el portátil y descubrimos, casi de pasada, que kind usa kubeadm por dentro: aquel campo kubeadmConfigPatches del fichero de configuración no era casualidad. Ahora vamos a la herramienta directamente.

kubeadm es la herramienta oficial del proyecto Kubernetes para arrancar un clúster conforme sobre máquinas que tú controlas. Es la base sobre la que están construidas casi todas las distribuciones, y entenderla te da algo que ninguna otra vía te da: ver con tus propios ojos dónde están los certificados, dónde viven los pods estáticos del plano de control y qué ocurre exactamente cuando un nodo se une al clúster. Aunque Rutas Norte S.L. acabe eligiendo un clúster gestionado (10-06), este conocimiento es el que te permitirá depurar un plano de control roto y aprobar la certificación CKA (12-01).

1. Qué es kubeadm y qué no es
2. Autogestionado frente a gestionado: cuándo tiene sentido
3. Preparación de las máquinas
4. Instalación de containerd
5. Instalación de kubeadm, kubelet y kubectl
6. kubeadm init con fichero de configuración
7. Qué crea exactamente kubeadm en el nodo
8. Instalar el CNI y por qué los nodos están NotReady
9. Unir nodos de trabajo
10. Plano de control en alta disponibilidad
11. Gestión de certificados
12. Actualización de versión
13. Copia de seguridad y restauración de etcd
14. kubeadm reset y limpieza
15. Errores comunes y consejos
16. Ejercicios
17. Conclusión

kubeadm hace una sola cosa bien: dadas unas máquinas ya preparadas, arranca en ellas un plano de control y une nodos de trabajo, produciendo un clúster que pasa las pruebas de conformidad de Kubernetes.

Esa lista de la derecha es la clave. Mucha gente ejecuta kubeadm init, ve el mensaje de éxito, y luego se sorprende de que kubectl get nodes diga NotReady. No hay ningún error: falta el CNI, y ese trabajo no es de kubeadm.

Antes de escribir una sola orden, la pregunta honesta: ¿debería Rutas Norte S.L. operar su propio clúster?

Advertencia seria: operar un clúster propio en producción exige un equipo dedicado. No es una tarea que se pueda añadir a la lista de otro puesto. Necesitas cobertura para incidentes fuera de horario, un procedimiento probado de restauración de etcd, una política de parches del sistema operativo, y alguien que entienda los certificados cuando caduquen. Si tu organización no puede sostener eso, un clúster gestionado no es una comodidad: es una decisión de gestión de riesgo.

Cuándo kubeadm sí es la respuesta correcta: centro de datos propio o hardware específico (GPU, baja latencia, cumplimiento normativo); necesidad de configuraciones del plano de control que ningún gestionado permite; ahorro de coste con muchos nodos; y aprendizaje y certificación, porque el CKA (12-01) evalúa exactamente esto.

Para Rutas Norte montaremos un clúster con kubeadm en un laboratorio para aprender y practicar, con la conclusión razonada de producción reservada para 10-06.

Partimos de tres máquinas Ubuntu 24.04 LTS en el laboratorio de Rutas Norte:

Requisitos mínimos oficiales: 2 CPU y 2 GB de RAM por nodo de control, nombre de host único, dirección MAC única y product_uuid único (sudo cat /sys/class/dmi/id/product_uuid). Si dos máquinas clonadas comparten product_uuid, el clúster puede confundirlas: regenéralo desde el hipervisor.

Todos los pasos siguientes se ejecutan en las tres máquinas.

¿Por qué hay que desactivar el swap? Porque rompe el modelo de recursos que estudiamos en 03-04 y 03-05. El planificador decide dónde va un pod según la memoria solicitada y disponible; el kubelet expulsa pods cuando el nodo tiene presión de memoria, siguiendo las clases de QoS. Si hay swap, un pod que supera su límite de memoria no muere: empieza a paginar a disco, se vuelve mil veces más lento, sus sondas de liveness empiezan a fallar de forma errática y el nodo entero se degrada sin que ninguna métrica lo explique. Es un fallo mucho peor que un OOMKilled limpio.

Kubernetes 1.30 tiene soporte experimental de swap (NodeSwap), pero está en beta con muchas advertencias. Para un clúster de producción, swap desactivado.

Qué hace cada uno:

• overlay: el sistema de ficheros por capas que usa containerd para montar las imágenes de contenedor. Sin él, el runtime no puede crear contenedores.
• br_netfilter: permite que el tráfico que atraviesa un puente de red de Linux (el que conecta los contenedores del nodo) sea visible para iptables. Sin él, kube-proxy escribe reglas que nunca se aplican al tráfico entre pods, y los Services simplemente no funcionan.

• ip_forward = 1: el nodo debe reenviar paquetes entre interfaces. Sin esto, un pod de rn-worker-1 no puede hablar con uno de rn-worker-2.
• bridge-nf-call-iptables = 1: activa lo que br_netfilter hace posible.

Si sysctl te dice que el parámetro no existe, es que br_netfilter no está cargado. El orden importa.

Sobre el último: cada CNI usa lo suyo. Calico con VXLAN necesita UDP 4789; con IP-in-IP necesita el protocolo IP 4; Cilium con VXLAN, UDP 8472. Consulta la documentación del CNI que elijas.

Para el laboratorio basta con abrir esos puertos con ufw y permitir todo el tráfico de la red interna: sudo ufw allow from 10.10.0.0/24. Verifica desde otro nodo con nc -zv 10.10.0.11 6443.

Consejo de laboratorio: si estás aprendiendo y algo no conecta, desactiva temporalmente el cortafuegos (sudo ufw disable) para descartar que sea el culpable. En producción, jamás; ahí se documenta cada regla.

Kubernetes no ejecuta contenedores directamente: habla con un runtime a través de la interfaz CRI. Desde 1.24, Docker no es un runtime válido de forma directa; containerd es la opción estándar.

Aquí está el fallo número uno de los clústeres con kubeadm. containerd trae por defecto una configuración con SystemdCgroup = false, mientras que el kubelet de Kubernetes 1.30 usa el controlador de cgroups systemd. Si no coinciden, el clúster arranca aparentemente bien y luego los pods se reinician de forma aleatoria bajo presión de memoria, porque hay dos gestores de cgroups peleándose por el mismo nodo.

Si el grep no devuelve nada o devuelve false, la ruta de la opción ha cambiado en tu versión. Edita el fichero a mano y busca la sección [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options].

Si esto responde, el runtime está listo. crictl es tu herramienta de depuración a nivel de nodo: crictl ps, crictl images, crictl logs. Cuando el apiserver está caído, kubectl no sirve de nada y crictl es lo único que tienes.

Los tres se instalan desde el repositorio oficial de Kubernetes, que desde 1.28 está segmentado por versión menor. Esto es importante: el repositorio de v1.30 solo contiene parches de 1.30, lo que evita saltos accidentales de versión menor.

Por qué el hold es imprescindible: sin él, un apt upgrade rutinario de mantenimiento del sistema actualizaría el kubelet en un nodo cualquiera. Ese kubelet nuevo podría ser incompatible con el plano de control, o simplemente reiniciarse en mitad del día y expulsar todos los pods de ese nodo. Las actualizaciones de Kubernetes son un procedimiento planificado (apartado 12), nunca un efecto secundario.

Podrías arrancar el clúster con una ristra de banderas (kubeadm init --pod-network-cidr=... --control-plane-endpoint=... --apiserver-cert-extra-sans=...), y funcionaría. Pero el problema es evidente después de todo lo que llevamos de curso: no está versionado, nadie recuerda qué banderas se usaron hace un año, y al añadir un nodo de control hay que repetirlas exactamente. La forma profesional es un fichero de configuración, guardado junto a los manifiestos.

Ejecutamos:

--upload-certs sube los certificados del plano de control a un Secret temporal del clúster, cifrado, para que otros nodos de control puedan unirse sin copiarlos a mano. Caduca a las 2 horas.

Salida (muy abreviada):

Guarda esa salida. Las dos órdenes join del final son las que necesitas en los apartados 9 y 10.

NotReady. Es correcto, y lo explicamos en el apartado 8.

Sobre controlPlaneEndpoint: aunque hoy solo tengas un nodo de control y no un balanceador, decláralo con un nombre DNS desde el principio. Puedes hacer que ese nombre apunte hoy a 10.10.0.11 y mañana a la IP virtual del balanceador. Si no lo haces, el certificado y todos los kubeconfig apuntarán a la IP del nodo, y montar HA más tarde exige regenerar certificados en todo el clúster.

Este apartado conecta directamente con la arquitectura que vimos en 01-02. Ahora vamos a verla en el disco.

Esto es un pod estático: el kubelet vigila ese directorio y arranca cualquier pod que encuentre en él, sin pasar por el apiserver. Es la solución al problema del huevo y la gallina: ¿cómo arranca el apiserver, si para crear un pod hace falta un apiserver? Respuesta: no se crea como un pod normal, lo lee el kubelet directamente del disco.

Consecuencias prácticas muy importantes:

• Si editas /etc/kubernetes/manifests/kube-apiserver.yaml, el kubelet detecta el cambio y reinicia el apiserver automáticamente en segundos. Es la forma de añadir una bandera a mano.
• Si borras ese fichero, el apiserver desaparece y pierdes el clúster. Copia de seguridad antes de tocar nada.
• kubectl delete pod kube-apiserver-rn-control-1 -n kube-system no lo elimina de verdad: el kubelet lo recrea, porque la fuente de verdad es el fichero.
• Si el apiserver no arranca, kubectl no funciona. Depúralo con crictl ps -a y crictl logs, o con journalctl -u kubelet.

Para inspeccionar los nombres válidos de un certificado: sudo openssl x509 -in /etc/kubernetes/pki/apiserver.crt -noout -text | grep -A2 'Subject Alternative Name'.

En /etc/kubernetes/*.conf hay uno por componente: controller-manager.conf, scheduler.conf, kubelet.conf (credenciales de este nodo, con rotación automática) y dos de administración:

• admin.conf: el que copiaste a ~/.kube/config. Desde 1.29 pertenece al grupo kubeadm:cluster-admins, sujeto a RBAC (08-01).
• super-admin.conf: salta el RBAC por completo (system:masters). Es el rompecristales cuando has roto el RBAC y no puedes ni arreglarlo. No lo repartas.

En /var/lib/etcd/member/ (con sus directorios snap y wal) vive el estado completo de tu clúster: todos los objetos, todos los Secrets, todo. Es lo que hay que respaldar (apartado 13).

El mensaje es explícito. El kubelet se niega a declararse Ready mientras no exista un complemento de red que sepa asignar IP a los pods. Recuerda de 04-01: Kubernetes define el contrato (todo pod tiene una IP, todos los pods se ven sin NAT) pero no lo implementa. Eso es trabajo del CNI.

Verás también CoreDNS en Pending, y es normal: CoreDNS es un pod y necesita red para arrancar.

Instalamos Calico (el detalle de los CNI está en 04-01; aquí solo lo necesario):

Y CoreDNS arranca solo. La secuencia completa es:

En rn-worker-1 y rn-worker-2, ya preparados con los apartados 3, 4 y 5:

Qué significan los dos parámetros:

• --token: una credencial temporal (caduca a las 24 horas) que autoriza al nodo a pedir su certificado. Es un Secret de tipo bootstrap.kubernetes.io/token en kube-system.
• --discovery-token-ca-cert-hash: el hash SHA-256 de la clave pública de la CA del clúster. Sirve para que el nodo verifique al apiserver, no al revés. Sin él, un atacante podría suplantar el plano de control y capturar el token. Nunca uses --discovery-token-unsafe-skip-ca-verification fuera de un laboratorio.

Es la situación más habitual: quieres añadir un nodo tres semanas después y el token original ya no vale.

Órdenes relacionadas:

kubeadm no pone la etiqueta de rol en los nodos de trabajo por seguridad (un kubelet no puede autoasignarse etiquetas de rol). Se hace desde el plano de control:

Con un solo nodo de control, si rn-control-1 cae, el clúster sigue sirviendo tráfico (los pods siguen corriendo, kube-proxy sigue enrutando) pero pierdes toda capacidad de gestión: no hay reprogramación de pods, ni escalado, ni despliegues, ni HPA. Y si el disco de etcd se pierde, pierdes el clúster entero.

Todos los nodos de control publican el mismo puerto 6443. Necesitas algo delante que reparta:

Opciones: HAProxy + keepalived con una IP virtual flotante (lo más común en centro de datos propio), el balanceador de capa 4 de la nube si estás en máquinas virtuales, o kube-vip como pod estático si no quieres infraestructura externa. Lo que no vale es un DNS con varios registros A: el cliente cachea y no detecta caídas.

Configuración mínima de HAProxy:

Es TCP puro (modo tcp), no HTTP: la conexión al apiserver es TLS de extremo a extremo y el balanceador no debe terminarla. Con check, si un nodo deja de responder en 6443, HAProxy deja de enviarle tráfico automáticamente.

etcd necesita quórum: 1 miembro tolera 0 fallos, 2 miembros también toleran 0 (¡peor que 1!), 3 toleran 1, 4 toleran 1, y 5 toleran 2. Por eso el número de nodos de control es siempre impar: 1 (laboratorio), 3 (producción normal) o 5 (clústeres grandes).

Para etcd externo, se declara en el fichero de kubeadm:

La --certificate-key viene de --upload-certs. Si han pasado más de 2 horas, se regenera:

Para verificar la salud del clúster de etcd, kubectl -n kube-system exec etcd-rn-control-1 -- etcdctl ... endpoint status --cluster -w table debe mostrar los tres miembros, con la misma versión, tamaño de base de datos parecido y exactamente uno con IS LEADER = true.

Aquí está la trampa que sorprende a más equipos: los certificados que genera kubeadm caducan al año. Un clúster montado en marzo deja de funcionar en marzo del año siguiente, sin previo aviso, con un mensaje así:

Kubernetes renueva automáticamente los certificados durante kubeadm upgrade. Como muchos equipos actualizan al menos una vez al año, nunca lo ven. El que no actualiza, se lleva el susto.

Las CA duran 10 años; los certificados que firman, 1 año.

Recomendación de operación: no lo dejes al calendario humano. El apiserver expone apiserver_client_certificate_expiration_seconds_bucket, sobre la que se puede montar una alerta en Alertmanager (07-04). Más simple y más fiable todavía: un CronJob (06-03) o una tarea del sistema que ejecute kubeadm certs check-expiration semanalmente y avise si queda menos de un mes.

Nota sobre el kubelet: su certificado se rota solo, automáticamente, si rotateCertificates: true (por defecto). Los certificados que hay que renovar a mano son los del plano de control.

Solo puedes saltar una versión menor cada vez. De 1.28 a 1.30 no se puede ir directo: hay que hacer 1.28 → 1.29 → 1.30. Cada salto es un procedimiento completo.

Además, la política de desfase (version skew) exige:

De ahí el orden obligatorio: primero el plano de control, después los nodos de trabajo. Nunca al revés.

Tres cosas, por este orden: copia de seguridad de etcd (apartado 13, no negociable), leer las notas de la versión, y comprobar que nada usa APIs que desaparecen.

Cualquier línea aquí es trabajo que hay que hacer antes de actualizar. Herramientas como kubent (kube-no-trouble) o pluto escanean tus manifiestos buscando lo mismo.

Para los demás nodos de control y para los de trabajo, el procedimiento es el mismo del apartado anterior con una sola diferencia: se usa sudo kubeadm upgrade node en vez de upgrade apply.

Uno a uno, verificando entre medias. Si drain se bloquea, es un PodDisruptionBudget haciendo su trabajo: postgres-reservas no puede quedarse sin réplicas. Investiga con kubectl get pdb -A antes de forzar nada.

En 05-06 hicimos copias de los datos de las aplicaciones con Velero. Esto es otra cosa: es la copia de la definición del clúster. Todos los Deployments, Secrets, ConfigMaps, RBAC, CRDs... todo vive en etcd.

Sin copia de etcd, un fallo del disco del nodo de control te obliga a recrear el clúster desde cero y volver a aplicar todos los manifiestos. Con GitOps (10-05) eso sería recuperable, pero perderías todo lo que no esté en Git.

Esa misma orden en /etc/cron.d/respaldo-etcd, a las 03:15 diarias y encadenada con un find /var/respaldos -name 'etcd-*.db' -mtime +14 -delete, cubre la automatización con retención de dos semanas.

Tres cosas imprescindibles: copia también /etc/kubernetes/pki/ (el snapshot sin la CA es inútil), sácalas del nodo (una copia en el disco que se va a estropear no es una copia) y cífralas, porque contienen todos los Secrets de rutas-norte-pro, incluidas las credenciales de postgres-reservas y las de la pasarela de pagos: recuerda de 03-02 que los Secrets están en base64, no cifrados.

Procedimiento de emergencia, para cuando el plano de control es irrecuperable:

Puntos críticos:

• En un clúster HA, hay que restaurar en los tres nodos de control, con el snapshot idéntico y cada uno con su --name y sus URL. Si los datos difieren, etcd no formará quórum.
• El estado vuelve al momento de la copia. Todo lo creado después se pierde.
• Los pods que estaban corriendo siguen corriendo (el kubelet no se ha enterado), pero pueden aparecer objetos "fantasma": pods que existen en el nodo pero no en etcd, o al revés. Después de restaurar, revisa kubectl get pods -A contra crictl ps en cada nodo.

Ensaya la restauración. Una copia de seguridad que nunca se ha restaurado no es una copia de seguridad: es un fichero. Hazlo en el laboratorio, cronométrate, y escribe el procedimiento en un runbook (11-06).

Cuando algo sale mal y quieres volver a empezar, o retirar un nodo:

reset es honesto sobre lo que no limpia. Hay que rematarlo a mano:

Si te saltas los pasos 3, 4 y 5, el siguiente kubeadm init o join en esa máquina puede parecer que funciona y luego dar fallos de red inexplicables: reglas viejas de iptables enrutando a IP de pods que ya no existen. Es una de las causas más frecuentes de «reinstalé y sigue fallando».

1. SystemdCgroup = false en containerd. Es el error número uno. El clúster arranca, todo parece bien, y días después los pods se reinician bajo presión de memoria sin explicación. Verifica siempre con grep SystemdCgroup /etc/containerd/config.toml y reinicia containerd después de cambiarlo.

2. Olvidar swapoff -a en /etc/fstab. Lo desactivas, funciona, reinicias la máquina un mes después y el kubelet no arranca. Comenta la línea en /etc/fstab siempre.

3. podSubnet que se solapa con la red física. Si tu laboratorio usa 10.10.0.0/24 y declaras podSubnet: 10.0.0.0/8, el enrutado se rompe de formas que parecen magia negra. Elige rangos que no colisionen con nada: ni con la red de nodos, ni con serviceSubnet, ni con la red corporativa.

4. El rango del CNI distinto de podSubnet. Declaras 10.244.0.0/16 en kubeadm e instalas Calico con su valor por defecto 192.168.0.0/16. Los pods obtienen IP del rango del CNI, pero el controller-manager asigna bloques del otro. Deben coincidir.

5. No declarar controlPlaneEndpoint desde el principio. Añadir alta disponibilidad después obliga a regenerar certificados en todo el clúster. Declara un nombre DNS desde el primer día, aunque apunte a una sola IP.

6. Certificados caducados al año. Real y muy común. Alerta en el calendario, o mejor, en la monitorización.

7. Saltar dos versiones menores, o actualizar los nodos antes que el plano de control. kubeadm upgrade apply v1.32.0 desde 1.30 es rechazado; y un kubelet 1.31 contra un apiserver 1.30 está fuera de la política de desfase. Una menor cada vez, plano de control primero.

8. kubectl drain bloqueado y forzarlo con --force. Lo que te bloquea suele ser un PDB (09-05) protegiendo postgres-reservas o redis-cache. Forzarlo puede provocar pérdida de datos. Investiga antes con kubectl get pdb -A.

9. Copias de etcd sin /etc/kubernetes/pki. El snapshot sin la CA no te devuelve un clúster funcional. Copia ambos, juntos, cifrados y fuera del nodo.

10. kubeadm reset sin limpiar iptables y CNI. Restos que provocan fallos de red en la reinstalación. Ejecuta la limpieza completa del apartado 14.

11. No fijar apt-mark hold. Un apt upgrade rutinario que actualice el kubelet en producción es un incidente esperando a ocurrir.

Escribe un script preparar-nodo.sh idempotente (que se pueda ejecutar dos veces sin romper nada) que deje una máquina Ubuntu lista para kubeadm join: swap desactivado de forma permanente, módulos y sysctl, containerd con SystemdCgroup=true verificado, y kubeadm/kubelet/kubectl 1.30.4 fijados. El script debe fallar con un mensaje claro si alguna verificación no pasa.

Escribe el fichero de configuración de kubeadm para el clúster rutas-norte-lab con estos requisitos: tres nodos de control detrás de api-k8s.rutasnorte.example (IP virtual 10.10.0.10), podSubnet 172.16.0.0/16, etcd apilado, auditoría activada, y el kubelet reservando 500m de CPU y 512Mi de memoria para el sistema. Explica por qué elegiste 172.16.0.0/16 y qué comprobarías antes.

Redacta el procedimiento completo, en orden y con las órdenes exactas, para actualizar el clúster de 1.30.4 a 1.31.1 con un nodo de control y dos de trabajo, incluyendo la copia de seguridad previa. Añade el criterio de "punto sin retorno" y qué harías si el apiserver no arranca tras upgrade apply.

Solución 1

Claves de idempotencia: el sed que no recomenta líneas ya comentadas, el [[ -s ]] antes de regenerar la configuración de containerd, y el unhold antes de instalar.

Solución 2

Por qué 172.16.0.0/16: es rango privado (RFC 1918) que no colisiona con la red del laboratorio (10.10.0.0/24) ni con serviceSubnet (10.96.0.0/12), y da 65 536 IP, suficientes. Comprobaciones previas: que 172.16/16 no se use en la red corporativa ni en la VPN, y configurar el CNI con ese mismo CIDR.

Solución 3

Punto sin retorno: kubeadm upgrade apply, porque migra el esquema de etcd. Antes, basta con revertir los paquetes; después, la vuelta atrás exige restaurar el snapshot.

Si el apiserver no arranca: sudo crictl ps -a | grep apiserver, sudo crictl logs <id> y journalctl -u kubelet -f. Causas típicas: una bandera nueva no soportada o un certificado mal generado. Si no se resuelve en la ventana de mantenimiento, restaurar pre-131.db y pki-pre-131.tgz con el procedimiento del apartado 13.2 y revertir los paquetes a 1.30.4.

Ya sabes montar un clúster de Kubernetes desde cero sobre máquinas propias. Lo esencial:

• kubeadm arranca un clúster conforme; no aprovisiona máquinas ni instala el CNI. Esa frontera explica el 90 % de las dudas iniciales, incluido el nodo NotReady.
• La preparación de las máquinas —swap, overlay y br_netfilter, ip_forward, puertos, y sobre todo SystemdCgroup = true en containerd— es donde nacen los fallos más difíciles de diagnosticar.
• Un fichero de configuración versionado (ClusterConfiguration, InitConfiguration, KubeletConfiguration) es infinitamente mejor que una ristra de banderas; controlPlaneEndpoint y certSANs bien puestos desde el primer día te ahorran regenerar certificados más tarde.
• kubeadm deja en el nodo pods estáticos en /etc/kubernetes/manifests, los certificados en /etc/kubernetes/pki y los kubeconfig: la arquitectura de 01-02, hecha ficheros.
• Los nodos se unen con token y hash de la CA; el token caduca a las 24 horas y se regenera con kubeadm token create --print-join-command. La alta disponibilidad exige un punto de entrada estable y un número impar de miembros de etcd, normalmente 3 apilados.
• Los certificados caducan al año, las actualizaciones van una versión menor cada vez con el plano de control antes que los nodos de trabajo, y las copias de etcd (snapshot + pki, cifradas, fuera del nodo, con restauración ensayada) son la diferencia entre un mal día y el fin de la empresa.

Y la advertencia que hay que repetir: operar esto en producción exige un equipo dedicado con guardia. En 10-06 veremos qué te ahorra un clúster gestionado y a qué precio.

Pero antes tenemos que resolver el problema con el que empezó este módulo. Ya sabemos crear clústeres, locales y propios; lo que sigue sin resolverse son los 120 ficheros YAML duplicados de Rutas Norte. En la siguiente lección, Helm, conoceremos el gestor de paquetes de Kubernetes: charts, valores, plantillas y releases. Es la herramienta con la que ya instalamos cert-manager (04-05) y kube-prometheus-stack (07-03) sin explicarla; toca entenderla de verdad y usarla para empaquetar la plataforma Rutas Norte en un único chart con un fichero de valores por entorno.