DOCSEARCHbyAlgolia
Submit Docs

Argo CD Image Updater Documentation

repository·master·Indexed 23 days ago

https://github.com/argoproj-labs/argocd-image-updater

A tool that automates updating container image tags in Argo CD managed applications. It monitors registries and applies updates via Argo CD parameter overrides or Git commits. Supports Kustomize, Helm, and Plugin application types. Includes a registry-scanner Go library for inspecting OCI and Docker registries, a webhook server for event-driven updates, and the argocd-git-ask-pass credential helper.

Tokens
37.8K
Snippets
89
Records
183
Agent score
82%

What's inside Argo CD Image Updater

  1. Overview of the Registry Scanner library

    master
    The registry-scanner is a reusable Go library designed for inspecting OCI and Docker registries. It allows users to inspect registry contents and fetch specific images based on configured constraints or strategies. It is intended to be used as a standalone component that can be integrated into other projects independently of the full Argo CD Image Updater.

  2. Overview of Argo CD Image Updater

    master

    Argo CD Image Updater is a tool designed to automatically update container images for Kubernetes workloads managed by Argo CD.

    It operates by using a dedicated ImageUpdater Custom Resource (CR) to define how to track and update image versions for specific Argo CD Applications. When a new image version is detected, the tool updates the application using one of two methods:

    1. Argo CD API: Setting parameter overrides directly via the API.
    2. Git Write-back: Committing changes to a Git repository by writing Parameter Overrides rather than modifying the application's original manifests.

    Supported Application Types: Currently, the tool only supports applications built using:

    • Kustomize
    • Helm
    • Plugin (Config Management Plugin)

    Note: Applications built from plain YAML are not currently supported.

  3. When to configure a custom registry

    master

    Argo CD Image Updater automatically infers the registry from the image slug (e.g., ghcr.io/somerepo/someimage uses https://ghcr.io/v2). You only need to configure a custom registry if:

    • TLS/SSL Issues: Your registry uses self-signed or non-publicly known TLS certificates, and you need to disable verification or provide a custom CA certificate.
    • Non-standard API Endpoints: The registry's API endpoint is at a different location than the image prefix (note: Docker Hub's quirk is already handled).
    • Custom Settings: You need to apply specific settings like a custom rate limit or global credentials for that specific registry.
    • Default Registry Overrides: Your cluster uses a registry other than docker.io as the default when no prefix is specified.

  4. Hierarchical configuration for ImageUpdater

    master

    Configuration settings (like commonUpdateSettings and writeBackConfig) follow a hierarchical override pattern. More specific levels override more general ones:

    1. Global level: Defined in spec.commonUpdateSettings or spec.writeBackConfig. Applies to all applications.
    2. Application level: Defined in spec.applicationRefs[].commonUpdateSettings or spec.applicationRefs[].writeBackConfig. Overrides global settings for matched applications.
    3. Image level: Defined in spec.applicationRefs[].images[].commonUpdateSettings. Overrides both global and application settings for a specific image.
    spec:
  # 1. Global level
  commonUpdateSettings:
    updateStrategy: "semver"
  writeBackConfig:
    method: "argocd"
  applicationRefs:
    - namePattern: "production-*"
      # 2. Application level override
      commonUpdateSettings:
        updateStrategy: "newest-build"
        forceUpdate: true
      images:
        - alias: "app"
          imageName: "myregistry/myapp:stable"
          # 3. Image level override
          commonUpdateSettings:
            updateStrategy: "newest-build"
        - alias: "database"
          imageName: "postgres:13"

  5. How Argo CD Image Updater updates Git repositories

    master

    Since version v0.9.0 (and requiring Argo CD v1.9.0 or later), Argo CD Image Updater can commit changes directly to Git.

    Instead of modifying your application's source manifests (which could cause conflicts), it writes Parameter Overrides to the repository. This approach ensures that the desired state is stored in Git while minimizing the risk of breaking the original manifest structure.

  6. Requirements and limitations for updating images

    master

    To use Argo CD Image Updater, your setup must meet the following requirements:

    • Argo CD Management: Applications must be managed by Argo CD.
    • Manifest Rendering: The tool can only update images for applications rendered using Helm, Kustomize, or a Config Management Plugin.
      • For Helm, templates must support specifying the image tag/name via parameters (e.g., image.tag).
      • For Plugins, you must use manifestTargets.plugin (reading from env vars) or manifestTargets.helm/manifestTargets.kustomize with the Git write-back method.
    • Secrets Access: Image pull secrets must exist in the same Kubernetes cluster where Argo CD Image Updater is running (or be accessible to it).

  7. How application selection specificity works

    master

    When multiple applicationRefs rules match the same application, ImageUpdater uses a specificity-based selection algorithm. It sorts all rules by specificity and selects the first match for each application.

    Specificity Ranking Factors:

    1. Exact matches: Highest priority.
    2. Label selectors: Add significant bonus points to the score.
    3. Literal characters: More literal characters in a namePattern increase the score.
    4. Wildcards: Patterns like app-* are less specific than app-prod-* because they have fewer literal characters.

    Warning: Multiple ImageUpdater Resource Conflicts If two different ImageUpdater CRs target the same application (e.g., one with namePattern: "app-1" and another with namePattern: "app-*"), they will conflict and cause the application to "thrash" between different image versions. Ensure each application is targeted by only one ImageUpdater CR.

  8. Test multi-arch image support with `--platforms`

    master

    By default, the test command considers images for the same platform as the system running the command. If you are running on a platform (like darwin) that does not have native images in the registry, the test may yield no results.

    You can manually specify target platforms using the --platforms flag to simulate different environments.

  9. Set a default container registry

    master

    By default, Argo CD Image Updater uses docker.io (Docker Hub). If your cluster's container engine uses a different default registry, you must configure it in the registries configuration to prevent workload breakage.

    To set a different default, set the default property to true for that registry. Warning: You can only configure exactly one registry as the default. If multiple registries have default: true, the configuration will fail to load.

    registries:
- name: RedHat Quay
  api_url: https://quay.io
  prefix: quay.io
  default: true

  10. Configure namespace watching and leader election

    master

    The controller's scope and high-availability settings are controlled via namespace and leader election flags.

    Namespace Watching (--watch-namespaces): Controls which namespaces the controller watches for ImageUpdater CRs:

    • Not set (default): Watches only the controller's own namespace. Requires Role + RoleBinding in that namespace.
    • *: Watches all namespaces (cluster-scoped). Requires ClusterRole + ClusterRoleBinding.
    • ns1,ns2,...: Watches specific namespaces. Requires Role + RoleBinding in each specified namespace.

    Leader Election:

    • --leader-election: Enables leader election for the controller manager to ensure only one active instance is running.
    • --leader-election-namespace: The namespace used for the leader election lease. If running locally, this must be set.

    Important Note on RBAC: If you set --leader-election-namespace to a namespace other than the one where the controller is installed, you must manually create the argocd-image-updater-leader-election-role Role and its RoleBinding in that target namespace.

  12. How Argo CD Image Updater works

    master

    Argo CD Image Updater operates via a reconciliation loop that monitors ImageUpdater custom resources (CRs). The process follows these steps:

    1. Application Matching: The controller identifies Argo CD Application resources in its namespace by matching them against applicationRefs (using name patterns or label selectors) defined in the ImageUpdater CR.
    2. Image Configuration: For each matched application, the controller applies image configurations (image name, update strategy, allowed/ignored tags, platform requirements).
    3. Deployment Verification: The controller performs a strict check to ensure the image configured in the ImageUpdater CR is actually the one currently deployed in the Argo CD Application. It compares the complete image name, including the registry (e.g., docker.io/some/image is distinct from quay.io/some/image).
    4. Registry Check: If eligible, the controller connects to the container registry to find newer versions based on the configured update strategy and constraints.
    5. Update Execution: If a newer version is found, the controller uses the configured update method to re-configure the Argo CD Application source with the new tag.

    Note: Argo CD Image Updater does not modify your Git manifests. It re-configures the Argo CD Application resource itself, handing control back to Argo CD to perform the sync.