homelab/kubernetes

Kubernetes Cluster Bootstrap

This covers phase 2 of the full cluster setup. The two phases are:

1. Terraform (terraform/) — provisions the Talos VM on Proxmox and bootstraps the Kubernetes control plane. Outputs kubeconfig and talosconfig.
2. Flux CD (this file) — installs the GitOps controller into the running cluster and points it at this repository. From that point on, everything in kubernetes/ is reconciled automatically.

If you haven't run Terraform yet, start with terraform/README.md.

Prerequisites

• flux CLI installed
• AGE private key for SOPS decryption
• kubectl configured with the cluster kubeconfig from Terraform:

  cd ../terraform
  terraform output -json kubeconfig | jq -r '.homelab' > ~/.kube/config
  

Bootstrap Steps

1. Verify cluster access

kubectl get nodes

2. Bootstrap Flux CD

flux bootstrap github \
  --owner=berezovskyi-oleksandr \
  --repository=homelab \
  --branch=homelab-v2 \
  --path=./kubernetes \
  --token-auth \
  --personal

You will be prompted for a GitHub PAT, or set it beforehand:

export GITHUB_TOKEN=<your-pat>

Create a fine-grained PAT scoped to the homelab repository with:

• Contents: Read and write
• Metadata: Read-only (granted automatically)

This installs the Flux controllers and creates the flux-system namespace.

3. Create the SOPS AGE secret

Flux needs the AGE private key to decrypt SOPS-encrypted secrets.

kubectl create secret generic sops-age \
  --namespace=flux-system \
  --from-file=age.agekey=<path-to-age.key>

4. Verify Flux is reconciling

flux get kustomizations --watch

All kustomizations should eventually show as Ready.

5. Troubleshooting

Check Flux controller logs:

flux logs

Force a reconciliation:

flux reconcile source git flux-system
flux reconcile kustomization flux-system

Changing the Target Branch

To point Flux at a different branch (e.g. after merging homelab-v2 into master):

1. Merge the branch as usual via a PR.
2. Re-run flux bootstrap with the new --branch value:

flux bootstrap github \
  --owner=berezovskyi-oleksandr \
  --repository=homelab \
  --branch=master \
  --path=./kubernetes \
  --token-auth \
  --personal

This updates both the GitRepository resource in the cluster and the flux-system/gotk-sync.yaml file committed to the repo. No manual kubectl patch needed.

Reconciliation Order

Flux applies resources in dependency order:

1. config — Cluster-wide variables and encrypted secrets
2. infrastructure-controllers — Traefik, cert-manager, Authelia, MetalLB, NFS provisioner, Intel GPU plugin (depends on config)
3. infrastructure-configs — ClusterIssuer, MetalLB config (depends on infrastructure-controllers)
4. external-vars — External service variables (e.g. Home Assistant)
5. apps — All application workloads (depends on config + infrastructure-configs + external-vars)