Demo Install Image Automation Controller

In this lesson we upgrade an existing Flux installation to add the Image Reflector and Image Automation controllers. These controllers let Flux read image metadata from registries and automatically update your Git repository with newer image tags according to configured policies. Prerequisites:

A Kubernetes cluster with Flux already bootstrapped (the example uses the flux-system namespace).
Access to the Git repository you used to bootstrap Flux (e.g., a GitHub repo) and a token with repo permissions if required.

Inspect an example Kustomization manifest that exists in the repository:

apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: 7-demo-kustomize-oci-bb-app-7-7-0
  namespace: flux-system
spec:
  dependsOn:
  - name: infra-database-kustomize-git-mysql
  healthChecks:
    kind: Deployment

Check current Flux controllers running in the flux-system namespace:

kubectl -n flux-system get deploy

Example output (your times/ages will vary):

NAME                         READY   UP-TO-DATE   AVAILABLE   AGE
helm-controller              1/1     1            1           18h
kustomize-controller         1/1     1            1           18h
notification-controller      1/1     1            1           18h
source-controller            1/1     1            1           18h

Why you need extra controllers

Flux does not enable image controllers by default. To automate image scanning and Git updates you must add:
- image-reflector-controller — reads image metadata from registries and exposes it as ImageRepository resources.
- image-automation-controller — updates your Git repository (or other configured sources) with newer image tags according to policies.

Controller responsibilities

Controller	Purpose	Example resource type
image-reflector-controller	Reads registry metadata and publishes available tags	`ImageRepository`
image-automation-controller	Updates manifests in Git (or other sources) with new tags	`ImageUpdateAutomation`

Install (or upgrade) the image controllers using flux bootstrap. Use the --components-extra flag to request additional controllers alongside the defaults.

A screenshot of the Flux documentation site in a browser, with the left navigation menu visible and the main content showing options/code text where "image-reflector-controller" is highlighted.

Example bootstrap/upgrade command Replace owner, repository, path, and the token with values appropriate for your environment. You can store your token in an environment variable (recommended).

flux bootstrap github \
  --owner=your-github-owner \
  --repository=your-repo \
  --branch=main \
  --path=./flux-clusters/dev-cluster/flux-system \
  --components-extra=image-reflector-controller,image-automation-controller \
  --personal \
  --token="$GITHUB_TOKEN"

Using --components-extra accepts a comma-separated list (no spaces) for extra controllers. If Flux components already exist, flux bootstrap upgrades or reconciles them as needed.

Common outputs during installation When the bootstrap completes you should see reconciliation and health checks such as:

◐ waiting for Kustomization "flux-system/flux-system" to be reconciled
✓ Kustomization reconciled successfully
► confirming components are healthy
✓ helm-controller: deployment ready
✓ image-automation-controller: deployment ready
✓ image-reflector-controller: deployment ready
✓ kustomize-controller: deployment ready
✓ notification-controller: deployment ready
✓ source-controller: deployment ready
✓ all components are healthy

Verify the new controllers are running:

kubectl -n flux-system get po,deploy

Example output:

NAME                                             READY   STATUS    RESTARTS       AGE
pod/helm-controller-644cc6fdfb-tn7kw             1/1     Running   3 (105m ago)   18h
pod/image-automation-controller-949478c65-smbbl  1/1     Running   0               27s
pod/image-reflector-controller-5f75cf5799-t9zzx  1/1     Running   0               27s
pod/kustomize-controller-7f65556bf5-n6c67        1/1     Running   3 (105m ago)   18h
pod/notification-controller-57fb4fcb68-c8lnl     1/1     Running   3 (105m ago)   18h
pod/source-controller-7c8f5fbf68-rfnv4           1/1     Running   3 (105m ago)   18h

NAME                                               READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/helm-controller                    1/1     1            1           18h
deployment.apps/image-automation-controller        1/1     1            1           27s
deployment.apps/image-reflector-controller         1/1     1            1           27s
deployment.apps/kustomize-controller               1/1     1            1           18h
deployment.apps/notification-controller            1/1     1            1           18h
deployment.apps/source-controller                  1/1     1            1           18h

Verify CRDs The image controllers install new CRDs so you can declare image-related resources. Confirm they were added:

kubectl get crds | grep image

Example output:

imagepolicies.image.toolkit.fluxcd.io                   2023-04-06T13:23:41Z
imagerepositories.image.toolkit.fluxcd.io               2023-04-06T13:23:41Z
imageupdateautomations.image.toolkit.fluxcd.io          2023-04-06T13:23:41Z

What changes in your Git repo After the operation, Flux updates the manifests in your repository to reflect the installed components. For example, part of gotk-components.yaml may include the image controllers in the header comment:

---
# This manifest was generated by flux. DO NOT EDIT.
# Flux Version: v0.41.2
# Components: source-controller,kustomize-controller,helm-controller,notification-controller,image-reflector-controller,image-automation-controller
apiVersion: v1
kind: Namespace
metadata:
  labels:
    app.kubernetes.io/instance: flux-system
    app.kubernetes.io/part-of: flux
    app.kubernetes.io/version: v0.41.2
  name: flux-system
---

Fetch the changes locally:

git status
git pull

Example git status and git pull output after the upgrade:

# git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

# git pull
remote: Enumerating objects: 18, done.
remote: Counting objects: 100% (18/18), done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 12 (delta 5), reused 7 (delta 0), pack-reused 0
Unpacking objects: 100% (12/12), done.
From https://github.com/your-org/your-repo
   9b16147..003b28c  main       -> origin/main
Updating 9b16147..003b28c
Fast-forward
 flux-clusters/dev-cluster/flux-system/gotk-components.yaml | 1389 ++++++++++++++++++++++++++++++++++++++++++
 flux-clusters/dev-cluster/flux-system/gotk-sync.yaml       |   4 +-
 2 files changed, 1390 insertions(+), 3 deletions(-)

Keep your Git token secure. Avoid committing tokens to source control and prefer using environment variables (e.g., GITHUB_TOKEN) or secret managers when running bootstrap commands.

Next steps

Create ImageRepository resources to point at container registries.
Define ImagePolicy resources to select tags (semantic versioning, regex, etc.).
Add ImageUpdateAutomation resources to define how Flux should update the Git repo (e.g., commit message, path, and push method).

References

Flux documentation: https://fluxcd.io
GitOps with Flux: https://fluxcd.io/docs/installation/

GitOps Overview

Flux Overview

Source and Kustomize Controller

Helm Controller and OCI Registry

Image Automation Controller

Secret Management & Sign Verification

Notification Controller

Monitoring & User Interface

Demo Install Image Automation Controller

Watch Video