Skip to main content
This guide shows how to use Flux’s ImagePolicy CRD to select the “latest” image tag from an ImageRepository using a policy (for example, the highest patch version matching a semver range). It assumes you already have an ImageRepository that lists tags from your registry. Open your repository in Visual Studio Code and follow along.

​
Overview

  • ImageRepository discovers and lists tags for an image in a registry.
  • ImagePolicy consumes an ImageRepository’s tag list and resolves a single “latest” image according to a configured policy (semver, alphabetical, numeric, etc.).

​
Create an ImagePolicy

The following ImagePolicy references an existing ImageRepository (named 8-demo-image-repo-bb-app) and selects the highest patch version within the 7.8.x series:
Generate and export the ImagePolicy YAML to your cluster repo (example path used here):
Then commit and push the file to your Flux-managed Git repository so Flux can reconcile it:

​
How the policy selects the image

  • The example uses semver with range 7.8.x. Flux will consider tags where major=7 and minor=8, then pick the highest patch (e.g., 7.8.1 > 7.8.0).
  • Flux supports other policy strategies:
    • semver — semantic version comparison with ranges
    • alphabetical — lexicographic comparison of tags
    • numeric — numeric comparison of tag values
  • You can combine filterTags to restrict which tags are considered (for example, to select release candidates).
Example: basic semver policy
Example: filtering tags (e.g., release candidates)

​
Apply and let Flux reconcile

Once committed to the repository Flux manages, Flux will scan the referenced ImageRepository and resolve the latest image according to your ImagePolicy. Allow some time for the reconciliation loop to run.

​
Inspecting results with the Flux CLI

List discovered repositories and resolved policies:
Example output (imagerepository entry):
Example output (imagepolicy entry):
You can also inspect the ImagePolicy resource directly with kubectl to see status conditions and the resolved tag in the status section:

​
Important: ImagePolicy does not mutate Deployments

Creating an ImagePolicy only resolves which tag is considered “latest” under your policy. It does not update workload manifests or change images in running Deployments by itself. For example, the workload in the 8-demo namespace may still be using tag 7.8.0:
Example output:
To automatically update the image tag in your Git repository (and therefore apply the change to the cluster), you must configure the ImageUpdateAutomation controller and related image automation CRDs. ImageUpdateAutomation watches image policies and image repositories and commits updated manifests back to Git. Wiring ImageUpdateAutomation to ImagePolicy and ImageRepository is covered in separate guides.
ImagePolicy resolves the latest tag per your policy but does not mutate Deployments. To automatically update manifest files (and apply those changes to the cluster via GitOps), configure ImageUpdateAutomation to commit the updated image tags to your Git repository.

Watch Video