In a Flux ImageUpdateAutomation, how does the controller know which lines of a YAML manifest to rewrite when a new image tag is selected?

## Why the controller needs to be told A repository full of Kubernetes YAML contains many strings that look like image references — sidecars, init containers, chart values, comments, documentation. An automation that rewrote all of them would be dangerous, and one that guessed which to rewrite would be unpredictable. Flux therefore requires an explicit, per-value opt-in written into the manifest itself. That marker is the entire contract between your repository and the automation. ## The marker A setter marker is a YAML comment placed on the same line as the value it governs: ```yaml spec: template: spec: containers: - name: app image: ghcr.io/org/app:1.2.3 # {"$imagepolicy": "flux-system:app"} ``` The comment body is a small JSON object whose `$imagepolicy` key names an ImagePolicy as `namespace:name`. When that policy's selected image changes, the controller rewrites the value on that line to the policy's current selection — here the full `repository:tag` reference. Because it is a YAML comment, three things follow immediately. The marker survives normal editing and diffs cleanly in review. It cannot be used in a JSON manifest, which has no comments. And it is invisible to Kubernetes itself, which ignores comments entirely. ## Field selectors for split fields Sometimes the repository name and the tag live in different keys. The canonical case is Kustomize's image transformer: ```yaml apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization images: - name: ghcr.io/org/app newName: ghcr.io/org/app # {"$imagepolicy": "flux-system:app:name"} newTag: 1.2.3 # {"$imagepolicy": "flux-system:app:tag"} ``` Appending `:name` or `:tag` to the policy reference tells the controller to write only that component. The same trick handles a Helm values file that keeps `repository:` and `tag:` as separate keys — mark each with the matching selector. ## Path scoping `spec.update.path` bounds the walk. This is a real safety control, not just an optimisation: pointing one ImageUpdateAutomation at `./clusters/staging` means production manifests are never even read by that automation, no matter what markers they contain. A common layout is one automation per cluster directory, each with its own policies, so staging can track every build while production tracks a narrow semver range. ## The failure everyone hits once `Setters` is the strategy, and a file with no marker is not an error. It is simply not a candidate. So the classic symptom is: the ImagePolicy status shows the new image, the ImageUpdateAutomation reconciles successfully every interval, and no commit ever appears. Nothing is red. The cause is almost always one of: - the marker is missing, or was lost when someone reformatted the file; - the marker names the wrong namespace, or a policy name that does not exist — the reference is `namespace:name`, and the namespace is not inferred for you; - the file lies outside `spec.update.path`; - the value being marked is not in the repository at all, because it is generated later. That last point deserves emphasis. Automation edits **files in Git**. If your image tag only appears in output produced at apply time — a chart template rendered by helm-controller, a value injected by a post-build substitution — there is no line in the repository to mark. The fix is to move the tag into a committed file, typically a values file in your repo referenced by the HelmRelease, or the HelmRelease's own inline `spec.values`, and mark it there. ## What the commit looks like When at least one file changes, the controller stages the changes and commits with the identity under `spec.git.commit.author` and the text from `messageTemplate`, then pushes. If nothing changed, there is deliberately no empty commit — which is why a healthy, correctly configured automation is quiet for days at a time and that quiet is not evidence of a problem. ## Verifying without waiting The cheapest check is to grep the repository for `$imagepolicy` and confirm each hit names a policy that `flux get image policy` actually lists, in the namespace spelled in the marker. The second cheapest is to force a run rather than wait for the interval, and read the automation's status message, which reports the commit it pushed or that there was nothing to update.