Saltar a contenido

Fase 6 — CAPN (opcional)

Objetivo

Provisionar workload clusters kubeadm sobre instancias Incus vía Cluster API y CAPN.

Qué aprendes

CAPI (Cluster API) declara clusters como recursos Kubernetes; CAPN (Cluster API Provider for Incus) traduce LXCMachine en instancias Incus — clusters efímeros sin tocar el management K3s (distribución ligera de Kubernetes).

Aprende esta fase

En simple: Cluster API es una impresora 3D de clústeres: en vez de armar cada clúster a mano, escribes una descripción y el sistema lo fabrica. CAPN es el "accesorio" que usa Incus como fábrica: cada nodo del clúster nuevo es una instancia de Incus.

Conceptos clave

  • Management cluster y workload cluster: el primero gestiona; el segundo es el que se crea y se usa.
  • Provider (proveedor): el plugin que sabe crear máquinas en una plataforma concreta (aquí, Incus).
  • Recursos declarativos: un clúster se describe como un objeto de Kubernetes (por ejemplo LXCMachine).
  • Clústeres efímeros: se crean para una prueba y se destruyen después.

Reto práctico (seguro): genera la descripción de un clúster y léela, sin aplicarla. Primero exporta las variables que aparecen en la sección «Ejecutar» de esta fase; después:

clusterctl generate cluster demo -i incus \
  --kubernetes-version v1.36.2 \
  --control-plane-machine-count 1 \
  --worker-machine-count 2 > /tmp/demo.yaml
less /tmp/demo.yaml     # solo lectura: no ejecutes kubectl apply
¿Por qué crear clústeres desde un manifiesto y no a mano?

Se repiten igual cada vez, quedan en Git y se pueden destruir y recrear sin esfuerzo.

¿Qué diferencia hay entre el management cluster y un workload cluster?

El management cluster crea y vigila a los demás; los workload clusters ejecutan las aplicaciones.

¿Dudas? Usa el botón Aprende con IA junto a cada título, o la página Aprende.

Stack de esta fase

sequenceDiagram
  participant Op as Operador
  participant K3s as K3s_management
  participant CAPI as Cluster_API
  participant CAPN as CAPN_controller
  participant Incus as Incus_API
  participant WL as Workload_cluster
  Op->>K3s: clusterctl_init
  Op->>K3s: apply_demo_yaml
  CAPI->>CAPN: reconcile_LXCMachine
  CAPN->>Incus: crear_LXC
  Incus->>WL: kubeadm_listo
  Op->>WL: kubectl_workload
  • Cluster API — API (Application Programming Interface) declarativa; Fase 6.
  • CAPN — Provider Incus; Fase 6.
  • clusterctl — Bootstrap CAPI en el management cluster.
  • Incus — Runtime de instancias; Fase 2.
  • Sealed Secrets — Credenciales Incus cifradas en git.

Profundización: CAPN · Secretos

Antes de empezar

La Fase 5 — vCluster es opcional: no hace falta para esta fase.

Balanceador del control plane

Cada clúster de CAPN crea su propio balanceador para el API (LOAD_BALANCER='lxc: {}', un contenedor dentro de Incus). Los balanceadores de red de Incus solo existen con OVN, que el HomeLab no usa: ver Balanceo de carga y OVN.

Ejecutar

Instalar clusterctl e init CAPN

curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.10.10/clusterctl-linux-amd64 -o clusterctl
chmod +x clusterctl && sudo mv clusterctl /usr/local/bin/
mkdir -p ~/.cluster-api
curl -o ~/.cluster-api/clusterctl.yaml https://capn.linuxcontainers.org/static/v0.1/clusterctl.yaml
clusterctl init -i incus

Generar y aplicar cluster demo

Ver comandos completos en CAPN — profundización.

kubectl apply -f gitops/argocd/apps/capn-demo.yaml
# Sync manual en ArgoCD

Opciones

Decisión Default HomeLab
Sync ArgoCD Manual (efímero, evita borrados accidentales)
Target workers @arm64-nodes (deborah) / CP @x86-nodes
Análisis de trade-offs
Sync manual
Clusters efímeros no se prunean solos
Apply + Sync en UI cada vez
Workers en @arm64-nodes
Aprovecha 31 GB de deborah
Menos margen si deborah ya es CP K3s
CP en @x86-nodes
Separación CP workload / management
Más RAM en nodos x86 limitados
CAPN vs vCluster
VMs/Incus reales; kubeadm completo
Mucha más RAM que vCluster en pods

Verificar

kubectl get clusters
kubectl get machines

Si falla

Síntoma Revisar
Machine stuck Secret Incus, IP Incus en lxc-secret
Image pull images.linuxcontainers.org

Siguiente

→ Resumen del HomeLab · Stack tecnológico