Getting Started with Argo CD Image Updater: Practical Guide

What Is Argo CD Image Updater?

Argo CD Image Updater automates updating container images in GitOps workflows. It tracks, fetches, and deploys new container image versions to ensure deployments use the latest or specified versions. By automatically updating image versions in Git repositories, the Image Updater helps maintain an efficient deployment pipeline.

By integrating with the Argo CD continuous delivery platform, the Image Updater reduces manual intervention, improving efficiency and reducing errors in production environments. This tool is useful for teams using Kubernetes, addressing the need to keep applications up to date without constant oversight. 

Argo CD Image Updater Features 

Argo CD Image Updater provides several features that automate updating container images in Kubernetes environments managed by Argo CD:

• Automated image updates: The tool can automatically update container images based on the latest available versions. By polling configured applications and querying container registries, Argo CD Image Updater ensures that applications are always running with the most up-to-date images.
• Flexible update strategies: It supports various update strategies, allowing users to choose how the images are updated. These include:
  • semver: Updates to the highest allowed version according to semantic versioning constraints.
  • latest/newest-build: Updates to the most recently created image tag (this strategy has been renamed from latest to newest-build).
  • name/alphabetical: Updates to the last tag in an alphabetically sorted list.
  • digest: Updates to the most recent pushed version of a mutable tag (this strategy has been renamed from name to alphabetical).
• Integration with Argo CD: The tool integrates tightly with Argo CD, supporting features such as Sync Windows and role-based access control (RBAC). This ensures that the image update process respects the policies and permissions configured within Argo CD.
• Support for multiple registries: Argo CD Image Updater can interact with widely used container registries, including both public and private registries. It allows the use of custom pull secrets to access private registries, supporting various authentication methods such as Kubernetes secrets, environment variables, and external scripts.
• GitOps compliance: The tool can be configured to write changes back to Git, ensuring that the GitOps model is maintained. This feature helps in keeping the Git repository as the single source of truth for the application’s desired state.
• Scalability and flexibility: It can run within a Kubernetes cluster or as a standalone command-line tool. It also supports parallel updates of multiple applications, improving efficiency in large-scale deployments.

How the Argo CD Image Updater Works 

Argo CD Image Updater automates updating container images in Kubernetes applications managed by Argo CD. It starts by scanning for Argo CD applications configured with specific annotations that list the images to be updated. This scanning can be done through either the Kubernetes API or the Argo CD API, depending on the installation method. 

Once it identifies the relevant applications, the Image Updater checks the images listed in the argocd-image-updater.argoproj.io/image-list annotation. For each image, it verifies whether the image is actually deployed by matching the complete image name, including the registry information. If there is a newer version of an image that meets the configured update criteria, it updates the application to use the new image tag. 

The Image Updater does not directly modify the Kubernetes manifests; instead, it adjusts the application sources, allowing Argo CD to manage the deployment of the new image. The tool also supports multi-architecture images, ensuring compatibility with clusters that have nodes of different architectures. 

To ensure smooth updates, it’s recommended to enable automatic syncing in Argo CD, which allows the application to immediately deploy the new image version once updated by the Image Updater. 

Update Methods

Argo CD Image Updater supports two primary methods to propagate new image versions to Argo CD-managed applications: argocd and git. These methods, often referred to as write-back methods, determine how changes are applied and stored.

argocd Write-Back Method (Not Recommended for Production)

The argocd method directly modifies the Argo CD application resource by interacting with either the Kubernetes API or the Argo CD API, depending on the Image Updater’s configuration. This method updates the application by setting new parameters that prompt Argo CD to re-render the manifests with the updated image details.

It is pseudo-persistent, meaning that changes made using the argocd method are not stored in the Git repository. If the application resource is deleted and recreated, or if the Git version of the application is re-synced, the changes will be lost. This method is most suitable for applications that are managed imperatively, such as those created through the Argo CD web UI or CLI. However, this method is not recommended for production setups.

git Write-Back Method (Recommended for Production Use)

The git method is used for more persistent updates. It commits the new image details directly into the Git repository that holds the application’s manifests. By doing so, it ensures that the changes are permanently stored and can be tracked alongside the rest of the application’s configuration.

For this method to work, the application must be configured to track a branch rather than a specific commit or tag, as this allows Argo CD to detect and apply the changes after the Image Updater has committed and pushed the updates. The changes are typically stored in a .argocd-source-<appName>.yaml file within the repository, which Argo CD uses to re-render the application manifests.

This method requires additional configuration, particularly if using custom credentials or specifying a non-default branch for committing changes. It also supports updating Kustomization files for applications managed by Kustomize. This is the recommended method for production use.

Update Strategies

Argo CD Image Updater supports a variety of update strategies to help manage how new image versions are identified and applied to Kubernetes applications. These strategies allow users to choose the most appropriate method for keeping container images up to date. Here are the key update strategies supported by Argo CD Image Updater:

• semver (semantic versioning): The default option, focusing on updating images that follow semantic versioning rules. Tags must include version identifiers in the format X.Y.Z, where X, Y, and Z are integers. This strategy can specify constraints, such as only updating within a particular minor version (e.g., 1.2.x) or major version (e.g., 1.x). It is suitable for stable updates within controlled version ranges.
• latest/newest-build: Updates the image to the most recently built version available in the container registry. It relies on the build date rather than the tag’s creation date, making it useful for pipelines that produce images with tags like commit SHAs or arbitrary strings. However, it’s important to note that if reproducible builds are used where the build date does not change, this strategy may not work as intended. 
• digest: Tracks updates based on the SHA digest of a specific tag, such as latest. It is useful for managing mutable tags that change frequently, ensuring that the application always runs the most recent image associated with a given tag. The digest strategy updates the image by its unique digest (e.g., sha256:<hash>), decoupling the application from the mutable tag name.
• name/alphabetical: Sorts image tags alphabetically and selects the one with the highest cardinality for the update. This approach can be useful for images that use date-based versioning (e.g., YYYY-MM-DD). By default, all tags are considered, but developers can apply filters to focus on specific tag patterns.

Note: The latest strategy has been renamed to newest-build, and name has been renamed to alphabetical. At the time of this writing the old names are still supported, but support will be removed in future releases, so it’s important to transition existing code to the new names.

Authentication in Argo CD Image Updater

Argo CD Image Updater requires authentication to access various external systems, including Kubernetes, Argo CD, and container registries. Properly configuring these authentication mechanisms is crucial for the tool to function correctly in updating container images.

Authentication to Kubernetes

When Argo CD Image Updater runs as a Kubernetes workload, it typically operates in the Kubernetes API access mode, using a ServiceAccount token mounted to its pod. The ServiceAccount, named argocd-image-updater, is created during installation and is linked to an appropriate Role via a RoleBinding, granting the necessary permissions to interact with the Kubernetes API. 

By default, no additional configuration is needed if Argo CD Image Updater is installed in the argocd namespace. However, if Argo CD is installed in a different namespace, the RoleBinding must be adjusted to bind to the correct namespace.

Authentication to Argo CD

For cases where Argo CD Image Updater needs to interact with Argo CD through its API instead of the Kubernetes API, appropriate credentials must be set up in Argo CD. This involves creating a local user in Argo CD with API access, generating an API token, and configuring RBAC permissions for that user. 

Once these credentials are in place, they must be provided to the Image Updater, which will then use them to authenticate against the Argo CD API. This setup is particularly important when the Image Updater is configured to connect to Argo CD directly rather than through the Kubernetes API.

Authentication to Container Registries

When dealing with private registries or private repositories within public registries, Argo CD Image Updater must authenticate to these registries to pull container images. Authentication credentials can be configured at the registry level or on a per-image basis, providing flexibility in managing access:

• Pull secrets: These are Kubernetes secrets that contain a .dockerconfigjson field with the credentials formatted as JSON. They are typically used for Docker registries and can be referenced by specifying the namespace and secret name.
• Generic secrets: Argo CD Image Updater can also use generic Kubernetes secrets where credentials are stored in a configurable field in the format <username>:<password>. These can be useful when the same credentials are used across multiple registries.
• Environment variables: Credentials can also be provided through environment variables, useful for testing or for setups where environment variables are mounted from secrets.
• External scripts: In scenarios requiring dynamic or short-lived credentials, such as with AWS ECR, Argo CD Image Updater can execute a script to generate the required credentials. The script must output the credentials in the format <username>:<password> and must be executable within the container.

Related content: Read our guide to Argo Kubernetes

Installing Argo CD Image Updater 

Argo CD Image Updater can be installed using different methods depending on the environment and requirements. These instructions are adapted from the official documentation.

Method 1: Installing as a Kubernetes Workload in Argo CD Namespace

The simplest method is to install Argo CD Image Updater as a Kubernetes workload within the same namespace where Argo CD is running. This ensures integration and minimal configuration.

To install the Image Updater, use the following command:

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

This command applies the installation manifests, creating the necessary resources in the argocd namespace.

Configuration Tips:

• Logging: To help with troubleshooting during initial setup, you can set a more verbose log level by editing the argocd-image-updater-config ConfigMap:
• High availability: It’s recommended to run only one replica of Argo CD Image Updater to avoid unexpected behavior.

data:
  log.level: debug

After setting the desired log level, you may need to restart the Image Updater pod for the changes to take effect:

kubectl -n argocd rollout restart deployment argocd-image-updater

Method 2: Connecting Using Argo CD API Server

If running Argo CD Image Updater in the same Kubernetes cluster is not feasible, you can configure it to connect to the Argo CD API server from a different cluster or environment. This method requires that the Argo CD API is exposed externally, typically through an Ingress.

1. First, create a dedicated namespace for the Image Updater:

kubectl create namespace argocd-image-updater

2. Then, apply the installation manifests:

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

Now you can start configuring API access:

3. API user setup: You need to create a local user in Argo CD with appropriate API permissions. Add the user definition in the argocd-cm ConfigMap:

First, create a dedicated namespace for the Image Updater:

data:
  accounts.image-updater: apiKey

4. Generate an API token for this user with the following command:

argocd account generate-token --account image-updater --id image-updater

5. RBAC configuration: Grant the necessary RBAC permissions by editing the argocd-rbac-cm ConfigMap:

p, role:image-updater, applications, get, */*, allow
p, role:image-updater, applications, update, */*, allow
g, image-updater, role:image-updater

This configuration allows the image-updater user to get and update all applications managed by Argo CD.

6. Next, start configuring connection settings. If you need to connect to Argo CD from another cluster or with specific connection parameters, edit the argocd-image-updater-config ConfigMap:

data:
  argocd.server_addr: <FQDN or Argo CD server IP>
  argocd.grpc_web: "true"
  argocd.insecure: "false"
  argocd.plaintext: "false"

7. After making these changes, restart the Image Updater pod:

kubectl -n argocd-image-updater rollout restart deployment argocd-image-updater

Running Multiple Instances

While you can run multiple instances of Argo CD Image Updater in the same Kubernetes cluster, ensure that each instance manages different sets of applications to avoid conflicts:

• Deploy each instance in its own namespace.
• Use separate API users and RBAC configurations to prevent cross-interference between instances.

Codefresh: An Argo-Based CI/CD Platform

The Codefresh platform, powered by Argo, combines the best of the open-source with an enterprise-grade runtime allowing you to fully tap the power of Argo Workflows, Events, CD, and Rollouts. It provides teams with a unified GitOps experience to build, test, deploy, and scale their applications.

You can use Codefresh for your platform engineering initiative either as a developer portal or as the machinery that takes care of everything that happens in the developer portal. Your choice depends on how far your organization has adopted Kubernetes and micro-services

Codefresh is a next-generation CI/CD platform designed for cloud-native applications, offering dynamic builds, progressive delivery, and much more.

Ready to Get Started?

Deploy more and fail less with Codefresh and Argo

Sign Up