Stage 4 · Provision

Continuous Delivery & GitOps

Flux Image Automation

ImageRepository, ImagePolicy, ImageUpdateAutomation, and Git-based promotion — automating container image updates.

7 min readInfrastructure as CodeProvision

What Is Image Automation?

Flux Image Automation detects new container images and commits the updated tag to Git. This completes the GitOps loop — image updates flow through the same pipeline as code changes. No manual image tag bumps or CI pipeline triggers.

The system has three components: ImageRepository (scans registries), ImagePolicy (selects which tag to use), and ImageUpdateAutomation (commits changes to Git). Together they automate the entire image promotion workflow.

ImageRepository

ImageRepository manifest


apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: webapp
  namespace: flux-system
spec:
  image: ghcr.io/org/webapp
  interval: 1m
  secretRef:
    name: ghcr-credentials
  excludeFilterExpReg: ".*windows.*"
  selectionPolicy: semver
  provider: generic

The ImageRepository polls the container registry at the specified interval. secretRef provides authentication for private registries. excludeFilterExpReg filters out unwanted tags. selectionPolicy determines how tags are ranked.

ImageRepository for multiple tags


apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: webapp
spec:
  image: ghcr.io/org/webapp
  interval: 5m
  selectionPolicy: semver
  extractionProgress:
    enabled: true

The ImageRepository automatically discovers all tags. The extractionProgress field enables progress tracking for large registries. SelectionPolicy semver sorts tags by semantic version.

ImagePolicy

Semver policy


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"

The semver policy selects the latest tag matching the range. The range >=1.0.0 <2.0.0 accepts any 1.x.y release. This is the most common policy — it automatically picks up patch and minor updates.

Alphabetical and numerical policies


# Numerical policy — latest tag as a number
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: webapp-numerical
spec:
  imageRepositoryRef:
    name: webapp
  policy:
    numerical:
      order: asc

# Alphabetical policy — latest tag alphabetically
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: webapp-alpha
spec:
  imageRepositoryRef:
    name: webapp
  policy:
    alphabetical:
      order: asc

Numerical policy sorts tags as numbers — useful for build numbers (100, 101, 102). Alphabetical policy sorts lexicographically — useful for date-based tags (20240101, 20240102). Semver is preferred when tags follow semver.

ImageUpdateAutomation

ImageUpdateAutomation manifest


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
      email: fluxcdbot@example.com
      message: " automated: update image {{range .Updated.Images}}{{println .}}{{end}}"
    push:
      branch: main
  update:
    path: ./apps
    strategy: Setters

The ImageUpdateAutomation controller watches ImagePolicies and commits changes to Git. The commit message includes the updated images. The strategy Setters uses annotations in the manifest files to identify which images to update.

Semver Policies

Range	Accepts	Blocks
>=1.0.0 <2.0.0	1.0.0, 1.5.3, 1.9.9	0.9.0, 2.0.0
>=1.0.0	1.0.0, 2.0.0, 3.0.0	0.9.0
>=1.0.0 <1.5.0	1.0.0, 1.4.9	1.5.0, 2.0.0
>=1.0.0 <1.1.0	1.0.0, 1.0.5	1.1.0, 2.0.0

Git-Based Promotion

Deployment with image setter annotation


apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
spec:
  template:
    spec:
      containers:
        - name: webapp
          image: ghcr.io/org/webapp:1.0.0  # {"$imagepolicy": "flux-system:webapp"}

The comment annotation tells Flux which ImagePolicy to use for this container. When the policy detects a new image, Flux updates the image tag in Git and commits the change. Flux then detects the Git change and deploys it.

Multi-image promotion


apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
spec:
  template:
    spec:
      containers:
        - name: webapp
          image: ghcr.io/org/webapp:1.0.0  # {"$imagepolicy": "flux-system:webapp"}
        - name: sidecar
          image: ghcr.io/org/sidecar:1.0.0  # {"$imagepolicy": "flux-system:sidecar"}

Each container can reference a different ImagePolicy. The webapp container follows the webapp policy. The sidecar container follows the sidecar policy. Each image is updated independently.

Test with a dev branch first

Before enabling image automation on main, test with a dev branch. Push the ImageUpdateAutomation to target dev. Verify that commits are created correctly. Then switch to main.

Image automation creates Git commits

Every image update creates a Git commit. For busy registries, this can produce many commits. Use longer intervals (5m or 10m) to batch updates. Configure commit message templates to keep history clean.

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