Skip to content

ArgoCD Image Updater

Companion to ArgoCD that watches container registries for new image tags and automatically updates running deployments when a newer image is available.

How it works

Image Updater runs as a Deployment in the cluster. On a configurable interval (default: 2 minutes) it:

  1. Reads all ArgoCD Application objects that have Image Updater annotations
  2. Queries the configured registry for new tags matching the version constraint
  3. If a newer tag is found, triggers a rollout — but only when the image actually changes, not on a timer

This means no surprise restarts: Vaultwarden only restarts when there is actually a new release.

Write-back modes

Image Updater supports two write-back modes, configured per Application via annotation.

argocd (no git required)

Image Updater stores the new image tag directly on the ArgoCD Application object as a parameter override. ArgoCD then syncs the live deployment to match.

argocd-image-updater.argoproj.io/write-back-method: argocd

The resolved tag is stored in spec.source.helm.parameters (for Helm apps) or as an argocd app set parameter override (for plain manifests). It survives pod restarts because it lives on the Application object in the cluster. It does not commit anything to git — the repo always shows the original tag, but the running image is overridden.

Tradeoff: the override is invisible in git. If you delete and re-create the Application, Image Updater will re-apply the override on its next cycle, but there is a brief window where the old tag from git is used.

git (full GitOps)

Image Updater commits the updated tag back to the git repository. ArgoCD then syncs from git as normal.

argocd-image-updater.argoproj.io/write-back-method: git

Requires a git credential secret with write access to the repo. The committed change is a small .argocd-source-<app>.yaml file or a direct patch to kustomization.yaml, depending on the app type.

Install

kubectl apply -n argocd -f \
  https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/manifests/install.yaml

Or as an ArgoCD Application (recommended — keeps it self-managed):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argocd-image-updater
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://argoproj-labs.github.io/argocd-image-updater
    chart: argocd-image-updater
    targetRevision: "*"
    helm:
      values: |
        config:
          argocd:
            serverAddress: https://argocd-server.argocd.svc.cluster.local
            insecure: true
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Example: Vaultwarden with argocd write-back

Annotate the ArgoCD Application manifest:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: vaultwarden
  namespace: argocd
  annotations:
    argocd-image-updater.argoproj.io/image-list: vaultwarden=vaultwarden/server:~1
    argocd-image-updater.argoproj.io/vaultwarden.update-strategy: semver
    argocd-image-updater.argoproj.io/write-back-method: argocd
spec:
  ...
  • image-list — declares an alias (vaultwarden) mapped to the Docker Hub image. ~1 means "latest 1.x release".
  • update-strategy: semver — only update to a newer semver tag, never downgrade.
  • write-back-method: argocd — store the resolved tag on the Application object, no git needed.

Pin the deployment to a real tag (not :latest) — Image Updater will manage it from here:

image: vaultwarden/server:1.32.0

Image Updater will detect 1.32.1 (or whatever the latest is) within 2 minutes and patch the running deployment automatically.

Checking status

# See what Image Updater has resolved
kubectl -n argocd get application vaultwarden -o jsonpath='{.operation}'

# Image Updater logs
kubectl -n argocd logs -l app.kubernetes.io/name=argocd-image-updater --tail=50

Notes

  • Image Updater needs RBAC to read and patch ArgoCD Application objects — the upstream install manifest includes this
  • Docker Hub has a rate limit (100 pulls/6h unauthenticated). For many apps, configure a registry secret with credentials to avoid hitting it
  • ~1 (semver minor constraint) is usually right for Vaultwarden — tracks latest 1.x.y without jumping to a potential breaking 2.0