# 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:

```hcl
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.

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.