GitOps with Flux CD

Relevant source files

• kubernetes/apps/flux-system/flux-instance/app/externalsecret.yaml
• kubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml
• kubernetes/apps/flux-system/flux-instance/app/kustomization.yaml
• kubernetes/apps/flux-system/flux-instance/app/prometheusrule.yaml
• kubernetes/apps/flux-system/flux-instance/app/receiver.yaml
• kubernetes/apps/flux-system/flux-instance/ks.yaml
• kubernetes/apps/flux-system/flux-operator/app/helmrelease.yaml
• kubernetes/apps/flux-system/flux-operator/app/kustomization.yaml
• kubernetes/apps/flux-system/flux-operator/ks.yaml
• kubernetes/flux/cluster/ks.yaml

This page provides a high-level overview of the GitOps implementation using Flux CD. In this architecture, the entire state of the Kubernetes cluster—from system controllers to application workloads—is defined in Git and reconciled automatically by Flux. The system is designed for high performance, automated dependency updates, and secure secret handling.

Reconciliation Architecture

The cluster state is driven by a hierarchy of Kustomization resources. The root entry point is the flux-system GitRepository, which points to the main branch of the home-ops repository kubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml33-36 Flux monitors this repository and reconciles changes into the cluster using a continuous loop.

Code-to-System Mapping: Flux Hierarchy

The following diagram illustrates how Flux entities in the code map to the running system components.

[Flowchart Diagram]

Sources:kubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml27-36kubernetes/flux/cluster/ks.yaml1-15

---

Flux Operator and Instance

The deployment of Flux itself is managed by the flux-operator. This operator handles the lifecycle of the flux-instance, which contains the core controllers: source-controller, kustomize-controller, helm-controller, and notification-controllerkubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml27-31

To handle the scale of the home-ops repository, the controllers are tuned for performance:

• Concurrency: The kustomize-controller is configured with 20 concurrent workers kubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml77
• Memory Optimization: In-memory Kustomize builds are enabled using an emptyDir backed by RAM kubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml81-83
• Reliability: The helm-controller utilizes OOMWatch to detect near-out-of-memory conditions and prevent crashes kubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml107-113

For details, see Flux Operator and Instance.

Sources:kubernetes/apps/flux-system/flux-operator/app/helmrelease.yaml1-5kubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml43-117

---

CI/CD Automation and Renovate

Automation is a core pillar of the GitOps workflow. The repository utilizes GitHub Actions and Renovate to ensure the cluster stays up-to-date with minimal manual intervention.

• Renovate: Automatically scans the codebase for outdated Docker images, Helm charts, and Talos versions, submitting Pull Requests with updates.
• Validation: Every PR is validated using flux-local to ensure Kustomizations and HelmReleases are syntactically correct and reconcilable.
• Webhooks: To reduce reconciliation latency, a Receiver is configured to listen for GitHub push events, triggering an immediate refresh of the flux-system GitRepository kubernetes/apps/flux-system/flux-instance/app/receiver.yaml1-18

For details, see CD Automation and Renovate.

Sources:kubernetes/apps/flux-system/flux-instance/app/receiver.yaml1-18kubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml23-24

---

Secrets Management

Secrets in this repository follow a “Shift Left” security model. Sensitive data is never stored in plain text.

1. SOPS: Files containing secrets are encrypted with sops using the age provider before being committed to Git kubernetes/flux/cluster/ks.yaml16-19
2. External Secrets: The ExternalSecret operator bridges the gap between external vaults and Kubernetes. It fetches sensitive values (like the GitHub Webhook Token) from Bitwarden using a ClusterSecretStorekubernetes/apps/flux-system/flux-instance/app/externalsecret.yaml1-20

For details, see Secrets Management.

Sources:kubernetes/flux/cluster/ks.yaml16-35kubernetes/apps/flux-system/flux-instance/app/externalsecret.yaml1-20

---

OpenTofu Controller (In-Cluster Terraform)

While Flux primarily manages Kubernetes manifests, the tofu-controller allows Flux to manage infrastructure resources via Terraform/OpenTofu from within the cluster. This is used for provisioning resources that exist outside of the standard Kubernetes API but are required by applications, such as Authentik configurations or Minio buckets.

For details, see OpenTofu Controller (In-Cluster Terraform).

---

Summary of Component Interactions

The following table describes how the different GitOps components interact during a typical reconciliation cycle.

Component	Role	Code Entity
Source Controller	Fetches Git/OCI artifacts	source-controllerkubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml28
Kustomize Controller	Applies manifests and patches	kustomize-controllerkubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml29
Helm Controller	Manages Helm chart lifecycles	helm-controllerkubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml30
Notification Controller	Handles webhooks and alerts	notification-controllerkubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml31
External Secrets	Injects vault secrets into K8s	ExternalSecretkubernetes/apps/flux-system/flux-instance/app/externalsecret.yaml3

Sources:kubernetes/apps/flux-system/flux-instance/app/helmrelease.yaml27-31kubernetes/apps/flux-system/flux-instance/app/externalsecret.yaml1-5