k8s-gitops

Flux-managed Kubernetes homelab. Infrastructure and media stack deployed declaratively from Git.

This repo replaces the imperative deploy.sh approach from k8s-media-stack with Flux GitOps. Same Helm charts, same values, automated delivery.

Architecture

┌──────────────────────────────────────────────────────────┐
│  Git push                                                │
│     │                                                    │
│     ▼                                                    │
│  Flux (in-cluster)                                       │
│     │                                                    │
│     ├── infrastructure/        (Kustomization, wait)     │
│     │   ├── MetalLB            HelmRelease               │
│     │   ├── NFS CSI            HelmRelease               │
│     │   └── Traefik            HelmRelease               │
│     │                                                    │
│     └── apps/                  (Kustomization, depends)  │
│         ├── Plex               HelmRelease               │
│         ├── Sonarr             HelmRelease               │
│         ├── Radarr             HelmRelease               │
│         ├── Prowlarr           HelmRelease               │
│         ├── qBittorrent        HelmRelease               │
│         ├── Bazarr             HelmRelease               │
│         ├── Overseerr          HelmRelease               │
│         ├── Tautulli           HelmRelease               │
│         └── Homepage           raw manifest              │
└──────────────────────────────────────────────────────────┘

Prerequisites

• Talos Kubernetes cluster running (k8s-deploy)
• flux CLI installed (install guide)
• kubectl configured
• GitHub personal access token with repo scope
• NFS directories created on Synology (see k8s-media-stack)

Bootstrap

export GITHUB_TOKEN=<your-token>
export GITHUB_USER=<your-username>

flux bootstrap github \
    --owner=$GITHUB_USER \
    --repository=k8s-gitops \
    --branch=main \
    --path=clusters/homelab \
    --personal

This:

1. Installs Flux components into the cluster (flux-system namespace)
2. Creates a GitRepository source pointing at this repo
3. Creates a Kustomization that syncs clusters/homelab/
4. Commits the Flux manifests back to the repo

After bootstrap, Flux picks up infrastructure.yaml and apps.yaml from clusters/homelab/ and reconciles everything.

Repo Structure

k8s-gitops/
├── clusters/
│   └── homelab/
│       ├── flux-system/           # Auto-generated by flux bootstrap
│       ├── infrastructure.yaml    # Flux Kustomization → infrastructure/
│       └── apps.yaml              # Flux Kustomization → apps/ (depends on infra)
├── infrastructure/
│   ├── kustomization.yaml         # Native kustomize resource list
│   ├── sources/
│   │   └── helm-repositories.yaml # HelmRepository CRDs
│   ├── metallb/
│   │   ├── namespace.yaml
│   │   ├── helmrelease.yaml
│   │   └── config.yaml            # IPAddressPool + L2Advertisement
│   ├── nfs-csi/
│   │   ├── helmrelease.yaml
│   │   └── storageclass.yaml
│   └── traefik/
│       ├── namespace.yaml
│       └── helmrelease.yaml
└── apps/
    ├── kustomization.yaml         # Native kustomize resource list
    ├── media/
    │   ├── namespace.yaml
    │   ├── storage.yaml           # Shared NFS PV/PVC
    │   ├── plex.yaml              # HelmRelease (LoadBalancer)
    │   ├── sonarr.yaml            # HelmRelease (Ingress)
    │   ├── radarr.yaml
    │   ├── prowlarr.yaml
    │   ├── qbittorrent.yaml       # HelmRelease (Ingress + LoadBalancer)
    │   ├── bazarr.yaml
    │   ├── overseerr.yaml
    │   └── tautulli.yaml
    └── dashboard/
        └── homepage.yaml          # Raw manifest (Deployment, Service, Ingress, ConfigMap)

Dependency Order

Flux Kustomizations enforce ordering:

1. infrastructure — deploys MetalLB, NFS CSI, Traefik. Waits for health checks.
2. apps — deploys media apps. Only starts after infrastructure is healthy.

Within each layer, Flux applies resources in the order listed in kustomization.yaml.

Day-to-Day Operations

Change an app's config

Edit the HelmRelease values, push to main. Flux reconciles within 30 minutes (or on demand):

flux reconcile kustomization apps --with-source

Check status

flux get kustomizations
flux get helmreleases -A

Suspend an app

flux suspend helmrelease sonarr -n media

Resume later:

flux resume helmrelease sonarr -n media

Force immediate sync

flux reconcile source git flux-system

Customization

Before deploying, update these values for your environment:

File	What to change
infrastructure/metallb/config.yaml	IP address pool range
infrastructure/nfs-csi/storageclass.yaml	NAS IP and NFS share path
infrastructure/traefik/helmrelease.yaml	Traefik LoadBalancer IP
apps/media/storage.yaml	NAS IP and NFS data path
apps/media/plex.yaml	Plex LoadBalancer IP, timezone
apps/media/qbittorrent.yaml	qBittorrent LoadBalancer IP
All app HelmReleases	TZ environment variable

Migration from deploy.sh

This repo is a 1:1 port of k8s-media-stack. Each helm install from deploy.sh maps to a HelmRelease CRD. Same charts, same values, automated delivery.

deploy.sh	k8s-gitops
helm install metallb ...	infrastructure/metallb/helmrelease.yaml
helm install traefik ... -f traefik-values.yaml	infrastructure/traefik/helmrelease.yaml (values inline)
helm install sonarr bjw-s/app-template -f values.yaml	apps/media/sonarr.yaml (values inline)
kubectl apply -f metallb-config.yaml	infrastructure/metallb/config.yaml
kubectl apply -f homepage.yaml	apps/dashboard/homepage.yaml