Implementación — guía paso a paso¶

Esta sección es el recorrido principal del HomeLab: desde nodos bare-metal hasta GitOps completo. Cada fase es ejecutable, verificable y enlaza al stack tecnológico y a páginas de profundización.

Cómo usar esta guía

Sigue las fases en orden la primera vez. En despliegues posteriores puedes saltar a la fase que necesites si los prerrequisitos ya están cumplidos. Donde haya más de una alternativa, cada fase incluye un breve Análisis de trade-offs (ventaja vs coste/riesgo).

Timeline de fases¶

flowchart LR
  F0[Fase_0_Preparacion] --> F1[Fase_1_Red]
  F1 --> F2[Fase_2_Incus]
  F2 --> F3[Fase_3_K3s]
  F3 --> F4[Fase_4_GitOps]
  F4 --> F5[Fase_5_vCluster]
  F4 --> F6[Fase_6_CAPN]

0

Preparación Completada

Repo, Ansible, inventario, discovery opcional.

playbook-discovery.yml

1

Red Completada

IP fija en br0 en los 3 nodos.

playbook-set-static-ip.yml

2

Incus Completada

Clúster Incus HA + cluster groups + UI.

playbook-bootstrap.yml + playbook-incus-cluster.yml

3

K3s Completada

Management cluster + ArgoCD controller.

playbook-k3s.yml

4

GitOps Completada

MetalLB, Gateway API, storage, Dex, waves.

Argo CD + gitops

5

vCluster Opcional

Clústeres virtuales + kubeconfig web.

Application manual

6

CAPN Opcional

Workload clusters sobre Incus.

clusterctl + Application manual

Cierre de la guía: Resumen del HomeLab — checklist global, URLs, /etc/hosts, nodos y verificación.

Dos repos, dos responsabilidades¶

Repo	Qué instala	Herramienta
`homelab`	Red SO, Incus, K3s, kube-vip, controller ArgoCD	Ansible
`gitops`	MetalLB, Gateway API, storage, vCluster, CAPN, …	Argo CD

Stack tecnológico¶

Diagrama por capas, lista de productos con enlaces oficiales y rol en el HomeLab:

Ver stack tecnológico completo →

Vista arquitectónica complementaria: Arquitectura C4.

Mapa de decisiones (forks)¶

Decisión	Opción A (default HomeLab)	Opción B
API K3s estable	IP fija deborah (`192.168.20.5`)	kube-vip (`kube_vip.enabled: true` en `k3s_install.yml`)
Instalar K3s	`playbook-k3s.yml`	curl manual (referencia)
CNI	Flannel embebido (`vxlan`)	Canal, Calico, Cilium
Secretos OAuth	1Password SDK — cuenta personal, bóveda `HomeLab`	Cuenta empresa u otra bóveda vía env vars
vCluster / CAPN	Comentadas en `homelab-root`	Descomentar en `root-appset.yaml` cuando estés listo
Storage HA	Longhorn en invincible+deborah	Solo OpenEBS

Análisis de trade-offs

IP fija vs kube-vip

IP fija: cero componentes extra

kube-vip: VIP 192.168.20.4 estable si el CP cambia de nodo

kube-vip

API en IP dedicada; agents no dependen de hostname

Un daemon más; no sustituye MetalLB

Ansible vs curl K3s

Idempotente, flags en group_vars

Manual solo para depuración puntual

Flannel elegida

Embebido en K3s; bajo consumo

Sin NetworkPolicy nativa

Canal / Calico / Cilium

Políticas de red (Canal/Calico) o eBPF (Cilium)

--flannel-backend=none; más RAM/CPU; elegir antes del bootstrap

1Password SDK

Secretos fuera de git; DesktopAuth local

Requiere app 1Password desbloqueada en la estación

env vars / kubectl patch

Sin 1Password

Secretos en shell/historial; no idempotente

Sync manual vCluster/CAPN

Evita borrados accidentales de clusters efímeros

Paso extra en Argo CD UI

Longhorn

Replicación x86↔arm64

Solo 2 nodos; más pods que OpenEBS

Solo OpenEBS

LocalPV en 3 nodos; simple

Sin HA entre nodos

Detalle CNI (Container Network Interface): Fase 3 — K3s · playbook-options.

Detalle de flags K3s (distribución ligera de Kubernetes): Opciones del playbook.

Catálogo de roles Ansible: Ansible — roles.

Empieza aquí¶

→ Fase 0 — Preparación

Apéndice fuera del flujo feliz: Desinstalar K3s.