How does Flux image automation work with ImageRepository, ImagePolicy, and ImageUpdateAutomation?

Think of Flux image automation like a personal shopper who monitors store shelves for you. The ImageRepository is the shopper walking through the store aisles (scanning the container registry) and noting every product version available. The ImagePolicy is your shopping list with preferences — you want the latest version that matches a specific pattern, like anything in the 3.x range but not pre-release builds. The ImageUpdateAutomation is the shopper placing the selected item in your cart and checking out — it writes the chosen image tag back into your Git repository, which then triggers the normal Flux GitOps reconciliation to deploy the updated image to your cluster.

The ImageRepository resource tells the Flux image-reflector-controller which container registry and repository to scan. You configure the registry URL, the scan interval, and optionally an access credentials secret for private registries. The controller periodically queries the registry API to enumerate all available tags for the specified image. For large repositories with hundreds or thousands of tags, you can configure tag filtering using exclusionList to skip irrelevant tags like latest or cache, and you can set a canonical image name to normalize multi-registry images. The scanned tags are stored in an internal database and exposed through the ImageRepository status, which other Flux resources can reference. This separation of concerns means multiple ImagePolicy resources can reference the same ImageRepository but apply different selection criteria.

The ImagePolicy resource defines the selection logic for choosing which tag to use. It references an ImageRepository and applies a policy consisting of an optional filterTags regex pattern and a required policy type. The three policy types are semver, which interprets tags as semantic versions and selects based on a version range like >=3.0.0 <4.0.0; alphabetical, which sorts tags lexicographically and picks the first or last; and numerical, which sorts tags as numbers. The semver policy is the most commonly used because it integrates naturally with release versioning practices. The filterTags field narrows the candidate set before the policy is applied — for example, filtering tags that match the pattern ^main-[a-f0-9]+-(?P<ts>[0-9]+) to extract a timestamp capture group that the numerical policy can sort on. The selected tag is stored in the ImagePolicy status and made available for downstream automation.

The ImageUpdateAutomation resource connects the selected image tags back to your Git repository. It specifies a Git source, a branch to update, a commit message template, and the author information for the automated commits. The Flux image-automation-controller reads all ImagePolicy resources in its scope, scans the specified Git checkout path for YAML files containing special marker comments in the format {"$imagepolicy": "namespace:policy-name"} or {"$imagepolicy": "namespace:policy-name:tag"}, and replaces the adjacent image reference with the tag selected by the corresponding ImagePolicy. This marker-based approach means you control exactly which image references get updated — it does not blindly update every occurrence of an image name. The controller then commits the changes to Git with the configured commit message and pushes, which triggers the normal Flux source reconciliation to pick up the new commit and deploy the updated images.

In production, teams running services like shipping-service and user-auth-service typically configure ImageRepositories for each service's container image, create ImagePolicies with semver ranges that match their release strategy (for example, >=2.0.0 <3.0.0 for a stable v2 release train), and deploy a single ImageUpdateAutomation per cluster or per tenant that handles all image updates. A critical production consideration is separating the image automation branch from the main deployment branch to avoid infinite reconciliation loops — the automation pushes to a dedicated branch that is then merged via pull request, adding a human review gate. Another common pitfall is failing to configure registry credentials properly for private ECR, GCR, or ACR registries, which causes silent scan failures. Teams should also be aware that high-frequency image pushes combined with short scan intervals can create excessive Git commits, so tuning the scan interval and using filterTags to exclude CI build tags from non-release branches is essential for keeping the Git history clean.