Homelab Kubernetes Pipeline

This repo bootstraps a hybrid kubeadm cluster and then hands app delivery to Argo CD.

Flow

1. bootstrap/cluster

   • creates the kubeadm control plane on the Debian amd64 node
   • joins worker nodes such as Raspberry Pi arm64 nodes
   • configures Calico-compatible pod CIDR
   • configures containerd to pull from the in-cluster NodePort registry
   • creates retained host directories under /var/openebs/local

2. bootstrap/platform

   • installs a minimal Calico deployment through the Tigera operator
   • installs OpenEBS
   • creates openebs-hostpath-retain
   • installs Argo CD
   • registers the private GitOps repo without storing the SSH private key in Terraform state

3. bootstrap/apps

   • registers Argo CD Applications from the applications map
   • default apps are container-registry, gitea, and website-production

Adding Nodes

Add entries to bootstrap/cluster/variables.tf or a .tfvars file:

worker_nodes = {
  raspberrypi = {
    host         = "192.168.100.89"
    user         = "jv"
    node_name    = "raspberry"
    ssh_key_path = "/home/jv/.ssh/id_ed25519"
  }
}

Stateful apps currently pin retained local PVs to the debian node. Move or duplicate those PV manifests when you want storage on another node.

The website NodePort is reachable from the OCI jump box through the Raspberry Pi Tailscale interface. bootstrap/cluster installs a persistent homelab-tailscale-nodeport.service on the configured worker to restore the route, rp_filter settings, and iptables rules after reboot. Override the defaults through tailscale_nodeport_access when the jump-box IP, Pi Tailscale IP, pod CIDR, or NodePort changes:

tailscale_nodeport_access = {
  enabled           = true
  worker_key        = "raspberrypi"
  peer_ip           = "100.118.255.19"
  node_tailscale_ip = "100.77.80.72"
  pod_cidr          = "10.244.0.0/16"
  node_port         = 30080
  target_port       = 80
}

For ./lab.sh nuke, set WORKER_SSH_TARGETS to a space-separated list of remote SSH targets when more worker nodes exist. Set it to an empty string for a single-node rebuild.

Adding Platform Tools

Add Helm releases through bootstrap/platform's extra_helm_releases map.

Adding Apps

Add Kubernetes manifests under apps/<name> and register them in bootstrap/apps's applications map. Argo CD will own sync, pruning, and self-healing for the app.

Storage

OpenEBS provides the platform storage provisioner. Stateful homelab apps use retained local PV paths such as /var/openebs/local/gitea and /var/openebs/local/registry; these paths are intentionally outside kubeadm reset paths so data can survive cluster destroy/create cycles. Those critical volumes are declared explicitly as retained local PVs so a rebuilt cluster binds back to the same host paths instead of creating fresh directories.

Keep the .terraform.lock.hcl files committed. They pin provider selections and make bootstrap behavior reproducible across nodes and rebuilds.