Flux GitOps Toolkit

The Flux GitOps Toolkit is a collection of Kubernetes controllers that work together to implement GitOps. Each controller manages a specific aspect of the GitOps workflow, from fetching sources to applying manifests and automating image updates.

Toolkit Architecture

graph TB A[Git Repository] --> B[Source Controller] B --> C[GitRepository CRD] D[Helm Repository] --> B B --> E[HelmRepository CRD] F[S3 Bucket] --> B B --> G[Bucket CRD] C --> H[Kustomize Controller] C --> I[Helm Controller] E --> I H --> J[Kubernetes Resources] I --> J K[Container Registry] --> L[Image Repository Controller] L --> M[ImageRepository CRD] M --> N[Image Policy Controller] N --> O[ImagePolicy CRD] O --> P[Image Update Automation Controller] P --> Q[ImageUpdateAutomation CRD] Q --> A style B fill:#e1f5ff style H fill:#e8f5e9 style I fill:#fff4e1 style L fill:#f3e5f5 style N fill:#ffe1e1 style P fill:#e1f5ff

Source Controller

The Source Controller manages external sources of Kubernetes manifests and Helm charts.

Responsibilities

Clones Git repositories
Fetches Helm charts from repositories
Retrieves artifacts from S3-compatible buckets
Caches sources locally
Provides artifacts to other controllers

GitRepository CRD

Manages Git repositories as sources:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: GitRepository
metadata:
  name: web-app
  namespace: flux-system
spec:
  interval: 1m0s
  url: https://github.com/your-org/kubernetes-manifests
  ref:
    branch: main
  secretRef:
    name: git-credentials

HelmRepository CRD

Manages Helm chart repositories:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  name: bitnami
  namespace: flux-system
spec:
  interval: 15m0s
  url: https://charts.bitnami.com/bitnami

Bucket CRD

Manages S3-compatible buckets:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: Bucket
metadata:
  name: manifests
  namespace: flux-system
spec:
  interval: 5m0s
  bucketName: my-manifests-bucket
  endpoint: s3.amazonaws.com
  region: us-east-1
  secretRef:
    name: s3-credentials

OCI Repository CRD

Manages OCI artifact repositories:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
  name: oci-artifacts
  namespace: flux-system
spec:
  interval: 5m0s
  url: oci://ghcr.io/your-org/manifests
  secretRef:
    name: oci-credentials

Kustomize Controller

The Kustomize Controller applies Kustomize overlays to Kubernetes clusters.

Responsibilities

Watches Kustomization resources
Fetches sources from Source Controller
Builds Kustomize overlays
Applies resources to cluster
Monitors resource health
Prunes deleted resources

Kustomization CRD

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: web-app
  namespace: flux-system
spec:
  interval: 5m0s
  path: ./apps/web-app
  prune: true
  sourceRef:
    kind: GitRepository
    name: web-app
  validation: client
  healthChecks:
  - apiVersion: apps/v1
    kind: Deployment
    name: web-app
    namespace: default

Kustomization Spec

Key fields:

interval - How often to reconcile
path - Path to Kustomize directory in source
prune - Delete resources removed from Git
sourceRef - Reference to source (GitRepository, Bucket, etc.)
validation - Validate resources before applying
healthChecks - Resources to check for health

Example Workflow

sequenceDiagram participant K as Kustomization participant SC as Source Controller participant KC as Kustomize Controller participant K8s as Kubernetes K->>SC: 1. Request Source SC->>K: 2. Provide Artifact K->>KC: 3. Trigger Reconciliation KC->>KC: 4. Build Kustomize KC->>K8s: 5. Apply Resources K8s->>KC: 6. Resource Status KC->>K: 7. Update Status

Helm Controller

The Helm Controller manages Helm releases in Kubernetes clusters.

Responsibilities

Watches HelmRelease resources
Fetches Helm charts from Source Controller
Installs/upgrades Helm releases
Monitors release status
Handles rollbacks

HelmRelease CRD

apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: nginx
  namespace: flux-system
spec:
  interval: 5m0s
  chart:
    spec:
      chart: nginx
      sourceRef:
        kind: HelmRepository
        name: bitnami
      version: '13.2.20'
  values:
    service:
      type: LoadBalancer
    replicaCount: 3

HelmRelease Spec

Key fields:

interval - Reconciliation interval
chart - Helm chart specification
values - Helm values
releaseName - Name of Helm release
targetNamespace - Namespace to install release
install - Install configuration
upgrade - Upgrade configuration

Helm Chart from Git

apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m0s
  chart:
    spec:
      chart: ./charts/my-app
      sourceRef:
        kind: GitRepository
        name: my-repo
      version: '*'
  values:
    image:
      tag: v1.0.0

Image Automation Controllers

Flux includes three controllers for automating container image updates.

Image Repository Controller

Monitors container registries for new image tags.

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: web-app
  namespace: flux-system
spec:
  image: docker.io/your-org/web-app
  interval: 1m0s
  secretRef:
    name: registry-credentials

Image Policy Controller

Defines policies for which image tags to use.

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: web-app
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: web-app
  policy:
    semver:
      range: '>=1.0.0 <2.0.0'

Image Update Automation Controller

Automatically updates Git with new image tags.

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageUpdateAutomation
metadata:
  name: web-app
  namespace: flux-system
spec:
  interval: 5m0s
  sourceRef:
    kind: GitRepository
    name: web-app
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        name: Flux
        email: [email protected]
      messageTemplate: 'Update image: {{range .Updated.Images}}{{println .}}{{end}}'
    push:
      branch: main
  update:
    path: ./apps/web-app
    strategy: Setters

Component Interactions

Complete Workflow

sequenceDiagram participant Git as Git Repository participant SC as Source Controller participant KC as Kustomize Controller participant K8s as Kubernetes participant Reg as Container Registry participant IR as Image Repository participant IP as Image Policy participant IUA as Image Update Automation Git->>SC: 1. Clone Repository SC->>KC: 2. Provide Artifact KC->>K8s: 3. Apply Manifests Reg->>IR: 4. New Image Tag IR->>IP: 5. Check Policy IP->>IUA: 6. Policy Match IUA->>Git: 7. Update Manifest Git->>SC: 8. New Commit

Reconciliation Process

All Flux controllers follow a reconciliation loop:

graph TB A[Reconciliation Trigger] --> B[Fetch Source] B --> C[Process Resources] C --> D{Changes Detected?} D -->|Yes| E[Apply Changes] D -->|No| F[Wait for Interval] E --> G[Monitor Status] G --> H{Healthy?} H -->|Yes| F H -->|No| I[Retry/Alert] I --> F F --> A style A fill:#e1f5ff style E fill:#e8f5e9 style G fill:#fff4e1

Reconciliation Phases

Fetch - Get source from Source Controller
Build - Build Kustomize overlay or Helm chart
Diff - Compare desired vs actual state
Apply - Apply changes if needed
Verify - Check resource health
Wait - Wait for next interval

Status and Health Checks

Resource Status

Flux controllers update status in CRDs:

# Check GitRepository status
kubectl get gitrepository -n flux-system

# Check Kustomization status
kubectl get kustomization -n flux-system

# Get detailed status
kubectl describe kustomization web-app -n flux-system

Health Checks

Kustomization can define health checks:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: web-app
  namespace: flux-system
spec:
  healthChecks:
  - apiVersion: apps/v1
    kind: Deployment
    name: web-app
    namespace: default
  - apiVersion: v1
    kind: Service
    name: web-app
    namespace: default

Status Conditions

Resources have conditions:

Ready - Resource is ready
Reconciling - Currently reconciling
Stalled - Reconciliation failed
Suspended - Reconciliation paused

Best Practices

1. Use Appropriate Intervals

GitRepository: 1-5 minutes
Kustomization: 5-10 minutes
HelmRelease: 5-10 minutes
ImageRepository: 1-5 minutes

2. Enable Pruning

Enable pruning to remove deleted resources:

spec:
  prune: true

3. Use Health Checks

Define health checks for critical resources:

spec:
  healthChecks:
  - apiVersion: apps/v1
    kind: Deployment
    name: web-app

4. Validate Resources

Enable validation:

spec:
  validation: client  # or server

5. Monitor Controller Logs

Set up log aggregation for:

Reconciliation errors
Source fetch failures
Apply failures
Health check failures

Troubleshooting

Source Not Available

# Check Source Controller logs
kubectl logs -n flux-system deployment/source-controller

# Check GitRepository status
kubectl describe gitrepository <NAME> -n flux-system

# Verify Git credentials
kubectl get secret -n flux-system

Kustomization Not Applying

# Check Kustomize Controller logs
kubectl logs -n flux-system deployment/kustomize-controller

# Check Kustomization status
kubectl describe kustomization <NAME> -n flux-system

# Verify source is ready
kubectl get gitrepository -n flux-system

Helm Release Failing

# Check Helm Controller logs
kubectl logs -n flux-system deployment/helm-controller

# Check HelmRelease status
kubectl describe helmrelease <NAME> -n flux-system

# Check Helm release in cluster
helm list -A

Summary

The Flux GitOps Toolkit consists of:

Source Controller - Manages Git, Helm, and OCI sources
Kustomize Controller - Applies Kustomize overlays
Helm Controller - Manages Helm releases
Image Automation Controllers - Automate image updates

Each controller:

Watches CRDs for configuration
Fetches sources from Source Controller
Applies resources to cluster
Monitors resource health
Provides status updates

Controllers work together to implement a complete GitOps workflow, from source management to automated deployments and image updates.