Learning GitOps - FluxCD - Image Automation

#Introduction

In episode 12 you learned multi-tenancy: how to separate several teams in one cluster with per-tenant RBAC, quotas, and lockdown mode. That structure and isolation will be useful now, because episode 13 discusses something that runs across environments: image automation.

Image automation is FluxCD's ability to monitor the container registry, detect new images, evaluate the version that matches a policy, then update the manifests in Git automatically. The whole flow stays 100% GitOps — changes always end up in Git as the single source of truth, only they don't have to be done manually by a human.

#Image Automation Components

Image automation in FluxCD is built from three CustomResourceDefinitions (CRDs) that work together:

#ImageRepository

ImageRepository is tasked with periodically scanning the container registry and storing the list of tags it finds. This component is run by the image-reflector-controller.

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  image: ghcr.io/stefanprodan/podinfo
  interval: 10m

#Registry Authentication

For a private registry, create a Secret containing the credentials, then reference it via secretRef:

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: private-app
  namespace: flux-system
spec:
  image: registry.example.com/private-app
  interval: 5m
  secretRef:
    name: registry-credentials

kubectl create secret docker-registry registry-credentials \
  --namespace=flux-system \
  --docker-server=registry.example.com \
  --docker-username=ci \
  --docker-password=xxxxx

#Interval and Filtering

The interval field determines how often the registry is scanned. Avoid an interval that's too short, for example one minute, for a large registry because it will burden both the registry and the controller. To limit which tags are monitored, use filterTags with a regex pattern and an optional extract:

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: app
  namespace: flux-system
spec:
  image: ghcr.io/acme/app
  interval: 10m
  filterTags:
    pattern: "^v?[0-9]+\\.[0-9]+\\.[0-9]+$"
    extract: "$1"

#ImagePolicy

ImagePolicy determines the version selection policy from the tags found by the ImageRepository.

#Semver Policy

The most common policy, using semantic versioning:

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

With that range, the ImagePolicy selects the highest version tag that satisfies the range. The supported operators include >=, >, <, <=, =, plus the x and * wildcards.

#Alphabetical Policy

Compares tags lexicographically. Useful for tags that aren't semver versions:

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: app
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: app
  policy:
    alphabetical:
      order: asc

#Numerical Policy

Compares tags as numbers, so the numerical order is respected:

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: app
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: app
  policy:
    numerical:
      order: asc

#Policy Comparison

#ImageUpdateAutomation

ImageUpdateAutomation is the engine that writes the update back to Git. This component is run by the image-automation-controller.

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageUpdateAutomation
metadata:
  name: flux-system
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: flux-system
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        email: fluxcdbot@users.noreply.github.com
        name: fluxcdbot
      messageTemplate: |
        [ci skip] update image version
    push:
      branch: main

#Commit Message Template

The messageTemplate field determines the content of the commit message. The template supports several built-in variables, for example the image name and the new version. The [ci skip] prefix in the example above prevents a recurring CI pipeline from triggering itself.

#Branch Strategy

By default the update is written to the same branch as the checkout. For a pull request strategy, for example updating to a feature branch then a PR to main, set checkout.ref and push.branch to different branches so the change can be reviewed by a human first.

#Author Configuration

Always set a clear author, for example a bot account. This makes auditing easier: the commit history will show that the change was made by the image automation bot, not a human.

#End-to-End Workflow

Let's put all the components together with a real flow:

1. A CI pipeline builds a new image and pushes it to the registry with a new version tag
2. The ImageRepository detects the new tag on the next interval
3. The ImagePolicy evaluates which tag satisfies the semver policy
4. The ImageUpdateAutomation updates the image field in the Git manifests and creates a commit
5. Flux syncs the change from Git to the cluster

For the ImageUpdateAutomation to know which image to update, the Kustomization must have an images block:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 10m
  path: ./apps
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
  images:
    - name: ghcr.io/stefanprodan/podinfo
      newName: ghcr.io/stefanprodan/podinfo

When the ImagePolicy produces a new version, the ImageUpdateAutomation writes that version into the newTag or newName on the Kustomization, then commits to Git. Verify the running components:

flux get images repository
flux get images policy
flux get images update

#Use Cases

#Closing

Episode 13 wraps up how FluxCD automates image updates from the registry to Git.

The key takeaways:

• Three components: ImageRepository scans, ImagePolicy evaluates, ImageUpdateAutomation writes to Git.
• Choose a policy according to the tag naming: semver for semantic releases, numerical or alphabetical for other tags.
• filterTags on the ImageRepository narrows down the tags being considered.
• A commit bot and a separate branch keep the Git history tidy and safe.
• Use a PR for production so a human stays in final control.

In the next episode, episode 14, we'll discuss Notifications & Alerts — how FluxCD sends notifications to Slack, Discord, or a custom webhook on every event, and how the Alert CRD filters events so they don't flood the team. See you!