Chapter 4. Using Argo CD Image Updater

Argo CD Image Updater automatically updates container image versions for workloads managed by Argo CD. It monitors container registries for new image tags that match configured version constraints and updates applications through Argo CD.

In the Red Hat OpenShift GitOps Operator, Argo CD Image Updater is provided as a productized controller that you enable through the Argo CD custom resource.

The Argo CD Image Updater controller runs a reconciliation loop that continuously watches configured Argo CD applications and queries container registries for newer image versions. When a qualifying new version is discovered, the controller instructs Argo CD to update the application. You define which images to track and what version constraints to enforce by creating ImageUpdater custom resources.

Depending on the Argo CD application sync policy, updated images are either deployed automatically or marked as out of sync for manual approval.

The Image Updater provides the following capabilities:

Image selection and update behavior

Application support

Persistence and Git workflows

Registry integration

Observability

Argo CD Image Updater has the following limitations:

You can enable the Argo CD Image Updater controller for an Argo CD instance by configuring the Argo CD custom resource (CR). The Argo CD Image Updater controller is namespace-scoped by default, watching only the namespace in which it is installed.

By default, the Argo CD Image Updater controller watches only the namespace in which it is installed. To configure the Argo CD Image Updater controller to watch additional namespaces, set the IMAGE_UPDATER_WATCH_NAMESPACES environment variable to a comma-separated list of namespaces.

To configure the Argo CD Image Updater to track and update images for an Argo CD application, you create an ImageUpdater custom resource (CR). The ImageUpdater CR specifies which Argo CD applications to monitor, which images to track, the update strategy to use, and how to write back image updates.

The ImageUpdater CR must reside in the same namespace as the Argo CD applications it references. The controller uses metadata.namespace to determine the namespace in which to search for matching applications.

The following example shows a basic ImageUpdater CR that matches applications whose names start with my-app- and tracks the nginx image with a version constraint of ~1.26, which restricts updates to patch versions within the 1.26 minor release (for example, 1.26.0, 1.26.1, 1.26.2):

apiVersion: argocd-image-updater.argoproj.io/v1alpha1
kind: ImageUpdater
metadata:
  name: my-image-updater
  namespace: openshift-gitops
spec:
  applicationRefs:
    - namePattern: "my-app-*"
      images:
        - alias: "nginx"
          imageName: "nginx:~1.26"

The applicationRefs field in the ImageUpdater custom resource determines which Argo CD applications the Argo CD Image Updater controller monitors. Applications can be selected by name pattern, by label, or by a combination of both.

You can use glob patterns to match application names. The namePattern field supports glob-based selection. An exact name matches a single application, while wildcards match multiple applications.

Example: Using a name pattern with wildcards:

spec:
  applicationRefs:
    - namePattern: "frontend-*"
      images:
        - alias: "nginx"
          imageName: "nginx:~1.26"

You can select applications based on their Kubernetes labels. The labelSelectors field selects applications by their Kubernetes labels, supporting both matchLabels for key-value pairs and matchExpressions for operator-based conditions.

Example: Using label selectors:

spec:
  applicationRefs:
    - labelSelectors:
        matchLabels:
          tier: "frontend"
        matchExpressions:
          - key: env
            operator: In
            values:
              - staging
              - production
      images:
        - alias: "nginx"
          imageName: "nginx:~1.26"

You can combine name patterns and label selectors for more precise application selection. For example, to match only applications whose names start with web- and that have a tier: "frontend" label:

Example: Combining name pattern and label selectors:

spec:
  applicationRefs:
    - namePattern: "web-*"
      labelSelectors:
        matchLabels:
          tier: "frontend"
      images:
        - alias: "nginx"
          imageName: "nginx:~1.26"

Applications can provide image configuration through annotations as an alternative to CR-based configuration. When working with ApplicationSets that generate many Applications, each Application can provide its own image configuration through annotations instead of defining images in the ImageUpdater CR. Set useAnnotations: true on an applicationRef to enable this.

Example: Using annotations for image configuration:

spec:
  applicationRefs:
    - namePattern: "generated-app-*"
      useAnnotations: true

When useAnnotations is enabled, the controller reads image configuration from the argocd-image-updater.argoproj.io/image-list annotation on each matching Application resource.

For that applicationRef, any image configuration defined in the CR is ignored. Only the namePattern and labelSelectors fields remain effective.

Example: Using annotations for image configuration:

spec:
  applicationRefs:
    - namePattern: "*"
      labelSelectors:
        matchLabels:
          image-updater: my-image-updater
      useAnnotations: true

The Argo CD Image Updater supports four strategies for determining which image version to update to. Configure the strategy using the commonUpdateSettings.updateStrategy field.

Example: Using the newest-build strategy with a tag filter:

spec:
  applicationRefs:
    - namePattern: "my-app"
      images:
        - alias: "myimage"
          imageName: "myorg/myimage"
          commonUpdateSettings:
            updateStrategy: "newest-build"
            allowTags: "regexp:^v1\\.0\\.0-[0-9a-zA-Z]+$"

You can control which image tags are eligible for updates using the following parameters:

Example: Tag filtering with allowTags and ignoreTags:

spec:
  applicationRefs:
    - namePattern: "my-app"
      images:
        - alias: "myimage"
          imageName: "myorg/myimage"
          commonUpdateSettings:
            allowTags: "regexp:^v[0-9]+\\.[0-9]+\\.[0-9]+$"
            ignoreTags: "*-rc*"

This example allows only tags matching a specific semantic version pattern and ignores release candidate tags.

The Argo CD Image Updater supports three methods for writing back image updates to your applications: Argo CD API method, Git method, and pull request or merge request method.

The Argo CD API method is the default write-back method and requires no additional configuration. It updates the Argo CD Application resource directly via the Kubernetes API. No additional configuration is required. This method is best suited for applications created imperatively through the Argo CD Web UI or CLI.

The Git method provides persistent storage by committing changes to the application’s Git repository. The Argo CD Image Updater controller fetches the remote repository, checks out the target branch, creates or updates a parameter override file, and commits and pushes the change.

Example: Git write-back method:

spec:
  applicationRefs:
    - namePattern: "my-app"
      images:
        - alias: "nginx"
          imageName: "nginx:~1.26"
  writeBackConfig:
    method: "git"
    gitConfig:
      repository: "https://github.com/myorg/my-app-config.git"
      branch: "main"

To use credentials other than the ones configured in Argo CD, reference a Kubernetes secret:

Example: Git write-back with custom credentials:

spec:
  writeBackConfig:
    method: "git:secret:openshift-gitops/git-creds"
    gitConfig:
      branch: "main"

The Git method supports multiple write-back targets. By default, it creates or updates an .argocd-source-<appName>.yaml file in the application path. For Kustomization applications, you can set the writeBackTarget to kustomization to commit changes as a kustomize edit set image operation. For Helm applications, you can specify a Helm values file path using writeBackTarget: "helmvalues:/helm/config/values.yaml" to update the values file directly.

Example: Kustomization write-back target:

spec:
  writeBackConfig:
    method: "git"
    gitConfig:
      branch: "main"
      writeBackTarget: "kustomization"

Example: Helm values file write-back target:

spec:
  writeBackConfig:
    method: "git"
    gitConfig:
      branch: "main"
      writeBackTarget: "helmvalues:/helm/config/values.yaml"

The pull request or merge request method creates PRs or MRs for review instead of directly committing to the target branch. The PR/MR method extends the Git method by pushing changes to an auto-generated branch and opening a pull request or merge request instead of pushing directly to the target branch. This method is ideal when the target branch is protected or when image updates should go through a review workflow.

The Image Updater pushes the commit to a branch named image-updater-<namespace>-<appName>-<sha256> and opens a pull or merge request from that branch into the configured base branch. If a PR already exists for the same branch pair, no duplicate is created.

Example: GitHub pull request:

spec:
  writeBackConfig:
    method: "git:secret:openshift-gitops/git-creds"
    gitConfig:
      repository: "https://github.com/example/example.git"
      branch: "main"
      pullRequest:
        github: {}

Example: GitLab merge request:

spec:
  writeBackConfig:
    method: "git:secret:openshift-gitops/gitlab-creds"
    gitConfig:
      repository: "https://gitlab.com/org/repo.git"
      branch: "main"
      pullRequest:
        gitlab: {}

For Helm charts that use non-standard parameter names for image references, configure the manifestTargets.helm field in the ImageUpdater custom resource to explicitly map the image parameters.

When replacing one image with another, for example, switching registries, use the manifestTargets.kustomize.name field to identify the original image in the kustomization.

The Argo CD Image Updater works with most container registries that implement the Docker Registry v2 API out of the box. For custom or private registries, you can configure registry settings in the argocd-image-updater-config ConfigMap.

The Image Updater works with the following container registries out of the box:

Per-image pull secrets authenticate with private container registries. The pullSecret field supports the following formats:

Pull secret formats:

By default, the Argo CD Image Updater discovers new image versions by periodically polling container registries. You can also configure webhooks so that registries push notifications to the Image Updater immediately when a new image is available, eliminating the delay between image publication and update.

The webhook server exposes two endpoints:

Registry webhook URLs include a type query parameter that identifies the registry. For example: https://image-updater.example.com/webhook?type=docker.io.

The ImageUpdater custom resource exposes a status subresource with standard Kubernetes conditions that provide information about the operational state of the Argo CD Image Updater controller.

The following example shows a complete ImageUpdater custom resource that tracks two images for a Helm-based application, uses semantic versioning constraints, and writes back updates as pull requests to a GitHub repository. This example demonstrates tracking a frontend image with patch version updates within 2.0, a backend image with minor and patch updates within 1.x using semantic versioning strategy, pull secret authentication, and Git write-back with GitHub pull request creation.

Example: Complete ImageUpdater CR:

apiVersion: argocd-image-updater.argoproj.io/v1alpha1
kind: ImageUpdater
metadata:
  name: my-app-updater
  namespace: openshift-gitops
spec:
  applicationRefs:
    - namePattern: "my-app"
      images:
        - alias: "frontend"
          imageName: "myorg/frontend:~2.0"
          manifestTargets:
            helm:
              name: "frontend.image.repository"
              tag: "frontend.image.tag"
        - alias: "backend"
          imageName: "myorg/backend:^1.5"
          commonUpdateSettings:
            updateStrategy: "semver"
            allowTags: "regexp:^v[0-9]+\\.[0-9]+\\.[0-9]+$"
          manifestTargets:
            helm:
              name: "backend.image.repository"
              tag: "backend.image.tag"
          pullSecret: "pullsecret:openshift-gitops/myregistry-pull-secret"
  writeBackConfig:
    method: "git:secret:openshift-gitops/git-creds"
    gitConfig:
      repository: "https://github.com/myorg/my-app-config.git"
      branch: "main"
      pullRequest:
        github: {}