Demo Image Automation Controller Update

In this lesson you’ll use Flux’s ImageUpdateAutomation to automatically update manifests in a Git repository with the latest image tag and have Flux apply the change to your Kubernetes cluster. High-level flow:

An ImageRepository scans a container registry for tags.
An ImagePolicy resolves the desired tag (for example, latest patch).
ImageUpdateAutomation checks out the Git repo, updates the marked image string in the manifests, commits the change, and pushes it back to the repository.
Flux (GitRepository + Kustomize/Helm/manifest controllers) picks up the update and rolls out the new image in-cluster.

Benefits:

Automated image promotions from registry to manifests to cluster.
Auditable Git commits for image updates.
Fine-grained control via ImagePolicy and inline markers in manifests.

1) View the CLI help for ImageUpdateAutomation

Use the flux CLI to inspect usage, flags, and examples:

root ~/block-buster/flux-clusters/dev-cluster  main
➤ flux create image update -h
The create image update command generates an ImageUpdateAutomation resource.
An ImageUpdateAutomation object specifies an automated update to images
mentioned in YAMLs in a git repository.

Usage:
  flux create image update [name] [flags]

Examples:
  # Configure image updates for the main repository created by flux bootstrap
  flux create image update flux-system \
    --git-repo-ref=flux-system \
    --git-repo-path="./clusters/my-cluster" \
    --checkout-branch=main \
    --author-name=flux \
    --author-email=flux@example.com \
    --commit-template="{{range .Updated.Images}}{{println .}}{{end}}"

# Configure image updates to push changes to a different branch; the branch will be created if it doesn't exist

Tip: The CLI examples show the commit template and branch options you can use to control commit messages and the branch that receives automated updates.

2) ImageUpdateAutomation resource

Create an ImageUpdateAutomation resource that points at a Flux GitRepository (Source) and the path inside that repository where manifests should be updated. Example YAML:

apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: 8-demo-image-update-bb-app
  namespace: flux-system
spec:
  git:
    checkout:
      ref:
        branch: 8-demo
    commit:
      author:
        email: fluxcdbot@users.noreply.github.com
        name: fluxcdbot
    push:
      branch: 8-demo
  interval: 1m40s
  sourceRef:
    kind: GitRepository
    name: 8-demo-source-git-bb-app
  update:
    path: ./manifests
    strategy: Setters

Explanation of important fields

Field	Purpose	Example / Notes
`spec.git.checkout.ref.branch`	Branch to check out for making updates	`8-demo`
`spec.git.commit.author`	Commit author metadata used for automated commits	`fluxcdbot <fluxcdbot@users.noreply.github.com>`
`spec.git.push.branch`	Branch to push the updates to (created if missing)	`8-demo`
`spec.sourceRef`	The Flux `GitRepository` resource that represents the repo to update	`kind: GitRepository`, `name: 8-demo-source-git-bb-app`
`spec.update.path`	Path inside the repo holding manifests to update	`./manifests`
`spec.update.strategy`	Strategy to apply updates (e.g., `Setters`, `Replace` etc.)	`Setters`

Apply this YAML (for example kubectl apply -f image-update.yaml) or use flux create image update to generate and install the resource.

3) GitRepository (Flux Source) that holds manifests

The ImageUpdateAutomation points to a Flux GitRepository source that references the repo and branch being updated. Example GitRepository YAML:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: GitRepository
metadata:
  name: 8-demo-source-git-bb-app
  namespace: flux-system
spec:
  interval: 1m0s
  ref:
    branch: 8-demo
  url: https://github.com/sidd-harth-2/bb-app-source

ImageUpdateAutomation will check out the branch 8-demo and update files under ./manifests in that repository.

4) Mark the exact image line in your manifest

ImageUpdateAutomation needs an inline marker to identify which image string to replace. Add a JSON-style comment on the same line as the image: field to reference an ImagePolicy. Example Deployment manifest (marker on the image line):

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: block-buster
    version: 7.8.x
    env: dev
  name: block-buster
  namespace: 8-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: block-buster
  template:
    metadata:
      labels:
        app: block-buster
    spec:
      containers:
        - name: app
          image: siddharth67/bb-app-flux-demo:7.8.0 # {"$imagepolicy": "flux-system:8-demo-image-policy-bb-app"}
          imagePullPolicy: Always
          resources:
            requests:
              memory: "10Mi"
              cpu: "10m"
            limits:
              memory: "64Mi"
              cpu: "20m"

Key points:

The marker must be on the same line as the image string.
The marker format is a JSON comment such as # {"$imagepolicy": "namespace:policy-name"}. Use inline code formatting when documenting this pattern: # {"$imagepolicy": "namespace:policy-name"}.
The referenced ImagePolicy will control how tags are selected (for example, latest minor/patch).

Keep the JSON marker and the image string on the same line. The marker tells ImageUpdateAutomation which ImagePolicy to consult when resolving the new tag.

5) Check current image scanning and update status

Use flux get images all to inspect image repository scans, policy resolutions, and ImageUpdateAutomation status:

➜ flux get images all
NAME                                              LAST SCAN                   SUSPENDED  READY  MESSAGE
imagerepository/8-demo-image-repo-bb-app          2023-04-06T20:01:09+05:30   False      True   successful scan: found 2 tags

imagepolicy/8-demo-image-policy-bb-app            docker.io/siddharth67/bb-app-flux-demo:7.8.1   True   Latest image tag resolved to 7.8.1

imageupdateautomation/8-demo-image-update-bb-app  2023-04-06T20:00:15+05:30   False      True   no updates made; last commit 487882c at 2023-04-06T14:28:23Z

Possible reasons ImageUpdateAutomation reports “no updates made”:

The manifest already matches the resolved tag (no change required).
The controller could not locate the marker in the file.
An update was required but the controller could not commit/push due to missing authentication.

6) Authentication required: deploy key (SSH) for repository push

If ImageUpdateAutomation finds an update but shows authentication errors, Flux does not have push permissions. Provide Flux a Git deploy key and store the private key in a Kubernetes secret. Example: generate a deploy key secret with the flux CLI (sample uses ECDSA P-521):

root ~/block-buster/flux-clusters/dev-cluster  main
► flux create secret git 8-demo-git-bb-app-auth \
  --url=ssh://git@github.com/sidd-harth-2/bb-app-source.git \
  --ssh-key-algorithm=ecdsa \
  --ssh-ecdsa-curve=p521
+ deploy key: ecdsa-sha2-nistp521 AAAAE2VjZHNhLXNoYTItbm1zdHA1MjEAAAAIBmlzdHA1MjEAAACFBAAigpn8XTCI0AQbVrNiZr5hzbEbM3bxDxVXWlXievZdj/jR5eFiJ8EyrfS4LzbIx6hzLMRYSDXesamDU7dbtwoElwA/NI5wsZSoefzJHPw/Ya9VSq1viLaVDjRBlDqndOm0ygr/DgAoiKKdJ7ON4HgtNUB/WnGyWh/gfu/iKKqr2GH5zw==
► git secret '8-demo-git-bb-app-auth' created in 'flux-system' namespace

root ~/block-buster/flux-clusters/dev-cluster  main
► kubectl -n flux-system get secret 8-demo-git-bb-app-auth
NAME                         TYPE    DATA   AGE
8-demo-git-bb-app-auth       Opaque  3      17s

The command prints a public deploy key (the long string starting with ecdsa-sha2-nistp521 ...). Add this public key to the repository’s Deploy Keys in GitHub and grant write access so Flux can push commits.
The private key is stored in the Kubernetes secret 8-demo-git-bb-app-auth in the flux-system namespace.

When registering the deploy key in GitHub, grant write access (allowing pushes) if you want ImageUpdateAutomation to push commits. Otherwise Flux will be able to read but not write.

When using a deploy key for push access you must use the SSH URL for the repository (ssh://git@github.com/...) and configure the GitRepository to reference the secret that stores the private key.

7) Update the GitRepository resource to use the SSH URL and secretRef

Update (or recreate/export) the GitRepository so Flux clones using SSH and the secret you created: Example command that exports the updated resource:

root ~/block-buster/flux-clusters/dev-cluster  main
▶ flux create source git 8-demo-source-git-bb-app \
  --url 'ssh://git@github.com/sidd-harth-2/bb-app-source.git' \
  --branch 8-demo \
  --timeout 10s \
  --secret-ref 8-demo-git-bb-app-auth \
  --export > 8-demo-source-git-bb-app.yml

Resulting YAML will include secretRef and the SSH URL:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: GitRepository
metadata:
  name: 8-demo-source-git-bb-app
  namespace: flux-system
spec:
  interval: 1m0s
  ref:
    branch: 8-demo
  secretRef:
    name: 8-demo-git-bb-app-auth
  url: ssh://git@github.com/sidd-harth-2/bb-app-source.git

Apply this updated GitRepository so Flux uses the SSH key for authenticated operations.

8) Reconcile and confirm updates

After you:

Add the image marker to the Deployment manifest,
Create the deploy key secret and add the public key to GitHub with write access, and
Update the GitRepository to reference the SSH URL and secret,

ImageUpdateAutomation should:

Resolve the latest tag via the ImagePolicy,
Update the marked image line in the manifest,
Commit the change using the configured author identity,
Push the commit to the specified branch.

Commands to confirm status and rollout:

# Confirm image policy resolution and repository scans
➜ flux get images all

# Confirm ImageUpdateAutomation last run and message
➜ flux get images update
NAME                         LAST RUN                   SUSPENDED   READY   MESSAGE
8-demo-image-update-bb-app   2023-04-06T19:58:32+05:30   False       True    no updates made; last commit 487882c at 2023-04-06T14:28:23Z

# Check deployment in the cluster (shows updated image if rollout completed)
➜ kubectl -n 8-demo get deploy block-buster -o wide
NAME          READY  UP-TO-DATE AVAILABLE AGE  CONTAINERS  IMAGES
block-buster  1/1    1         1         51m  app         docker.io/siddharth67/bb-app-flux-demo:7.8.1

If everything is configured correctly, the Deployment will reflect the new image tag that ImagePolicy resolved and ImageUpdateAutomation committed.

A browser window showing an arcade-style "BLOCK BUSTER" game screen with a metadata panel at the top listing pod details (Pod Name, Pod IP, Namespace, K8S Node, App Version). The main play area displays "PRESS START" with level/score indicators across the top and a green "START GAME" button at the bottom.

Summary

Use ImageRepository to scan registry tags and ImagePolicy to resolve which tag to use.
Create an ImageUpdateAutomation that references your GitRepository source and the path to the manifests.
Mark the manifest image line with an inline JSON comment that references the ImagePolicy: # {"$imagepolicy": "namespace:policy-name"}.
If ImageUpdateAutomation must push commits, provide Flux push credentials (deploy key) and configure the GitRepository to use the SSH URL and secretRef.
Monitor with flux get images all and flux get images update, and verify the Deployment image with kubectl.

Links and references

Flux Image Update Automation documentation: https://fluxcd.io/docs/components/image/automation/
Flux Image Toolkit docs: https://fluxcd.io/docs/components/image/
GitHub deploy keys: https://docs.github.com/en/developers/overview/managing-deploy-keys
Kubernetes Deployments: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/

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 Image Automation Controller Update

1) View the CLI help for ImageUpdateAutomation

2) ImageUpdateAutomation resource

3) GitRepository (Flux Source) that holds manifests

4) Mark the exact image line in your manifest

5) Check current image scanning and update status

6) Authentication required: deploy key (SSH) for repository push

7) Update the GitRepository resource to use the SSH URL and secretRef

8) Reconcile and confirm updates

Summary

Watch Video

Practice Lab

​1) View the CLI help for ImageUpdateAutomation

​2) ImageUpdateAutomation resource

​3) GitRepository (Flux Source) that holds manifests

​4) Mark the exact image line in your manifest

​5) Check current image scanning and update status

​6) Authentication required: deploy key (SSH) for repository push

​7) Update the GitRepository resource to use the SSH URL and secretRef

​8) Reconcile and confirm updates

​Summary

Watch Video

Practice Lab

1) View the CLI help for ImageUpdateAutomation

2) ImageUpdateAutomation resource

3) GitRepository (Flux Source) that holds manifests

4) Mark the exact image line in your manifest

5) Check current image scanning and update status

6) Authentication required: deploy key (SSH) for repository push

7) Update the GitRepository resource to use the SSH URL and secretRef

8) Reconcile and confirm updates

Summary