Image Update Automation

## The gap this fills A CI pipeline builds a container image and pushes it to a registry. Something still has to tell the cluster that a new tag exists. In a push-based pipeline, CI would hold cluster credentials and run a deploy command. Flux's image update automation closes the same loop the other way round: components running *inside* the cluster watch the registry themselves and rewrite the Git manifests, so the change arrives through the same reviewed, versioned path as every other change. Flux deliberately splits that job across three objects rather than one, because scanning, choosing and writing are different concerns with different failure modes and different owners. ## ImageRepository — the scanner `ImageRepository` names a *repository*, never a specific image version: `spec.image: ghcr.io/org/app`. Putting a tag in that field is a common first mistake and the object will be rejected. Other important fields are `spec.interval` (how often to list tags), `spec.secretRef` (a Kubernetes secret holding registry credentials), `spec.provider` for contextual cloud login, and `spec.exclusionList` for tags you never want considered. It is reconciled by **image-reflector-controller**, which caches the tag list and reports in status when it last scanned and how many tags it found. Scanning is polling by default; a notification-controller `Receiver` can also trigger a scan from a registry webhook. ## ImagePolicy — the chooser `ImagePolicy` references a scanner through `spec.imageRepositoryRef` and applies exactly one ordering rule under `spec.policy`: `semver` with a `range`, `numerical` with an `order`, or `alphabetical` with an `order`. An optional `spec.filterTags` narrows the candidate list first with a regular expression. The result is pure computation — the policy changes nothing anywhere. It simply publishes the selected image in its status, and you read it with `flux get image policy`. Separating this from the scanner means several policies can share one scan: production may track `>=1.0.0 <2.0.0` while staging tracks any tag, without listing the registry twice. ## ImageUpdateAutomation — the writer `ImageUpdateAutomation`, reconciled by **image-automation-controller**, is the only object that writes anything. It points at a `GitRepository` source through `spec.sourceRef`, checks out a branch, walks the files under `spec.update.path`, applies `spec.update.strategy: Setters`, and if any file changed it commits using the author and message template under `spec.git.commit` and pushes. ```yaml apiVersion: image.toolkit.fluxcd.io/v1beta1 kind: ImageUpdateAutomation metadata: name: flux-system namespace: flux-system spec: interval: 5m sourceRef: kind: GitRepository name: flux-system git: checkout: ref: branch: main commit: author: name: fluxcdbot email: [email protected] messageTemplate: 'chore: update images' push: branch: main update: path: ./clusters/production strategy: Setters ``` ## Nothing here deploys This is the point candidates miss most often. Image automation produces a **Git commit**, not a cluster mutation. The new tag reaches a Pod only when the Kustomization or HelmRelease that owns those manifests reconciles them in the normal way. That is also why end-to-end latency is a sum of independent intervals: the ImageRepository scan interval, plus the ImageUpdateAutomation interval, plus the deploying Kustomization's interval. It also explains why the design is safe by construction: if someone hand-edits a Deployment in the cluster, the reconciler puts it back, and the record of what should be running is always the file in Git. ## Installation is opt-in Neither controller ships in a default Flux install. You add them at bootstrap: ```bash flux bootstrap github \ --owner=my-org --repository=fleet-infra \ --components-extra=image-reflector-controller,image-automation-controller \ --read-write-key ``` The `--read-write-key` part matters: the default deploy key Flux creates is read-only, and automation has to push. ## Why three objects and not one Besides sharing scans, the split gives you three independently inspectable states. `flux get image repository` tells you whether the registry is reachable and authenticated. `flux get image policy` tells you whether your rule actually matched the tag you expect. `flux get image update` tells you whether a commit was attempted. When automation "does nothing", that ordering is the diagnostic path — and a single fused resource would have hidden which of the three stages stalled.