Saltar a contenido

Fase 3 — K3s

Objetivo

Management cluster K3s (distribución ligera de Kubernetes) en 3 nodos (CP en deborah, workers en invincible y oliver), con controller Argo CD listo para GitOps.

Qué aprendes

K3s como Kubernetes ligero bare-metal: server/agent, CNI (Container Network Interface) configurable (Flannel por defecto), deshabilitar Traefik/ServiceLB para controlar el Gateway y LoadBalancer vía GitOps después.

Aprende esta fase

En simple: Kubernetes es el gerente de un restaurante: tú le dices "quiero siempre tres cocineros trabajando" y él se encarga de reemplazar al que falte. El control plane es la gerencia (decide) y los workers son la cocina (trabajan). K3s es una versión de Kubernetes pensada para equipos pequeños.

Conceptos clave

  • Nodo: un equipo del clúster; puede ser control plane (decide) o worker (ejecuta).
  • Pod: la unidad mínima de ejecución: uno o más contenedores que viven juntos.
  • Deployment: declara cuántas copias de un pod deben existir y las mantiene.
  • CNI (Container Network Interface): el componente que da red a los pods; aquí, Calico.
  • kubectl y kubeconfig: la herramienta de línea de comandos y el archivo con los datos de acceso al clúster.

Reto práctico (seguro): crea un deployment de prueba, borra uno de sus pods y mira cómo Kubernetes lo repone.

kubectl get nodes -o wide
kubectl create deployment demo --image=nginx --replicas=2
kubectl get pods -l app=demo
kubectl delete pod -l app=demo --wait=false
kubectl get pods -l app=demo        # aparecen pods nuevos
kubectl delete deployment demo      # limpieza
¿Qué diferencia hay entre un pod y un deployment?

El pod es una copia en ejecución; el deployment es la regla que dice cuántas copias deben existir y las recrea si desaparecen.

¿Qué pasa si se cae un worker?

Kubernetes detecta que los pods dejaron de responder y los vuelve a crear en otros nodos sanos.

¿Por qué hace falta un CNI?

Porque Kubernetes no trae red de pods propia en este montaje: el CNI les da direcciones y los comunica entre nodos.

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

Stack de esta fase

flowchart TB
  subgraph cp [Control_plane]
    DEB[deborah_server]
    VIP[kube_vip_opcional]
  end
  subgraph workers [Workers]
    INV[invincible_agent]
    NOL[oliver_agent]
  end
  DEB --> API[API_6443]
  VIP -.-> API
  INV --> API
  NOL --> API
  DEB --> ArgoCD[ArgoCD_controller]

Profundización: Opciones del playbook · Catálogo roles Ansible · K3s manual (legacy)

Antes de empezar

  • Fases 0, 1 y 2 completadas.
  • Incus cluster healthy (opcional pero recomendado antes de CAPN).

Ejecutar

Las opciones del playbook se activan en group_vars/incus_cluster/k3s_install.yml, no por línea de comandos. Hoy vienen activadas ArgoCD (gitops_argocd), las etiquetas de nodos (node_labels) y el kubeconfig local (fetch_kubeconfig), con CNI (Container Network Interface) Calico. Revisa el archivo y corre:

cd ansible
ansible-playbook -i inventory.ini playbook-k3s.yml

No uses -e k3s_install.<opción>=…

Ansible lo ignora: k3s_install es un diccionario y una clave con puntos en -e no lo modifica (se instalaba el CNI por defecto sin avisar). Y pasar -e con JSON es peor: reemplaza el diccionario entero y se pierden core.version, cluster_cidr, etc. El playbook ahora falla en ambos casos. Para cambiar el CNI usa -e k3s_cni=canal (o edita el archivo); ver opciones del playbook.

Pasos curl en K3s — instalación manual. Usar solo si Ansible no está disponible; el camino soportado es el playbook.

Opciones

Si necesitas… En k3s_install.yml Hoy Doc
VIP estable del API kube_vip.enabled: true desactivado playbook-options
Etiquetas Longhorn/arch node_labels.enabled: true activado playbook-options
Kubeconfig local fetch_kubeconfig.enabled: true activado playbook-options
OS hardening os_hardening.enabled: true desactivado playbook-options
Decisión Opción A (default) Opción B
API K3s IP fija deborah 192.168.20.5 kube-vip 192.168.20.4
CNI Calico (configurado en este repo) Flannel vxlan (default de K3s), Canal o Cilium (k3s_install.core.cni)

CNI

CNI Variable Notas
Flannel (default de K3s) cni: flannel Embebido en K3s; flannel_backend: vxlan o host-gw
Canal cni: canal Flannel overlay + políticas Calico; rol k3s_cni
Calico cni: calico NetworkPolicy, BGP opcional; --flannel-backend=none
Cilium cni: cilium eBPF, Hubble; validar en ARM64 (deborah)

El CNI se elige en k3s_install.core.cni (hoy: calico), antes de instalar K3s: cambiarlo en un clúster ya instalado obliga a reinstalarlo.

# group_vars/incus_cluster/k3s_install.yml
k3s_install:
  core:
    cni: calico  # flannel | canal | calico | cilium

Detalle: playbook-options — CNI.

Análisis de trade-offs
Ansible (playbook-k3s.yml)
Flags en group_vars; rol k3s_cni
Requiere SSH y orden server → CNI → agents
curl manual
Escape hatch
Sin idempotencia; fácil olvidar --disable traefik
IP fija 192.168.20.5
Sin componentes extra
Si el CP migra, hay que reconfigurar agents
kube-vip 192.168.20.4
VIP estable del API
Daemon adicional; distinto de MetalLB
Flannel
Cero fricción; bajo consumo
Sin NetworkPolicy nativa
Canal
Políticas Calico sobre overlay
Proyecto legacy; dos stacks
Calico
NetworkPolicy madura; BGP en L2
Más pods/RAM; IP pools
Cilium
eBPF; políticas L3–L7; Hubble
Más CPU; kernel/BPF; probar en deborah
node_labels / fetch_kubeconfig
Longhorn y kubeconfig local listos
Play más largo; labels mal puestas afectan storage

Verificar

# En deborah o con kubeconfig
sudo k3s kubectl get nodes
# 3 nodos Ready
sudo k3s kubectl get pods -n argocd
# argocd-server Running (si gitops_argocd.enabled=true)

Espera pods argocd-server en Running antes de la Fase 4.

Si falla

Síntoma Revisar
Agent no une Token, K3S_URL, firewall :6443
Traefik residual --tags traefik o rol k3s_cleanup_traefik
CP caído tras reboot systemctl enable --now k3s en deborah

Siguiente

→ Fase 4 — GitOps