Stage 4 · Provision

GitOps Workflows

Flux v2

Kustomize, HelmRelease, image automation, and multi-tenancy — Kubernetes-native GitOps.

7 min readInfrastructure as CodeProvision

What Is Flux?

Flux is a set of Kubernetes-native controllers for GitOps. It watches Git repositories, Helm repos, and OCI registries and reconciles the desired state to the cluster. Flux v2 is a ground-up rewrite using the controller-runtime framework.

Flux is more extensible than ArgoCD. Its modular architecture separates source management, reconciliation, and notification into independent controllers. This makes it lighter and more composable.

Flux Architecture

Install Flux


$ curl -s https://fluxcd.io/install.sh | bash

# Bootstrap Flux on a cluster
$ flux bootstrap github \
    --owner=my-org \
    --repository=fleet-infra \
    --branch=main \
    --path=./clusters/my-cluster \
    --personal

The bootstrap command installs Flux components and creates a Git repository for the GitOps configuration. Flux manages its own configuration — the bootstrap repo is both the Flux installation and the GitOps source.

GitRepository Source

A GitRepository source defines which Git repository Flux should watch. It specifies the URL, branch, interval for polling, and optional credentials. Multiple sources can reference different repositories.

GitRepository manifest


apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: webapp
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/org/webapp-manifests.git
  ref:
    branch: main
  secretRef:
    name: git-credentials

The interval field controls how often Flux checks for changes. The secretRef points to a Kubernetes secret with Git credentials. Flux polls the repository at the specified interval and reconciles when changes are detected.

Kustomization

A Kustomization resource tells Flux to apply a directory of Kubernetes manifests. It supports Kustomize overlays, health checks, and dependency ordering between resources.

Kustomization manifest


apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: webapp
  namespace: flux-system
spec:
  interval: 5m
  path: ./overlays/production
  prune: true
  sourceRef:
    kind: GitRepository
    name: webapp
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: webapp
      namespace: production
  timeout: 3m

The Kustomization watches a GitRepository source and applies manifests from a specific path. healthChecks waits for resources to become ready. timeout determines how long to wait before marking the reconciliation as failed.

HelmRelease

The HelmRelease resource manages Helm chart deployments. It specifies the chart, version, values, and upgrade strategy. Flux handles install, upgrade, and rollback automatically.

HelmRelease manifest


apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: nginx-ingress
  namespace: flux-system
spec:
  interval: 30m
  chart:
    spec:
      chart: ingress-nginx
      version: "4.8.x"
      sourceRef:
        kind: HelmRepository
        name: ingress-nginx
  values:
    controller:
      replicaCount: 3
      resources:
        limits:
          cpu: 500m
          memory: 512Mi
  upgrade:
    remediation:
      retries: 3
      remediateLastFailure: true

The HelmRelease tracks a specific chart version using semver ranges. The values block provides Helm values. The remediation configuration automatically retries failed upgrades up to 3 times.

Image Automation

Flux can automatically update container images in Git when new versions are available. The ImageRepository controller scans registries, the ImagePolicy controller selects which tag to use, and the ImageUpdateAutomation controller commits the changes to Git.

Image update automation


apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: webapp
  namespace: flux-system
spec:
  image: ghcr.io/org/webapp
  interval: 1m
---
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: webapp
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: webapp
  policy:
    semver:
      range: ">=1.0.0 <2.0.0"
---
apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: webapp
  namespace: flux-system
spec:
  interval: 1m
  sourceRef:
    kind: GitRepository
    name: webapp
  git:
    checkout:
      ref:
        branch: main
    commit:
      author: fluxcdbot
      message: "Update image: {{range .Updated.Images}}{{println .}}{{end}}"
    push:
      branch: main

The ImageRepository scans the container registry. The ImagePolicy selects the latest semver tag. The ImageUpdateAutomation commits a new image tag to Git. Flux then detects the Git change and deploys it.

Multi-Tenancy

Flux supports multi-tenancy through namespace isolation and RBAC. Each tenant gets their own namespace, GitRepository, and Kustomization. Tenant controllers run in their own namespace with limited permissions.

Tenant namespace and RBAC


apiVersion: v1
kind: Namespace
metadata:
  name: team-a
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: team-a
  namespace: team-a
spec:
  interval: 5m
  path: ./team-a
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
  serviceAccountName: flux-team-a

Each tenant has their own namespace, Kustomization, and service account. The service account has RBAC permissions limited to their namespace. This prevents tenants from deploying to each other's namespaces.

Use flux diff for safe deployments

Run flux diff kustomization to preview changes before committing. This shows exactly what Flux would apply without actually applying it. Use it in CI to validate changes before merging.

Flux is Git-native

Flux treats Git as the source of truth more strictly than ArgoCD. Manual changes are reconciled away. Image updates create Git commits. The entire deployment lifecycle flows through Git.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.