Flux Components

Kimbernetes runs FluxCD v2.7.5, a complete GitOps toolkit that consists of six specialized controllers working together to maintain the desired state of your Kubernetes cluster.

Flux System Overview

All Flux components run in the flux-system namespace and are installed via the gotk-components.yaml manifest generated during bootstrap.

kubectl get pods -n flux-system

Expected output:

NAME                                       READY   STATUS    RESTARTS   AGE
source-controller-xxxxx                    1/1     Running   0          30d
kustomize-controller-xxxxx                 1/1     Running   0          30d
helm-controller-xxxxx                      1/1     Running   0          30d
notification-controller-xxxxx              1/1     Running   0          30d
image-reflector-controller-xxxxx           1/1     Running   0          30d
image-automation-controller-xxxxx          1/1     Running   0          30d

Core Controllers

source-controller

The source-controller is responsible for acquiring artifacts from external sources and making them available to other Flux components.

Purpose
Custom Resources
Configuration

Primary Role: Fetch and cache artifacts from various sources

Monitors Git repositories for changes
Manages Helm chart repositories
Handles S3/OCI buckets
Creates and maintains artifact archives
Provides HTTP endpoints for artifact access

The source-controller is the foundation of Flux - without it, no other controller can access your configurations.

The source-controller manages these CRDs:GitRepository - Git repository sources

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: flux-system
  namespace: flux-system
spec:
  interval: 1m0s
  ref:
    branch: main
  secretRef:
    name: flux-system
  url: ssh://[email protected]/kim-ae/kimbernetes-k8s-flux

HelmRepository - Helm chart repositoriesBucket - S3-compatible bucketsExternalArtifact - External artifact references

Key configuration in cluster/kimawesome/flux-system/gotk-sync.yaml:

Interval: 1m0s - Check for changes every minute
Branch: main - The Git branch to monitor
Authentication: SSH key stored in flux-system secret

The source-controller exposes metrics on port 8080 and runs with specific RBAC permissions to access cluster resources.

kustomize-controller

The kustomize-controller applies Kustomize configurations to the cluster, processing overlays and patches to produce final manifests.

Reconciliation

Continuously reconciles Kustomization resources, ensuring cluster state matches Git

Build Process

Processes Kustomize overlays, applying patches and generating final manifests

Health Checks

Monitors deployed resources for health and readiness

Pruning

Removes resources that are no longer defined in Git when prune: true

Kustomization Resource Example

The primary Kustomization that Flux reconciles:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: flux-system
  namespace: flux-system
spec:
  interval: 10m0s
  path: ./cluster/kimawesome
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system

Key fields:

interval: How often to reconcile (10 minutes)
path: Directory in Git to process
prune: Delete resources not in Git
sourceRef: Which GitRepository to use

Dependency Management

Kustomizations can depend on other Kustomizations:

apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: infrastructure
  namespace: flux-system
spec:
  interval: 10m
  path: "./overlays/kimawesome/infrastructure"
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
  dependsOn:
    - name: metallb
      namespace: kube-system

This ensures infrastructure is deployed after metallb is ready.

Permissions

The kustomize-controller runs with ClusterAdmin privileges via the cluster-reconciler-flux-system ClusterRoleBinding:

subjects:
- kind: ServiceAccount
  name: kustomize-controller
  namespace: flux-system
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin

This broad permission is required to manage any resource type in the cluster. Consider using more restrictive RBAC for production environments if needed.

helm-controller

The helm-controller automates Helm chart deployments, managing the full lifecycle of Helm releases.

Watch HelmRelease Resources

Monitors HelmRelease custom resources for changes

Fetch Chart

Retrieves the Helm chart from the specified HelmRepository

Render Templates

Processes Helm templates with provided values

Install or Upgrade

Installs new releases or upgrades existing ones

Monitor Health

Watches deployed resources for health status

Rollback on Failure

Automatically rolls back failed upgrades if configured

HelmRepository
HelmRelease
Benefits

Defines where to fetch Helm charts:

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: metallb
  namespace: kube-system
spec:
  interval: 24h
  url: https://metallb.github.io/metallb

The source-controller fetches the chart index every 24 hours.

Defines how to deploy a Helm chart:

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: metallb
  namespace: kube-system
spec:
  chart:
    spec:
      chart: metallb
      sourceRef:
        kind: HelmRepository
        name: metallb
      version: "=0.15.3"
  interval: 24h
  releaseName: metallb
  install:
    crds: Create
  upgrade:
    crds: CreateReplace
  values:
    # Custom values here

Key features:

Version pinning: =0.15.3 ensures specific version
CRD management: Automatic CRD installation and updates
Custom values: Override chart defaults
Reconciliation: Check every 24 hours

notification-controller

The notification-controller handles events and alerts, enabling integration with external systems.

Event Handling

The controller processes events from other Flux components and can:

Send notifications to Slack, Discord, Microsoft Teams
Trigger webhooks for CI/CD integration
Update commit statuses on Git providers
Forward events to external monitoring systems

While Kimbernetes doesn’t currently use notifications extensively, the controller is available for future integration.

Provider Configuration

Example notification provider:

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: slack
  namespace: flux-system
spec:
  type: slack
  channel: flux-alerts
  secretRef:
    name: slack-webhook

And corresponding alert:

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: on-error
  namespace: flux-system
spec:
  providerRef:
    name: slack
  eventSeverity: error
  eventSources:
    - kind: Kustomization
      name: '*'

Webhook Receivers

The notification-controller can receive webhooks from Git providers to trigger immediate reconciliation:

apiVersion: notification.toolkit.fluxcd.io/v1
kind: Receiver
metadata:
  name: flux-system
  namespace: flux-system
spec:
  type: github
  events:
    - "ping"
    - "push"
  secretRef:
    name: webhook-token
  resources:
    - apiVersion: source.toolkit.fluxcd.io/v1
      kind: GitRepository
      name: flux-system

This enables instant deployments instead of waiting for the polling interval.

image-reflector-controller

The image-reflector-controller scans container registries for new image versions.

This controller enables automated image updates - when a new container image is published, Flux can automatically update your manifests and deploy the new version.

Custom Resources:

ImageRepository - Defines which container registry to scan
ImagePolicy - Defines rules for selecting image versions (e.g., semver ranges)

Example configuration:

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: myapp
  namespace: flux-system
spec:
  image: ghcr.io/myorg/myapp
  interval: 5m
---
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: myapp
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: myapp
  policy:
    semver:
      range: '>=1.0.0 <2.0.0'

image-automation-controller

The image-automation-controller automatically updates Git repositories when new images are detected. Workflow:

image-reflector-controller detects new image version
image-automation-controller updates manifest in Git
Commits and pushes the change
source-controller detects the Git change
kustomize-controller/helm-controller deploys the new version

Custom Resource:

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageUpdateAutomation
metadata:
  name: flux-system
  namespace: flux-system
spec:
  interval: 5m
  sourceRef:
    kind: GitRepository
    name: flux-system
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        email: [email protected]
        name: fluxcdbot
      messageTemplate: |
        Automated image update
        
        Updates:
        {{ range .Updated.Images -}}
        - {{.}} 
        {{ end -}}
    push:
      branch: main
  update:
    path: ./overlays/kimawesome
    strategy: Setters

Image automation is powerful but optional. Kimbernetes currently uses manual image version management in HelmRelease resources for more control over updates.

Controller Communication

Monitoring Flux Components

Check Status
View Logs
Reconcile Manually
Metrics

View the status of all Flux resources:

flux get all --all-namespaces

Check specific Kustomizations:

flux get kustomizations -n flux-system

View logs from Flux controllers:

# Source controller logs
kubectl logs -n flux-system -l app=source-controller

# Kustomize controller logs
kubectl logs -n flux-system -l app=kustomize-controller

# Helm controller logs
kubectl logs -n flux-system -l app=helm-controller

Trigger immediate reconciliation:

# Reconcile a specific Kustomization
flux reconcile kustomization flux-system --with-source

# Reconcile a HelmRelease
flux reconcile helmrelease metallb -n kube-system

Flux controllers expose Prometheus metrics on port 8080:

kubectl port-forward -n flux-system svc/source-controller 8080:80
curl http://localhost:8080/metrics

Key metrics:

gotk_reconcile_duration_seconds - Reconciliation time
gotk_reconcile_condition - Resource conditions
gotk_suspend_status - Suspended resources

Security Considerations

RBAC

Controllers use ServiceAccounts with specific RBAC permissions. The kustomize and helm controllers have ClusterAdmin access.

Network Policies

NetworkPolicies restrict traffic to and from Flux components, allowing only necessary communication.

Secret Management

Git credentials and other secrets are stored in Kubernetes Secrets with appropriate access controls.

Pod Security

Flux namespace has pod security warnings enabled for restricted policies.

Flux Version

Kimbernetes runs Flux v2.7.5 with all six controllers enabled:

source-controller
kustomize-controller
helm-controller
notification-controller
image-reflector-controller
image-automation-controller

This version was installed during bootstrap and is defined in cluster/kimawesome/flux-system/gotk-components.yaml:1-4.

Next Steps

Kustomize Overlays

Learn how Kustomize overlays work with the kustomize-controller

Troubleshooting

Debug common Flux issues and understand controller behavior

Upgrading Flux

Learn how to safely upgrade Flux components

Repository Structure

Review how the repository is organized for Flux

Getting Started

Setup & Deployment

Architecture

Infrastructure Components

Observability

Applications

Operations

Flux System Overview

Core Controllers

source-controller

kustomize-controller

Reconciliation

Build Process

Health Checks

Pruning

helm-controller

Declarative

Automated

Auditable

Consistent

notification-controller

image-reflector-controller

image-automation-controller

Controller Communication

Monitoring Flux Components

Security Considerations

RBAC

Network Policies

Secret Management

Pod Security

Flux Version

Next Steps

Kustomize Overlays

Troubleshooting

Upgrading Flux

Repository Structure

Build docs developers (and LLMs) love

Getting Started

Setup & Deployment

Architecture

Infrastructure Components

Observability

Applications

Operations

​Flux System Overview

​Core Controllers

​source-controller

​kustomize-controller

Reconciliation

Build Process

Health Checks

Pruning

​helm-controller

Declarative

Automated

Auditable

Consistent

​notification-controller

​image-reflector-controller

​image-automation-controller

​Controller Communication

​Monitoring Flux Components

​Security Considerations

RBAC

Network Policies

Secret Management

Pod Security

​Flux Version

​Next Steps

Kustomize Overlays

Troubleshooting

Upgrading Flux

Repository Structure

Build docs developers (and LLMs) love

Flux System Overview

Core Controllers

source-controller

kustomize-controller

helm-controller

notification-controller

image-reflector-controller

image-automation-controller

Controller Communication

Monitoring Flux Components

Security Considerations

Flux Version

Next Steps