En el capítulo 02 ejecutamos kubeadm init y vimos el clúster subir. Funcionó, pero ¿qué hizo exactamente ese comando?

Esa es la diferencia entre “tener un clúster” y “operar un clúster”. Cuando algo se rompe a las 3 de la mañana, necesitas saber dónde están los certificados, qué pods son estáticos, cómo renovar un token y qué sucede en el upgrade.

Sello del curso: probado en Kubernetes 1.35 y Ubuntu 24.04. IPs ficticios (192.168.56.x).

Qué crea kubeadm

Al ejecutar kubeadm init, genera:

Ruta	Contenido
/etc/kubernetes/manifests/	static pods del control plane
/etc/kubernetes/pki/	CA, certificados del apiserver, etcd, service account
/etc/kubernetes/*.conf	kubeconfigs (admin, controller-manager, scheduler)
/var/lib/kubelet/	configuración y datos del kubelet
/etc/cni/net.d/	configuración de la CNI (después)

El control plane no es un “servicio systemd” tradicional. Se ejecuta como static pods, que el kubelet inicia a partir de los manifiestos en /etc/kubernetes/manifests. Si editas el YAML del apiserver allí, el kubelet recrea el pod automáticamente.

ls -l /etc/kubernetes/manifests/
sudo crictl pods | head
kubectl -n kube-system get pods -o wide

Verás kube-apiserver, kube-controller-manager, kube-scheduler y etcd como pods con nombres que terminan en el hostname del nodo.

Certificados: qué expira y cuándo

El clúster vive de TLS. kubeadm crea una PKI local:

sudo ls -l /etc/kubernetes/pki/
sudo kubeadm certs check-expiration

La salida muestra la validez de cada certificado. Por defecto, muchos expiran en 1 año. Si el apiserver deja de responder con error de TLS, verifica esto primero.

Renovación manual:

sudo kubeadm certs renew all
sudo systemctl restart kubelet

En clústeres de larga duración, automatiza la renovación o inclúyelo en el runbook de mantenimiento. Un certificado vencido no es un “bug de Kubernetes”; es operación.

Tokens de join

kubeadm init imprime un comando de join con token y hash. El token expira (24h por defecto). Para generar otro:

sudo kubeadm token list
sudo kubeadm token create --print-join-command

El hash es el sha256 de la CA pública. Si el token expiró, el comando anterior lo resuelve. Si la CA cambió (clúster recreado), el hash antiguo no sirve.

Para agregar un control plane (HA), el comando es diferente:

sudo kubeadm join 192.168.56.10:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash> \
  --control-plane --certificate-key <key>

La --certificate-key se genera con kubeadm init phase upload-certs --upload-certs. Vamos a usar esto en el capítulo 05.

El kubeconfig

El archivo ~/.kube/config apunta al apiserver y carga el certificado de cliente. Si pierdes acceso:

sudo cp /etc/kubernetes/admin.conf ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
kubectl get nodes

Nunca copies ese archivo a lugares inseguros: otorga acceso administrativo al clúster.

Upgrade del control plane

El upgrade es una operación de mantenimiento, no un apt upgrade cualquiera.

sudo kubeadm upgrade plan
sudo apt-mark unhold kubeadm
sudo apt install -y kubeadm=1.35.x-1.1
sudo apt-mark hold kubeadm
sudo kubeadm upgrade apply v1.35.x

Después, actualiza kubelet y kubectl en el nodo y reinicia el kubelet. En HA, un master a la vez; nunca todos juntos.

En los workers, el flujo es:

kubectl drain <worker> --ignore-daemonsets --delete-emptydir-data
sudo apt-mark unhold kubeadm kubelet
sudo apt install -y kubeadm=1.35.x-1.1 kubelet=1.35.x-1.1 kubectl=1.35.x-1.1
sudo kubeadm upgrade node
sudo systemctl restart kubelet
kubectl uncordon <worker>

La regla es: un nodo a la vez, validando kubectl get nodes y las cargas antes de continuar.

Reset: cuándo rehacer

Si el laboratorio se rompe sin vuelta atrás:

sudo kubeadm reset -f
sudo rm -rf /etc/cni/net.d /var/lib/cni /var/lib/kubelet
sudo systemctl restart containerd kubelet

En HA, esto es más delicado: elimina el nodo del clúster, limpia etcd y recréalo. Haz una copia de seguridad antes.

Laboratorio del capítulo

1. Lista los static pods:

kubectl -n kube-system get pods -o wide
sudo crictl pods | grep -E 'kube-apiserver|etcd|scheduler'

2. Verifica la validez de los certificados:

sudo kubeadm certs check-expiration

3. Genera un nuevo token de join:

sudo kubeadm token create --print-join-command

4. Ve el kubeconfig y el endpoint:

kubectl config view --minify
kubectl cluster-info

5. (Opcional) En un clúster desechable, prueba kubeadm upgrade plan.

Errores comunes

Síntoma	Causa probable
x509: certificate has expired	certificado caducado; kubeadm certs renew
bootstrap token expired	token de join expiró; genera otro
etcdserver: request timed out	disco lento o quórum perdido
apiserver no arranca después de editar el manifiesto	YAML inválido en /etc/kubernetes/manifests
el upgrade falla a la mitad	versión de kubelet/kubeadm inconsistente
el nodo no vuelve después del upgrade	kubelet parado o CNI sin config

Checklist

• [ ] Sé dónde están los static pods del control plane.
• [ ] Sé verificar la validez de los certificados.
• [ ] Sé generar un token de join nuevo.
• [ ] Entendí el papel del kubeconfig.
• [ ] Conozco el flujo de upgrade de un nodo.
• [ ] Sé cuándo (y cómo) hacer reset.

Glosario

• PKI: infraestructura de claves y certificados.
• static pod: pod gestionado directamente por el kubelet mediante manifiesto.
• bootstrap token: token temporal para el join.
• certificate-key: clave usada para distribuir certificados a nuevos control planes.
• drain/uncordon: evacuar y liberar un nodo para mantenimiento.

Próximo

Ahora que entiendes lo que kubeadm creó, vamos a poner el control plane en HA: 3 masters, endpoint estable y etcd con quórum.

Próximo: Curso Kubernetes 05 — HA: 3 masters, VIP y etcd