ArgoCD Image Updater — Automated Container Image Updates

Why Image Updater Matters

Keeping container images up to date is a constant operational burden. New versions are released, security patches become available, and manual updates are tedious and error-prone. ArgoCD Image Updater automates this by watching container registries and automatically updating Kubernetes deployments when new images are available.

Why this matters for your career:

Automated image updates reduce manual toil and speed up deployments
Security patches can be deployed automatically, reducing vulnerability windows
Image updater completes the GitOps automation picture
Understanding image update strategies helps design robust CI/CD pipelines

What Is ArgoCD Image Updater?

ArgoCD Image Updater is a companion tool for ArgoCD that automatically updates container images in Kubernetes workloads. It monitors registries for new image tags and updates the Application manifests accordingly.

How It Works

Image Updater scans the Applications managed by ArgoCD
For each Application with image updater annotations, it checks the configured registry
If a new image version is found (matching the update strategy), it updates the Application's source parameters
The update is written back to Git (or directly to the cluster)
ArgoCD detects the change and syncs the Application

Installation

# Install Image Updater alongside ArgoCD
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/manifests/install.yaml

# Verify installation
kubectl get pods -n argocd -l app.kubernetes.io/name=argocd-image-updater

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

Configuration

Application Annotations

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  annotations:
    # Required: specify images to watch
    argocd-image-updater.argoproj.io/image-list: my-app=ghcr.io/myorg/my-app, sidecar=ghcr.io/myorg/sidecar
    
    # Update strategy per image
    argocd-image-updater.argoproj.io/my-app.update-strategy: semver
    argocd-image-updater.argoproj.io/sidecar.update-strategy: latest
    
    # Allow only stable tags (semver regex)
    argocd-image-updater.argoproj.io/my-app.allow-tags: regexp:^v\\d+\\.\\d+\\.\\d+$
    
    # Keep latest 3 stable versions
    argocd-image-updater.argoproj.io/my-app.keep: 3
    
    # Write changes back to Git
    argocd-image-updater.argoproj.io/write-back-method: git:secret:argocd/image-updater-creds
    
    # Git branch to write to
    argocd-image-updater.argoproj.io/git-branch: main

Update Strategies

| Strategy | Description | Example Tags Matched | |----------|-------------|---------------------| | semver | Follow semantic versioning | v1.2.3 → v1.2.4, v1.3.0, v2.0.0 | | latest | Always use the latest tag | latest → latest | | name | Alphabetically highest tag | v1.0 → v1.1 → v1.2 | | digest | Update when the digest changes | sha256:abc... → sha256:def... | | regexp | Custom regex pattern | Custom pattern defined in allow-tags |

Semver Strategy Details

# Update only patch versions (1.2.x)
argocd-image-updater.argoproj.io/my-app.update-strategy: semver
argocd-image-updater.argoproj.io/my-app.semver-constraint: ^1.2.0  # ^ = compatible with 1.2.x

# Update only minor versions (1.x)
argocd-image-updater.argoproj.io/my-app.semver-constraint: ~1.0.0  # ~ = approximately equivalent

# Allow all semver versions
argocd-image-updater.argoproj.io/my-app.semver-constraint: '*'  # any version

Write-Back Methods

| Method | Description | Use Case | |--------|-------------|----------| | git | Commits changes to the Git repository | GitOps (recommended) | | argocd | Updates Application directly in ArgoCD | Non-GitOps setups | | none | Only logs the update, does not apply | Dry-run, monitoring |

Git Write-Back Setup

# Create a secret with Git credentials
kubectl create secret generic image-updater-creds -n argocd \
  --from-literal=username=<git-username> \
  --from-literal=password=<git-token>

# Reference in annotations (shown above)

Complete Example

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
  annotations:
    argocd-image-updater.argoproj.io/image-list: |
      app=ghcr.io/myorg/my-app
      nginx=ghcr.io/myorg/nginx-sidecar
    argocd-image-updater.argoproj.io/app.update-strategy: semver
    argocd-image-updater.argoproj.io/app.allow-tags: regexp:^v\\d+\\.\\d+\\.\\d+$
    argocd-image-updater.argoproj.io/app.keep: 3
    argocd-image-updater.argoproj.io/nginx.update-strategy: latest
    argocd-image-updater.argoproj.io/write-back-method: git:secret:argocd/image-updater-creds
    argocd-image-updater.argoproj.io/git-branch: main
    argocd-image-updater.argoproj.io/git-user: Image Updater Bot
    argocd-image-updater.argoproj.io/git-email: image-updater@example.com
spec:
  source:
    repoURL: https://github.com/myorg/myapp-config.git
    targetRevision: main
    path: k8s/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: my-app-prod
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Monitoring Image Updates

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

# Check which images were updated
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-image-updater | grep "updated"

# Check the Git commit history
# Each image update produces a commit with message:
# "Updated image my-app to v1.2.4"

Best Practices

| Practice | Reason | |----------|--------| | Use semver strategy for production apps | Controlled, predictable updates | | Use latest only for dev/test | Fast iteration, less stability | | Always use allow-tags with regex | Prevent accidental major version upgrades | | Use keep to retain multiple versions | Quick rollback to any recent version | | Use write-back-method: git | Maintain Git as the single source of truth | | Monitor image updater logs | Detect failures or unexpected updates | | Test image updates in staging first | Validate before promoting to production | | Set up notifications for image updates | Be aware of what changed and when |

Common Issues

| Issue | Cause | Solution | |-------|-------|----------| | Image not updated | Tag doesn't match allow-tags regex | Check regex and tag format | | Git push failed | Invalid credentials | Check the git secret | | Wrong version selected | Semver constraint too broad | Narrow the constraint | | Image updater not running | Not installed or misconfigured | Check pod status and logs | | Write-back to unsupported Git provider | Custom Git server | Use argocd method or configure custom repo |

Summary

ArgoCD Image Updater automates container image updates by monitoring registries and updating Application manifests. With semver strategies, Git write-back, and allow-tags regex, you can control exactly which updates are applied automatically.

Key takeaways:

Image Updater watches registries and updates Applications automatically
Strategies: semver, latest, name, digest, regexp
Use semver with constraints for controlled production updates
Write-back method: git (recommended), argocd, or none (dry-run)
allow-tags regex prevents unwanted updates
keep retains multiple versions for quick rollback
Monitor logs to track what was updated and why
Test image updates in staging before production

What's Next: Full GitOps Pipeline

The next chapter combines everything into a complete GitOps pipeline — CI (GitHub Actions) + CD (ArgoCD) + Image Updater + multi-environment promotion.