Implementation — Step-by-Step Guide¶

This section is the main journey of the HomeLab: from bare-metal nodes to full GitOps. Each phase is executable, verifiable, and links to the tech stack and pages for deeper dives.

How to use this guide

Follow the phases in order the first time. In subsequent deployments, you can skip to the phase you need if the prerequisites are already met. Where there are multiple options, each phase includes a brief Trade-offs Analysis (benefit vs cost/risk).

Phase Timeline¶

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

Preparation Completed

Repo, Ansible, inventory, optional discovery.

playbook-discovery.yml

1

Network Completed

Fixed IP on br0 on the 3 nodes.

playbook-set-static-ip.yml

2

Incus Completed

HA Incus cluster + cluster groups + UI.

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

3

K3s Completed

Management cluster + Argo CD controller.

playbook-k3s.yml

4

GitOps Completed

MetalLB, Gateway API, storage, Dex, waves.

Argo CD + gitops

5

vCluster Optional

Virtual clusters + web kubeconfig.

Application manual

6

CAPN Optional

Workload clusters on Incus.

clusterctl + Application manual

End of guide: HomeLab Summary — global checklist, URLs, /etc/hosts, nodes, and verification.

Two Repos, Two Responsibilities¶

Repo	What it Installs	Tool
`homelab`	OS network, Incus, K3s, kube-vip, Argo CD controller	Ansible
`gitops`	MetalLB, Gateway API, storage, vCluster, CAPN, …	Argo CD

Tech Stack¶

Layered diagram, list of products with official links and role in the HomeLab:

See full tech stack →

Complementary architectural view: C4 Architecture.

Decision Map (forks)¶

Decision	Option A (default HomeLab)	Option B
Stable K3s API	Name `k3s.homelab.local` to the control plane (`deborah`, `192.168.20.5`)	kube-vip (`kube_vip.enabled: true` on `k3s_install.yml`)
Install K3s	`playbook-k3s.yml`	Manual curl (reference)
CNI	Calico (`k3s_cni: calico`)	Embedded Flannel (`vxlan`), Canal, Cilium
OAuth Secrets	1Password SDK — personal account, vault `HomeLab`	Corporate account or other vault via env vars
vCluster / CAPN	Commented in `homelab-root`	Uncomment in `root-appset.yaml` when ready
HA Storage	Longhorn on invincible+deborah	Only OpenEBS

Trade-off Analysis

Fixed IP vs kube-vip

Fixed IP: no extra components

kube-vip: stable VIP 192.168.20.4 if CP changes node

kube-vip

API on dedicated IP; agents do not depend on hostname

One more daemon; does not replace MetalLB

Ansible vs curl K3s

Idempotent, flags in group_vars

Manual only for occasional debugging

Flannel

Embedded in K3s; low consumption

No native NetworkPolicy

Calico selected · Canal / Cilium

Network policies (Canal/Calico) or eBPF (Cilium)

--flannel-backend=none; more RAM/CPU; choose before bootstrap

1Password SDK

Secrets out of Git; local DesktopAuth

Requires unlocked 1Password app on the station

env vars / kubectl patch

No 1Password

Secrets in shell/history; not idempotent

Manual sync vCluster/CAPN

Avoid accidental deletion of ephemeral clusters

Extra step in Argo CD UI

Longhorn

Replication x86↔arm64

Designed for 2 nodes; more pods than OpenEBS

Only OpenEBS

LocalPV on 3 nodes; simple

No HA between nodes

Details CNI (Container Network Interface): Phase 3 — K3s · playbook-options.

Details K3s flags (lightweight Kubernetes distribution): Playbook options.

Ansible role catalog: Ansible — roles.

After the phases¶

With the platform running, add the local AI assistant (Ollama on several nodes behind a router, with Open WebUI and Open Terminal), the centralized logs with weekly reports with AI, and the security layers (host firewall, service tokens, stage-based NetworkPolicy). They are in Operation: Local AI assistant, Logs and Authentication model. If the control plane ever needed to change nodes, the procedure is in Move the control plane.

Start here¶

→ Phase 0 — Preparation

Appendix outside the normal path: Uninstall K3s.