> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# FluxCD Architecture Part2
> This article explores the architecture of FluxCD, detailing its core controllers and their roles in implementing GitOps workflows on Kubernetes.
Welcome to Part 2 of our deep dive into FluxCD Architecture. In this lesson, we’ll explore each Flux controller and see how they collaborate to implement GitOps workflows on Kubernetes.
Below is an overview of the five core controllers deployed in the `flux-system` namespace when you install Flux:
| Controller | Resource Types | Primary Function |
| ---------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- |
| Source Controller | `GitRepository`, `HelmRepository`, `OCIRepository`, `Bucket` | Fetches and makes external artifacts available |
| Kustomize Controller | `Kustomization` | Builds and applies Kustomize overlays |
| Helm Controller | `HelmRelease` | Manages Helm chart lifecycle (install, upgrade, rollback) |
| Image Reflector & Automation | `ImageRepository`, `ImagePolicy`, `ImageUpdateAutomation` | Detects new image tags and updates Git manifests |
| Notification Controller | `Alert`, `Receiver` | Routes inbound webhooks and outbound notifications |
***
## 1. Source Controller
The Source Controller offers a consistent interface to pull artifacts from various external systems into your cluster.
Supported sources:
* **Git repositories** via `GitRepository`
* **Helm chart repositories** via `HelmRepository`
* **OCI registries** via `OCIRepository`
* **S3-compatible buckets** via `Bucket`
Example: A simple Kubernetes Deployment stored in Git
```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
name: game
spec:
replicas: 3
template:
metadata:
labels:
app: game
spec:
containers:
- name: game
image: game:v1
```
The Source Controller will clone or pull the repo, then expose the manifest to downstream Flux controllers.
Ensure you provide credentials for private Git, OCI or S3 repositories via Kubernetes Secrets.
***
## 2. Kustomize Controller
Use the Kustomize Controller when your repository holds raw YAML or [Kustomize][kustomize] overlays. Define a `Kustomization` resource that:
1. References a fetched source (e.g., `GitRepository`).
2. Builds the Kustomize overlays.
3. Applies the resulting manifests to your Kubernetes cluster.
```yaml theme={null}
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
name: game-app
spec:
interval: 5m0s
sourceRef:
kind: GitRepository
name: game-repo
path: "./overlays/production"
prune: true
validation: client
```
Every commit to the Git repo triggers the Source Controller, which in turn prompts the Kustomize Controller to reconcile your desired state.
***
## 3. Helm Controller
If you prefer [Helm][helm] charts, Flux can fetch them via the Source Controller from Git, Helm repos, or OCI registries. Declare a `HelmRelease` to manage:
* Chart source and version
* Custom values
* Release settings (rollback, tests)
```yaml theme={null}
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: game-chart
spec:
chart:
spec:
chart: ./charts/game
sourceRef:
kind: GitRepository
name: game-repo
version: ">=1.2.0"
interval: 10m
values:
replicaCount: 3
```
The Helm Controller watches these resources and automates installs, upgrades, rollbacks, tests, and uninstalls.
***
## 4. Image Controllers
Flux splits image automation into two controllers for granular control:
| Controller | Role |
| -------------------- | ---------------------------------------------------------------------------------------- |
| **Image Reflector** | Periodically scans registries for new image tags, populating `ImageRepository` resources |
| **Image Automation** | Observes `ImagePolicy` updates and rewrites Git manifests via `ImageUpdateAutomation` |
When a new tag (e.g., `game:v2`) matches your policy, Flux commits the updated image reference back to Git:
```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
name: game
spec:
replicas: 3
template:
metadata:
labels:
app: game
spec:
containers:
- name: game
image: game:v2
```
The Image Automation Controller requires write access to your Git repository. Ensure branch protections and commit permissions are configured securely.
***
## 5. Notification Controller
The Notification Controller connects Flux events with external systems:
* **Inbound**: Listens for Git webhooks (GitHub, GitLab) or registry events to trigger immediate reconciliation.
* **Outbound**: Sends events (deployment success/failure, image updates, reconciliation errors) to channels like Slack, Teams, Discord, or email.
You configure `Alert` and `Receiver` resources to route events:
```yaml theme={null}
apiVersion: notification.toolkit.fluxcd.io/v1beta1
kind: Alert
metadata:
name: slack-alert
spec:
eventSources:
- kind: GitRepository
name: game-repo
eventSeverity: info
receiverRefs:
- name: team-slack
```
***
Whenever the Source Controller pulls commits or the Image Automation Controller pushes an update, the Kustomize or Helm Controller reconciles your cluster to match the latest Git state—completing the GitOps loop.
***
## Links and References
* [FluxCD Documentation][fluxcddocs]
* [FluxCD Website][fluxcd]
* [Kustomize Reference][kustomize]
* [Helm Docs][helm]
* [Kubernetes Documentation][kubernetes]
* [OCI Artifacts Specification][oci]
[fluxcd]: https://fluxcd.io
[fluxcddocs]: https://fluxcd.io/docs
[kustomize]: https://kubectl.docs.kubernetes.io/references/kustomize/
[helm]: https://helm.sh/docs
[kubernetes]: https://kubernetes.io/docs/
[oci]: https://github.com/opencontainers/artifacts
[s3]: https://aws.amazon.com/s3/