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)
ConfigAnnotations on each appAn ImageUpdater CR
APIK8s, or Argo CD API + tokenKubernetes API only
Last releasev0.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

  1. Trigger : the 2m timer, a CR spec change, or a registry webhook. Editing an Application does not.
  2. Match : Applications in the CR's namespace that fit namePattern and labelSelectors.
  3. Live ? : the image, registry included, must be in the app's status.summary.images, else skipped (unless forceUpdate).
  4. Pick : list tags, filter, the strategy chooses.
  5. Write : to the Application spec or to Git, plus an ImagesUpdated Event.
  6. Sync : auto-sync rolls it out. Without it the app just shows OutOfSync.
Registry Docker Hub, GHCR ImageUpdater CR, v1alpha1 list tags, 2m webhook (optional) reads Image Updater controller, 1 replica argocd (default) git or PR Application spec.source params Git repo commit or PR spec changed new commit Argo CD renders and syncs sync Deployment new image

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), optional labelSelectors.
  • images : an alias (no "/") and an imageName, the repo plus a version constraint.
  • manifestTargets : one of helm, kustomize, plugin. Helm defaults to image.name / image.tag, most charts want image.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.namespace was 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.

TagMeansPicks
nginx:1.26.3Exact pinNever moves
nginx:1.26~1.26, so >=1.26.0 <1.27.0Newest 1.26.z
nginx:1.26.xAny 1.26 patch1.26.3 (5 of 1209 fit)
nginx:1.xAny 1.y.zNewest 1.y.z
nginx* : no pre-releases (v1.3.0+)Newest, even a new major
app:2.x-02.x with pre-releasesrc 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) and backend:1.0.0 (cosign sample).
  • 1.27.5-alpine counts 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 -rc tags.

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> or any. 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

StrategyOld namePicksTag meansRegistry work
semver (default)-Highest version in the rangeThe rangeTag list, cached
newest-buildlatestNewest image creation dateNothing, use allowTagsA manifest per tag
alphabeticalnameLast tag in byte orderNothing, use allowTagsTag list, cached
digest-Digest of one mutable tag, writes tag@sha256:The tag to watchA manifest every cycle
  • Old names still work, with a warning. A typo like bogus passes the API server and runs semver.
  • calver exists on master only.
  • newest-build uses the build date, not the push date. On a tie lexical order decides, so latest can win.
  • alphabetical : 2026-9-01 sorts above 2026-10-03.

6.Write-back : argocd vs git

argocd (default)gitgit + PR (v1.2.0+)
WritesApplication spec, via the K8s APIA commit on the branchA new branch plus a GitHub PR or GitLab MR
ChangesHelm parameters, Kustomize images, plugin env.argocd-source-<app>.yaml, kustomization or valuesSame files, after review
CredsNone, RBAC on ApplicationsArgo 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 itYes, it is in GitYes, 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>/.argocd-source-<app>.yaml, merged by Argo CD at render time.
  • kustomizationEdits the images in kustomization.yaml. Takes a directory, not a file.
  • 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 ? Set gitConfig.branch. A main:<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 commonUpdateSettings block is saved with updateStrategy: semver. Repeat your strategy in every block.
  • READY lies : Ready=True can sit next to Error=True.
  • git:secret: SSH or password creds skip host-key and TLS checks.

3.What changed when

VersionWhat changed
v1.0.0CR replaces annotations
v1.2.0spec.namespace gone, PR mode, status
v1.3.0Plugin apps, cosign, Secrets in the CR's namespace, PR branch renamed
masterAuth 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 UpdaterFlux image automationRenovate
RunsIn the cluster, beside Argo CDIn the cluster, two controllersIn CI, outside the cluster
ConfigOne CR, v1alpha1Three CRs, v1 since Flux v2.7.0Config file, argocd manager opt-in
Finds imagesApp params, kustomizationSetter comments in any YAMLManifests in Git
WritesApp spec (no Git), commit or PRAlways a Git commitPull requests
Rule of thumbArgo CD shopFlux shop, plain YAMLReview every bump

5.Commands

CommandWhat it does
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/config/install.yamlInstall CRD, RBAC and controller next to Argo CD (or the argo/argocd-image-updater chart)
kubectl apply --dry-run=server -f iu.yamlCheck a CR against the CRD rules, catches a string ignoreTags
kubectl get imageupdater [<name> -o yaml] -n argocdAPPS, IMAGES, LAST CHECKED, READY. The YAML shows the stored updateStrategy and the Error condition
kubectl -n argocd logs deploy/argocd-image-updater-controllerLogs. Set log.level: debug in the ConfigMap, then restart
argocd-image-updater test nginx --semver-constraint 1.27Try 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.