Skip to main content

​
ArgoCD Image Updater

ArgoCD Image Updater is a tool to automatically update container image versions in ArgoCD applications. It monitors container registries for new image tags and updates the corresponding manifests in Git or directly in the cluster.

​
Purpose

Image Updater enables automated deployments by:
  • Monitoring registries for new image versions (e.g., GitHub Container Registry)
  • Updating applications automatically when new images are pushed
  • Integrating with GitOps workflows to maintain declarative state
  • Supporting multiple strategies (semver, latest, regex patterns)
This is particularly useful in development environments where applications are frequently updated.

​
Configuration

From nixidy/env/local/image-updater.nix: 
applications.image-updater = {
  namespace = "argocd";
  createNamespace = false;

  helm.releases.argocd-image-updater = {
    chart = charts.argoproj.argocd-image-updater;

    values = {
      config.registries = [
        {
          name = "GitHub Container Registry";
          prefix = "ghcr.io";
          api_url = "https://ghcr.io";
          credentials = "secret:argocd/ghcr-credentials#token";
        }
      ];
    };
  };
};

​
Registry Configuration

The image updater is configured to monitor GitHub Container Registry (ghcr.io):
  • Name: GitHub Container Registry
  • Prefix: ghcr.io
  • API URL: https://ghcr.io
  • Credentials: Stored in Kubernetes secret ghcr-credentials in the argocd namespace

​
Deployment

Deployed via ArgoCD in the argocd namespace alongside the main ArgoCD controller.

​
Namespace

namespace: argocd

​
Helm Chart

Uses the official ArgoCD Image Updater chart from the Argoproj repository: 
chart: charts.argoproj.argocd-image-updater
Chart version is pinned via flake.lock to ensure reproducibility.

​
Usage

​
Annotating Applications

To enable automatic image updates for an ArgoCD application, add annotations to the Application manifest: 
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  annotations:
    # Enable image updater
    argocd-image-updater.argoproj.io/image-list: myapp=ghcr.io/org/my-app
    
    # Update strategy (semver, latest, digest, name, regex)
    argocd-image-updater.argoproj.io/myapp.update-strategy: semver
    
    # Semver constraint (optional)
    argocd-image-updater.argoproj.io/myapp.semver-constraint: "~1.0"
    
    # Pull secret for private registry (optional)
    argocd-image-updater.argoproj.io/myapp.pull-secret: pullsecret:argocd/ghcr-credentials

​
Update Strategies

StrategyDescriptionExample
semverSemantic versioningv1.2.3 → v1.2.4
latestAlways use latest taglatest
digestUpdate by digest@sha256:abc...
nameLexical sort by name20240301 → 20240302
regexCustom regex patternMatch custom patterns

​
Example: Semver Updates

annotations:
  argocd-image-updater.argoproj.io/image-list: api=ghcr.io/hackz-megalo-cup/api-service
  argocd-image-updater.argoproj.io/api.update-strategy: semver
  argocd-image-updater.argoproj.io/api.semver-constraint: "^1.0.0"
This will automatically update from 1.0.0 → 1.0.1 → 1.1.0 but not to 2.0.0.

​
Example: Latest Tag

annotations:
  argocd-image-updater.argoproj.io/image-list: dev-app=ghcr.io/org/dev-app:latest
  argocd-image-updater.argoproj.io/dev-app.update-strategy: latest

​
Setting Up Registry Credentials

For private registries, create a secret with registry credentials: 
# Create secret for GitHub Container Registry
kubectl create secret generic ghcr-credentials \
  -n argocd \
  --from-literal=token=ghp_your_github_token_here
The token should have read:packages scope for reading from GHCR.

​
Monitoring Image Updater

​
Check Image Updater Logs

kubectl logs -n argocd -l app.kubernetes.io/name=argocd-image-updater -f

​
View Update Status

Image Updater adds annotations to Application resources to track update status: 
kubectl get application my-app -n argocd -o yaml | grep image-updater
Look for annotations like:
  • argocd-image-updater.argoproj.io/image-last-update - Last update timestamp
  • argocd-image-updater.argoproj.io/write-back-method - How updates are applied

​
Write-Back Methods

Image Updater can update images in two ways:

​
1. ArgoCD (default)

Updates the image parameter directly in ArgoCD (override): 
argocd-image-updater.argoproj.io/write-back-method: argocd
Pros: Fast, no Git commit required
Cons: Drift from Git source

​
2. Git

Commits changes back to the Git repository: 
argocd-image-updater.argoproj.io/write-back-method: git
argocd-image-updater.argoproj.io/git-branch: main
Pros: Maintains GitOps principles, auditable
Cons: Requires write access to repository, slower

​
Integration with ApplicationSet

Image Updater works with ArgoCD ApplicationSet to manage multiple applications: 
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: microservices
spec:
  template:
    metadata:
      annotations:
        argocd-image-updater.argoproj.io/image-list: "app=ghcr.io/org/{{name}}"
        argocd-image-updater.argoproj.io/app.update-strategy: semver

​
Configuration Options

​
Update Interval

Image Updater checks for new images every 2 minutes by default. Adjust via: 
values:
  config:
    interval: 5m  # Check every 5 minutes

​
Log Level

values:
  config:
    log.level: debug  # trace, debug, info, warn, error

ArgoCD

GitOps continuous delivery

GitOps Architecture

Complete GitOps workflow

Manifest Generation

Nixidy manifest generation

​
Troubleshooting

​
Image Not Updating

Check these common issues:
  1. Registry credentials: Verify secret exists and has correct token 
    kubectl get secret ghcr-credentials -n argocd
  2. Application annotations: Ensure annotations are correct 
    kubectl get application my-app -n argocd -o yaml | grep image-updater
  3. Image Updater logs: Check for errors 
    kubectl logs -n argocd -l app.kubernetes.io/name=argocd-image-updater
  4. Registry API: Test registry API access 
    # From inside a pod in the cluster
curl https://ghcr.io/v2/

​
Force Immediate Check

Restart the image updater to force an immediate check: 
kubectl rollout restart deployment argocd-image-updater -n argocd

​
Disable for Specific Application

Remove the image-updater annotations: 
kubectl annotate application my-app -n argocd \
  argocd-image-updater.argoproj.io/image-list- \
  argocd-image-updater.argoproj.io/myapp.update-strategy-

​
Best Practices

  1. Use semver in production - Prevents unexpected breaking changes
  2. Test in dev first - Use latest strategy in dev, semver in prod
  3. Set constraints - Use semver constraints to control update scope
  4. Monitor updates - Check logs regularly for update failures
  5. Git write-back - Use Git write-back method for production to maintain audit trail
  6. Limit update frequency - Avoid checking too frequently to reduce API rate limits

Build docs developers (and LLMs) love

Get started for freeTalk to us