Kubernetes

kubernetes desplega clústers kubeadm sobre VMs de Proxmox: un control plane i qualsevol nombre de workers, construïts, ampliats, reduïts i actualitzats per un stack d'Horizon per clúster.

L'stack acaba amb un clúster els nodes del qual estan Ready i amb la xarxa funcionant. A partir d'aquí, tot el que corre dins del clúster, inclòs Calico, pertany a FluxCD.

Aquest stack	FluxCD
Les VMs, CRI-O, kubelet, kubeadm i kubectl	Tot el que hi ha dins del clúster després del lliurament
kubeadm init, join, reset, upgrade apply	MetalLB, Traefik, cert-manager, metrics-server, Alloy, Keycloak, les aplicacions
kube-vip (l'endpoint de l'API)	Calico des del lliurament: adopció, actualitzacions
La instal·lació inicial de Calico	El vistiplau per a cada versió menor de Kubernetes

Nodes	1 control plane (2 vCPU, 6 GiB) i N workers (4 vCPU, 8 GiB) per defecte, discos de 50 GiB, sense disc de dades
Kubernetes	kubeadm 1.36, CRI-O de la mateixa versió menor
Endpoint de l'API	Un registre DNS reservat per l'stack; kube-vip en manté la IP al control plane
Xarxa	Calico, IPIP, pods 172.16.0.0/16, serveis 10.96.0.0/12
Emmagatzematge	Cap: sense StorageClass ni volums
Còpies de seguretat	Cap: res del clúster té estat

Sense estat

El clúster no té volums: les bases de dades són a PostgreSQL i tota la resta a Git. Un clúster trencat sense arranjament s'esborra, se'n desplega un de nou i FluxCD en torna a desplegar el contingut.

Fases

Fase	Què fa
1	Les VMs del control plane i dels workers (linux/terraform)
2	CRI-O i els paquets de Kubernetes a cada node
3	El clúster: kubeadm init, kube-vip i Calico (en sèrie)
4	La unió dels nodes (i la seva sortida en treure'ls)
5	La verificació que llegeix FluxCD

L'endpoint de l'API

L'endpoint és l'adreça de l'API de Kubernetes (port 6443). kubeadm init l'escriu a cada kubelet, cada kubeconfig, cada join i el certificat de l'API, i no es pot canviar després.

Per això no pot ser el nom d'un control plane: en substituir-lo, la VM nova té un altre registre i l'antic desapareix amb ella. L'endpoint és un registre DNS que pertany al clúster:

• Al formulari s'escull un registre DNS lliure de l'inventari d'Horizon, que l'stack reserva mentre existeixi.
• Cap màquina no arrenca amb la seva MAC, així que el DHCP no lliura mai aquella IP.
• kube-vip, un pod estàtic a cada control plane, afegeix la IP a la targeta de xarxa del control plane actiu i respon ARP per ella.

Així, un clúster fa servir un registre DNS per VM, més un per a l'endpoint. Per exemple:

Registre	IP	On viu
hori20, control plane	192.168.1.20	La seva pròpia adreça, per DHCP
hori22, worker	192.168.1.22	La seva pròpia adreça, per DHCP
hori23, endpoint reservat	192.168.1.23	També a hori20, afegida per kube-vip

warning

Escull un registre de la xarxa dels nodes, fora del rang de MetalLB (192.168.1.170–.189) i que no sigui de cap VM del clúster.

Desplegar un clúster

1. Crear l'stack des de Kubernetes Cluster:
   • una execució de controlplane i les de worker necessàries (FluxCD n'espera tres), cadascuna amb el seu registre DNS, clau SSH i servidor Proxmox;
   • control_plane_endpoint: un registre DNS lliure més, per a l'endpoint. control_plane_vip s'emplena amb la seva IP;
   • cluster_name: el nom que mostrarà FluxCD (per defecte kubernetes);
   • kubernetes_version: Latest emplena l'últim pegat de la 1.36.
2. Deploy. Les fases s'executen en ordre i l'stack queda desplegat quan la verificació final passa.

tip

Si una VM falla a la fase 1 amb un error SSH al node de Proxmox (handshake failed: EOF o Permission denied en escriure un snippet), són dos Terraform competint per l'SSH del node: Retry failed jobs.

El lliurament a FluxCD

Les sortides de l'stack són el lliurament; no s'envia res a mà.

Sortida	Contingut
kubeconfig	L'admin.conf com a JSON en una línia; és un kubeconfig vàlid, es desa com a fitxer
endpoint	https://<endpoint>:6443
cluster_name	El nom del clúster
calico_status, network_check, node_versions, ...	Les comprovacions que confirmen que el clúster està llest

Amb el kubeconfig ja es pot instal·lar FluxCD.

compte

El kubeconfig caduca a l'any. Cal lliurar el nou a FluxCD cada vegada que canviï: després d'una actualització, una substitució del control plane o una renovació de certificats.

Nodes

Afegir un worker: afegir una execució de worker i desar. Horizon crea la VM, la prepara, genera un token de join nou i el node s'uneix. La resta de nodes no es toquen.

Treure un worker: treure l'execució i desar. A la VM sortint es drena el node, s'elimina del clúster i es reseteja; després Horizon destrueix la VM.

• Mai menys de dos workers: Traefik executa dues rèpliques en nodes diferents i el drenatge es bloquejaria. Afegeix-ne un abans.
• Si se'n treuen diversos en un desament, surten d'un en un.
• Un drenatge fallit (deu minuts) manté el node acordonat i l'execució intacta. Arreglar el que no es pot desallotjar i tornar a desar.

Substituir un node: treure l'execució antiga i afegir-ne la nova al mateix desament. El node nou es crea i s'uneix primer, i després surt l'antic. Un control plane se substitueix igual: durant un moment n'hi ha dos, i kube-vip mou la IP de l'endpoint al nou.

perill

En treure una execució sempre s'executa el seu script de sortida a la VM. Si la VM és morta, cal reparar-la a Proxmox fins que respongui per SSH. Si no té arranjament (o és l'únic control plane), el clúster es reconstrueix.

Actualitzacions

Un node es construeix una vegada i no s'actualitza mai: se substitueix. Només la versió del clúster es mou al mateix lloc, amb l'acció Upgrade control plane.

Per a un pegat (1.36.x → 1.36.y):

1. Acció Upgrade control plane amb la nova versió (Latest l'ofereix). L'API no està disponible un parell de minuts; les càrregues continuen funcionant.
2. Run again al treball cluster, perquè la sortida kubeconfig porti els certificats renovats. Lliurar-lo a FluxCD.
3. Pujar kubernetes_version de l'stack al mateix pegat. Els nodes existents no canvien.
4. Substituir el control plane i després els workers.

Una nova versió menor requereix primer el vistiplau de FluxCD (que tots els seus components la suportin) i una nova versió de la plantilla que l'accepti. Després, el mateix procés. D'una versió menor en una.

Certificats

Els certificats de kubeadm duren un any. Una actualització o una substitució del control plane els renova. Si un clúster no veu cap de les dues en un any, s'executa l'acció Renew certificates i després Run again a cluster. El servei de Nagios Kubernetes Certificates avisa 30 dies abans.

Monitorització

Cada node té el Node Exporter i els checks base de Nagios, més kubelet i CRI-O. El control plane hi afegeix l'API (/readyz) i la caducitat dels certificats. La telemetria del clúster l'envia Alloy, des de FluxCD, a la màquina de monitorització.

Eliminar

Eliminar l'stack treu els nodes de Nagios, reseteja cada node (sense drenar), destrueix les VMs i allibera tots els registres DNS, inclòs el de l'endpoint.

Documentació

• architecture.md: nodes, endpoint, xarxa i responsabilitats.
• operations.md: desplegament, nodes, lliurament a FluxCD i fallades.
• upgrades.md: actualitzacions, substitució del control plane i certificats.