Kubernetes

kubernetes despliega clústeres kubeadm sobre VMs de Proxmox: un control plane y cualquier número de workers, construidos, ampliados, reducidos y actualizados por un stack de Horizon por clúster.

El stack termina con un clúster cuyos nodos están Ready y con la red funcionando. A partir de ahí, todo lo que corre dentro del clúster, incluido Calico, pertenece a FluxCD.

Este stack	FluxCD
Las VMs, CRI-O, kubelet, kubeadm y kubectl	Todo lo que hay dentro del clúster tras la entrega
kubeadm init, join, reset, upgrade apply	MetalLB, Traefik, cert-manager, metrics-server, Alloy, Keycloak, las aplicaciones
kube-vip (el endpoint de la API)	Calico desde la entrega: adopción, actualizaciones
La instalación inicial de Calico	El visto bueno para cada versión menor de Kubernetes

Nodos	1 control plane (2 vCPU, 6 GiB) y N workers (4 vCPU, 8 GiB) por defecto, discos de 50 GiB, sin disco de datos
Kubernetes	kubeadm 1.36, CRI-O de la misma versión menor
Endpoint de la API	Un registro DNS reservado por el stack; kube-vip mantiene su IP en el control plane
Red	Calico, IPIP, pods 172.16.0.0/16, servicios 10.96.0.0/12
Almacenamiento	Ninguno: sin StorageClass ni volúmenes
Copias de seguridad	Ninguna: nada en el clúster tiene estado

Sin estado

El clúster no tiene volúmenes: las bases de datos están en PostgreSQL y todo lo demás en Git. Un clúster roto sin arreglo se borra, se despliega uno nuevo y FluxCD vuelve a desplegar su contenido.

Fases

Fase	Qué hace
1	Las VMs del control plane y de los workers (linux/terraform)
2	CRI-O y los paquetes de Kubernetes en cada nodo
3	El clúster: kubeadm init, kube-vip y Calico (en serie)
4	La unión de los nodos (y su salida al quitarlos)
5	La verificación que lee FluxCD

El endpoint de la API

El endpoint es la dirección de la API de Kubernetes (puerto 6443). kubeadm init lo escribe en cada kubelet, cada kubeconfig, cada join y el certificado de la API, y no se puede cambiar después.

Por eso no puede ser el nombre de un control plane: al sustituirlo, la VM nueva tiene otro registro y el antiguo desaparece con ella. El endpoint es un registro DNS que pertenece al clúster:

• Se elige en el formulario un registro DNS libre del inventario de Horizon, que el stack reserva mientras exista.
• Ninguna máquina arranca con su MAC, así que el DHCP nunca entrega esa IP.
• kube-vip, un pod estático en cada control plane, añade la IP a la tarjeta de red del control plane activo y responde ARP por ella.

Así, un clúster usa un registro DNS por VM, más uno para el endpoint. Por ejemplo:

Registro	IP	Dónde vive
hori20, control plane	192.168.1.20	Su propia dirección, por DHCP
hori22, worker	192.168.1.22	Su propia dirección, por DHCP
hori23, endpoint reservado	192.168.1.23	También en hori20, añadida por kube-vip

aviso

Elige un registro de la red de los nodos, fuera del rango de MetalLB (192.168.1.170–.189) y que no sea de ninguna VM del clúster.

Desplegar un clúster

1. Crear el stack desde Kubernetes Cluster:
   • una ejecución de controlplane y las de worker necesarias (FluxCD espera tres), cada una con su registro DNS, llave SSH y servidor Proxmox;
   • control_plane_endpoint: un registro DNS libre más, para el endpoint. control_plane_vip se rellena con su IP;
   • cluster_name: el nombre que mostrará FluxCD (por defecto kubernetes);
   • kubernetes_version: Latest rellena el último parche de la 1.36.
2. Deploy. Las fases se ejecutan en orden y el stack queda desplegado cuando la verificación final pasa.

consejo

Si una VM falla en la fase 1 con un error SSH en el nodo de Proxmox (handshake failed: EOF o Permission denied al escribir un snippet), son dos Terraform compitiendo por el SSH del nodo: Retry failed jobs.

La entrega a FluxCD

Las salidas del stack son la entrega; no se envía nada a mano.

Salida	Contenido
kubeconfig	El admin.conf como JSON en una línea; es un kubeconfig válido, se guarda como fichero
endpoint	https://<endpoint>:6443
cluster_name	El nombre del clúster
calico_status, network_check, node_versions, ...	Las comprobaciones que confirman que el clúster está listo

Con el kubeconfig ya se puede instalar FluxCD.

precaución

El kubeconfig caduca al año. Hay que entregar el nuevo a FluxCD cada vez que cambie: tras una actualización, una sustitución del control plane o una renovación de certificados.

Nodos

Añadir un worker: añadir una ejecución de worker y guardar. Horizon crea la VM, la prepara, genera un token de join nuevo y el nodo se une. Los demás nodos no se tocan.

Quitar un worker: quitar la ejecución y guardar. En la VM saliente se drena el nodo, se elimina del clúster y se resetea; después Horizon destruye la VM.

• Nunca menos de dos workers: Traefik ejecuta dos réplicas en nodos diferentes y el drenado se bloquearía. Añade uno antes.
• Si se quitan varios en un guardado, salen de uno en uno.
• Un drenado fallido (diez minutos) mantiene el nodo acordonado y la ejecución intacta. Arreglar lo que no se puede desalojar y volver a guardar.

Sustituir un nodo: quitar la ejecución antigua y añadir la nueva en el mismo guardado. El nodo nuevo se crea y se une primero, y después sale el antiguo. Un control plane se sustituye igual: durante un momento hay dos, y kube-vip mueve la IP del endpoint al nuevo.

peligro

Al quitar una ejecución siempre se ejecuta su script de salida en la VM. Si la VM está muerta, hay que repararla en Proxmox hasta que responda por SSH. Si no tiene arreglo (o es el único control plane), el clúster se reconstruye.

Actualizaciones

Un nodo se construye una vez y nunca se actualiza: se sustituye. Solo la versión del clúster se mueve en el sitio, con la acción Upgrade control plane.

Para un parche (1.36.x → 1.36.y):

1. Acción Upgrade control plane con la nueva versión (Latest la ofrece). La API no está disponible un par de minutos; las cargas siguen funcionando.
2. Run again en el trabajo cluster, para que la salida kubeconfig lleve los certificados renovados. Entregarlo a FluxCD.
3. Subir kubernetes_version del stack al mismo parche. Los nodos existentes no cambian.
4. Sustituir el control plane y después los workers.

Una nueva versión menor requiere primero el visto bueno de FluxCD (que todos sus componentes la soporten) y una nueva versión de la plantilla que la acepte. Después, el mismo proceso. De una versión menor en una.

Certificados

Los certificados de kubeadm duran un año. Una actualización o una sustitución del control plane los renueva. Si un clúster no ve ninguna de las dos en un año, se ejecuta la acción Renew certificates y después Run again en cluster. El servicio de Nagios Kubernetes Certificates avisa 30 días antes.

Monitorización

Cada nodo tiene el Node Exporter y los checks base de Nagios, más kubelet y CRI-O. El control plane añade la API (/readyz) y la caducidad de los certificados. La telemetría del clúster la envía Alloy, desde FluxCD, a la máquina de monitorización.

Eliminar

Eliminar el stack quita los nodos de Nagios, resetea cada nodo (sin drenar), destruye las VMs y libera todos los registros DNS, incluido el del endpoint.

Documentación

• architecture.md: nodos, endpoint, red y responsabilidades.
• operations.md: despliegue, nodos, entrega a FluxCD y fallos.
• upgrades.md: actualizaciones, sustitución del control plane y certificados.