GitOps and delivery
Argo CD Image Updater
1.What is Image Updater ?
A controller from argoproj-labs. It watches container registries and bumps the image tag (or digest) of Argo CD Applications. Argo CD then syncs it. Flux users have image automation instead.
- Apps built with Helm, Kustomize or a Plugin (v1.3.0+). Plain YAML and Jsonnet apps are skipped.
- It never touches the Deployment, only the Application source. Argo CD renders the rest.
- Runs in the cluster that holds the Applications (the hub), not in workload clusters.
| v0.x (legacy) | v1.x (now) | |
|---|---|---|
| Config | Annotations on each app | An ImageUpdater CR |
| API | K8s, or Argo CD API + token | Kubernetes API only |
| Last release | v0.18.0 (2025-12-25) | v1.3.0 (2026-08-13) |
Bridge : useAnnotations: true on a ref (v1.1.0+) reads the old annotations, minus PR mode, plugin targets and cosign checks.
Alpha, and says soLabs repo, API
v1alpha1, and the README says not yet for critical production. One replica, polls every 2m.2.How one check works
- Trigger : the 2m timer, a CR spec change, or a registry webhook. Editing an Application does not.
- Match : Applications in the CR's namespace that fit
namePatternandlabelSelectors. - Live ? : the image, registry included, must be in the app's
status., else skipped (unlesssummary. images forceUpdate). - Pick : list tags, filter, the strategy chooses.
- Write : to the Application spec or to Git, plus an
ImagesUpdatedEvent. - Sync : auto-sync rolls it out. Without it the app just shows OutOfSync.
3.The ImageUpdater CR
apiVersion: argocd-image-updater.argoproj.io/v1alpha1
kind: ImageUpdater
metadata: {name: nginx-patches, namespace: argocd}
spec:
applicationRefs:
- namePattern: "web-*" # glob
labelSelectors: {matchLabels: {team: web}}
images:
- alias: nginx
imageName: nginx:1.26.x # a constraint
commonUpdateSettings: {updateStrategy: semver}
manifestTargets:
helm: {name: image.repository, tag: image.tag}
# no writeBackConfig = method argocd
4.Key fields
- applicationRefs : which apps.
namePattern(glob, required), optionallabelSelectors. - images : an
alias(no "/") and animageName, the repo plus a version constraint. - manifestTargets : one of helm, kustomize, plugin. Helm defaults to
image.name/image.tag, most charts wantimage.repository. - commonUpdateSettings : strategy, tag filters, forceUpdate, pullSecret, platforms. At spec, ref or image level, the most specific field wins.
- writeBackConfig : argocd or git, at spec or ref level, never per image.
- imagesVerification : cosign public key check (v1.3.0+).
5.Matching rules
- A CR only sees Applications in its own namespace.
spec.namespacewas removed in v1.2.0, using it fails. - Inside one CR the most specific ref wins : an exact name beats a glob, labels add weight.
- One CR per Application. Two CRs on one app overwrite each other every cycle.
In short : One namespaced ImageUpdater CR picks Applications and images, the alpha controller polls registries every 2m, and it writes the newest allowed tag back for Argo CD to sync.
1.The tag is a constraint
For semver, the tag in imageName is a version range (Masterminds semver), not the version you run today.
| Tag | Means | Picks |
|---|---|---|
| nginx:1.26.3 | Exact pin | Never moves |
| nginx:1.26 | ~1.26, so >=1.26.0 <1.27.0 | Newest 1.26.z |
| nginx:1.26.x | Any 1.26 patch | 1.26.3 (5 of 1209 fit) |
| nginx:1.x | Any 1.y.z | Newest 1.y.z |
| nginx | * : no pre-releases (v1.3.0+) | Newest, even a new major |
| app:2.x-0 | 2.x with pre-releases | rc and beta too |
2.The pin trap
- Writing today's version pins it forever, with no error.
- Two doc examples do it :
nginx:1.17.10(PR mode) andbackend:1.0.0(cosign sample). 1.27.5-alpinecounts as a pre-release, so a plain range skips it. Tags that are not semver are skipped too.- Before v1.3.0 an empty tag could jump to
-rctags.
3.Filters first, then the strategy
All tagsfrom the registry
allowTagskeeps matches
ignoreTagsdrops glob hits
Strategysorts what is left
Last one winsif not already live
4.Tag filters
- allowTagsOne string,
regexp:<expr>orany. Empty allows all, a bare regex matches nothing. Unanchored : add^and$. - ignoreTagsAn array of globs, a plain string is rejected.
["*"]pauses the image. - platformsAn array. Default is the controller's own OS / arch, so an amd64 controller with arm64 nodes needs it (newest-build, digest).
images:
- alias: myimage
imageName: some/image # no range here
commonUpdateSettings:
updateStrategy: newest-build
allowTags: "regexp:^[0-9a-f]{7}$"
ignoreTags: ["latest", "master"]
platforms: ["linux/amd64", "linux/arm64"]
5.Four update strategies
| Strategy | Old name | Picks | Tag means | Registry work |
|---|---|---|---|---|
| semver (default) | - | Highest version in the range | The range | Tag list, cached |
| newest-build | latest | Newest image creation date | Nothing, use allowTags | A manifest per tag |
| alphabetical | name | Last tag in byte order | Nothing, use allowTags | Tag list, cached |
| digest | - | Digest of one mutable tag, writes tag@sha256: | The tag to watch | A manifest every cycle |
- Old names still work, with a warning. A typo like
boguspasses the API server and runs semver. calverexists on master only.
- newest-build uses the build date, not the push date. On a tie lexical order decides, so
latestcan win. - alphabetical :
2026-9-01sorts above2026-10-03.
6.Write-back : argocd vs git
| argocd (default) | git | git + PR (v1.2.0+) | |
|---|---|---|---|
| Writes | Application spec, via the K8s API | A commit on the branch | A new branch plus a GitHub PR or GitLab MR |
| Changes | Helm parameters, Kustomize images, plugin env | ., kustomization or values | Same files, after review |
| Creds | None, RBAC on Applications | Argo CD repo creds or git:secret:<name> | HTTPS token or GitHub App, no SSH |
| Lasts ? | No : a re-created app, app-of-apps or ApplicationSet can revert it | Yes, it is in Git | Yes, once merged |
In short : The tag is a range, filters run before the strategy, and argocd write-back is quick but fragile while git keeps the bump.
1.Git and pull request write-back
Clonethe app's repo
Write targetone file per app
Commitskipped if no change
Push or PRbranch, PR or MR
Argo CD syncsa tracked branch
spec:
writeBackConfig:
method: git:secret:git-creds # Secret here
gitConfig:
branch: main # base only
writeBackTarget: helmvalues:/helm/values.yaml
pullRequest: {github: {}} # or gitlab
- (no target)
<path>/., merged by Argo CD at render time.argocd-source-<app>. yaml - kustomizationEdits the images in
kustomization.. Takes a directory, not a file.yaml - helmvaluesEdits a values file. Bare means
<path>/.values. yaml
Plain method: git reuses Argo CD's repo creds. A git:secret: Secret must sit in the CR's namespace.
- Argo CD deploys only the branch the app tracks. Tracking
HEAD, a tag or a SHA ? SetgitConfig.branch. Amain:<tpl>write branch is force-pushed, PR mode refuses it.
2.Alpha : sharp edges in v1.3.0
- Registry auth (issue 1797) : if
/v2/answers without auth but repos need it (zot), creds are never sent. Every cycle gets 401. The fix (PR 1801) is on master only. - Stored defaults : a ref or image
commonUpdateSettingsblock is saved withupdateStrategy: semver. Repeat your strategy in every block. - READY lies :
Ready=Truecan sit next toError=True. git:secret:SSH or password creds skip host-key and TLS checks.
3.What changed when
| Version | What changed |
|---|---|
| v1.0.0 | CR replaces annotations |
| v1.2.0 | spec.namespace gone, PR mode, status |
| v1.3.0 | Plugin apps, cosign, Secrets in the CR's namespace, PR branch renamed |
| master | Auth fix, no stored defaults, calver |
No Argo CD or Kubernetes version matrix is published. CHANGELOG.md is stale, read the GitHub release notes.
4.Image Updater vs Flux vs Renovate
| Image Updater | Flux image automation | Renovate | |
|---|---|---|---|
| Runs | In the cluster, beside Argo CD | In the cluster, two controllers | In CI, outside the cluster |
| Config | One CR, v1alpha1 | Three CRs, v1 since Flux v2.7.0 | Config file, argocd manager opt-in |
| Finds images | App params, kustomization | Setter comments in any YAML | Manifests in Git |
| Writes | App spec (no Git), commit or PR | Always a Git commit | Pull requests |
| Rule of thumb | Argo CD shop | Flux shop, plain YAML | Review every bump |
5.Commands
| Command | What it does |
|---|---|
kubectl apply -n argocd -f https://raw.githubusercontent.com/ | Install CRD, RBAC and controller next to Argo CD (or the argo/ chart) |
kubectl apply --dry-run=server -f iu.yaml | Check a CR against the CRD rules, catches a string ignoreTags |
kubectl get imageupdater [<name> -o yaml] -n argocd | APPS, IMAGES, LAST CHECKED, READY. The YAML shows the stored updateStrategy and the Error condition |
kubectl -n argocd logs deploy/ | Logs. Set log.level: debug in the ConfigMap, then restart |
argocd-image-updater test nginx --semver-constraint 1.27 | Try a range, writes nothing : nginx:1.27.5. Needs a kubeconfig |
kubectl patch imageupdater <name> -n argocd --type merge -p '{"metadata":{"finalizers":null}}' | Drop the finalizer of a CR stuck Terminating after the controller went first |
In short : Use git write-back for bumps that must last, read the Error condition and not just READY, and mind the v1.3.0 registry-auth bug.