Flux

Bootstrap flux with existing git repository, image-reflector and image-automation controllers enabled for image update automation.

flux bootstrap git --url=ssh://git@<YOUR_GIT_REPOSITORY_URL> \
    --private-key-file=$HOME/.ssh/id_ed25519 \
    --branch=main \
    --path=clusters/homelab \
    --components-extra image-reflector-controller,image-automation-controller

Upgrading Flux

Update your flux cli into the latest version:

flux install \
    --components-extra="image-reflector-controller,image-automation-controller" \
    --export > ./clusters/homelab/flux-system/gotk-components.yaml

Reconcile Manually

flux reconcile ks flux-system --with-source

Production Lessons & Best Practices

CRD Dependencies & Multi-Stage Reconciliation

When deploying services that depend on custom CustomResourceDefinitions (e.g., Gateway API TCPRoute or HTTPRoute, Traefik IngressRoutes, or cert-manager resources), always ensure the CRD definitions are staged in an earlier Kustomization or dependency tree:

Use dependsOn: in Flux Kustomization manifests to enforce that CRDs and operators reconcile before application routes.
Avoid mixing CRD installations and their custom resources within the exact same unstaged kustomization to prevent reconciliation errors and race conditions during cluster bootstrap.

Secrets Management in GitOps

Never commit plaintext secrets to your Git repository:

SOPS + age: Standard pattern for encrypting secret files in Git. The cluster keeps the age private key in a Kubernetes Secret (sops-age), allowing Flux kustomize-controller to decrypt in-memory.
External Secret Stores (Infisical / Vault): When using token-based secret sync, ensure authorization credentials have fallback renewal mechanisms and token rotation procedures to prevent 401/403 checkout and synchronization failures.