cloud-demo/README.md

Homelab Platform — Terraform + k3s + Flux on Forgejo

Learning project: provision VMs on the T630 with OpenTofu/Terraform, bootstrap a k3s cluster on them, and manage everything after that point through GitOps (Flux) synced from a Forgejo repo, with Forgejo Actions handling CI. The T630 keeps running its other self-hosted services throughout — this installs as ordinary KVM/libvirt packages next to them, sized deliberately small (3 VMs, 2 vCPU/2GB RAM each), not a hypervisor OS taking over the box.

Two setup paths, sharing everything past the cluster itself:

• docs/QUICKSTART.md — one manually-created VM (virt-install, no Terraform), fastest way to a real cluster to learn Flux/GitOps on.
• docs/SETUP.md — the full path, Terraform/OpenTofu provisioning all 3 VMs. Currently the harder, unfinished track (provider schema issues) — worth doing properly, but don't block on it.

The loop

OpenTofu (terraform/)
   -> provisions VMs on the T630 via KVM/libvirt (qemu:///system)
   -> cloud-init installs k3s (1 server + 2 agents)
   -> VMs live on an isolated private network (10.20.30.0/24), reachable
      only from the T630 itself

Forgejo repo (this repo)
   -> clusters/homelab/  = Flux config (what Flux itself watches)
   -> apps/               = workloads Flux deploys
   -> .forgejo/workflows/ = CI (terraform plan, image builds)

Flux (running in the cluster)
   -> watches this repo
   -> applies clusters/homelab/** and apps/** to k3s

Caddy (Podman, existing) is the public front door for boglabob.com, but only
for the low-stakes apps — the Dashboard and the k3s API server stay off it:
   git.boglabob.com     -> Forgejo (existing)
   podinfo.boglabob.com -> Traefik (k3s ingress) -> podinfo
   hello.boglabob.com   -> Traefik (k3s ingress) -> hello-app
   [Dashboard]           -> kubectl port-forward only, never a public hostname
   [k3s API, port 6443]  -> reachable only via the T630 (SSH tunnel or run
                             kubectl there directly), no proxy, no public port
   see docs/Caddyfile.example and docs/SETUP.md steps 12-13

Directory layout

• terraform/ — OpenTofu config that provisions the k3s VMs via KVM/libvirt directly on the T630 (no separate hypervisor OS, no VM template step — the cloud image is pulled straight from its URL).
• terraform/cloud-init/ — cloud-init templates that install k3s server/agent on first boot.
• clusters/homelab/ — Flux's own config for this cluster (populated by flux bootstrap, see docs/SETUP.md step 7).
• apps/podinfo/ — first GitOps app: a HelmRelease for the standard Flux demo app (podinfo). No CI needed — good for validating the Flux sync loop works.
• apps/hello-app/ — capstone app, and the public showcase piece at hello.boglabob.com: a one-page site (source + Dockerfile) built by Forgejo Actions, pushed to Forgejo's container registry, deployed via a Flux ImagePolicy/ImageUpdateAutomation so new pushes to main roll out automatically. The page itself shows the live commit SHA and deploy timestamp injected by CI, as proof the pipeline is really running rather than a static screenshot.
• apps/kubernetes-dashboard/ — the official Kubernetes Dashboard, with a cluster-admin token (apps/kubernetes-dashboard/rbac.yaml). No ingress — access is via kubectl port-forward only (see docs/SETUP.md step 12).
• .forgejo/workflows/ — CI: terraform validate/plan on PRs, build+push hello-app image on merge to main, via kaniko under a rootless Podman runner (no docker.sock, no sudo — see docs/SETUP.md step 9).
• docs/Caddyfile.example — the reverse-proxy blocks for podinfo/hello-app to add to your existing Caddy (Podman) config.

Prerequisites (see docs/SETUP.md for the full walkthrough)

• qemu-kvm/libvirt installed on the T630 (alongside its existing services)
• Forgejo instance reachable, with this repo pushed to it and Actions enabled
• tofu, kubectl, flux CLI — run on the T630 itself as the unprivileged k8s user (simplest, since the VMs' network is only reachable from there)

Milestones

1. KVM/libvirt installed on the T630, k8s user created
2. terraform apply — 3 VMs come up, k3s cluster forms
3. flux bootstrap against this Forgejo repo
4. Push apps/podinfo — watch Flux deploy it with no manual kubectl apply
5. Wire .forgejo/workflows/build-hello-app.yml — push a code change to apps/hello-app/src, watch CI build → registry → Flux auto-deploy
6. Stretch: sealed-secrets/SOPS, kube-prometheus-stack, cert-manager