ArgoCD Image Updater Skill

ArgoCD Image Updater is a tool that automates updating container images of Kubernetes workloads managed by Argo CD. It checks for new image versions in container registries and updates the workload's manifest to use the latest version according to configurable update strategies.

Quick Reference Installation (Basic) kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/config/install.yaml

Installation with Helm helm repo add argo https://argoproj.github.io/argo-helm helm install argocd-image-updater argo/argocd-image-updater -n argocd

Core Concepts Update Strategies Strategy Description Use Case semver Semantic versioning with constraints Production apps with version control newest-build Most recently built image CI/CD pipelines, dev environments digest Track mutable tags via SHA digest When using latest or other mutable tags alphabetical Lexical sort (CalVer, custom schemes) Calendar versioning, custom schemes Update Methods (Write-Back) Method Description Persistence argocd Updates via Argo CD API (default) Pseudo-persistent (survives restarts) git Commits changes to Git repository Permanent (requires Argo CD v2.0+) ImageUpdater CRD (v1.0.0+)

The recommended configuration approach uses the ImageUpdater Custom Resource Definition:

apiVersion: argocd-image-updater.argoproj.io/v1alpha1 kind: ImageUpdater metadata: name: my-image-updater namespace: argocd spec: namespace: argocd commonUpdateSettings: updateStrategy: "semver" forceUpdate: false applicationRefs: - namePattern: "my-app-*" images: - alias: "myimage" imageName: "myregistry/myimage"

Update Strategies Configuration Semver Strategy

Best for production applications with semantic versioning:

spec: applicationRefs: - namePattern: "production-*" images: - alias: "app" imageName: "myregistry/app:1.x" commonUpdateSettings: updateStrategy: "semver"

Semver Constraints:

1.x or 1.* - Any 1.x.x version 1.2.x - Any 1.2.x version

=1.0.0 <2.0.0 - Range constraints ~1.2.3 - Patch-level changes (>=1.2.3 <1.3.0) ^1.2.3 - Minor-level changes (>=1.2.3 <2.0.0) Newest-Build Strategy

For CI/CD pipelines where you want the most recently pushed image:

spec: applicationRefs: - namePattern: "dev-*" images: - alias: "app" imageName: "myregistry/app" commonUpdateSettings: updateStrategy: "newest-build"

Digest Strategy

Track mutable tags (like latest) via their SHA digest:

spec: applicationRefs: - namePattern: "staging-*" images: - alias: "app" imageName: "myregistry/app:latest" commonUpdateSettings: updateStrategy: "digest"

Alphabetical Strategy

For CalVer or custom versioning schemes:

spec: applicationRefs: - namePattern: "calver-*" images: - alias: "app" imageName: "myregistry/app" commonUpdateSettings: updateStrategy: "alphabetical"

Git Write-Back Configuration

For permanent, GitOps-native updates:

apiVersion: argocd-image-updater.argoproj.io/v1alpha1 kind: ImageUpdater metadata: name: my-image-updater namespace: argocd spec: namespace: argocd writeBackConfig: method: "git" gitConfig: repository: "git@github.com:myorg/myrepo.git" branch: "main" writeBackTarget: "helmvalues:./values.yaml" applicationRefs: - namePattern: "my-app-*" images: - alias: "nginx" imageName: "nginx:1.20" manifestTargets: helm: name: "image.repository" tag: "image.tag"

Write-Back Targets Target Description .argocd-source-.yaml Default, creates parameter override file kustomization Updates kustomization.yaml helmvalues: Updates specified Helm values file Authentication Registry Authentication with Kubernetes Secret apiVersion: v1 kind: Secret metadata: name: docker-registry-secret namespace: argocd type: kubernetes.io/dockerconfigjson data: .dockerconfigjson:

Reference in ImageUpdater:

spec: registries: - name: myregistry prefix: myregistry.example.com credentials: pullsecret:argocd/docker-registry-secret

Git Credentials for Write-Back apiVersion: v1 kind: Secret metadata: name: git-creds namespace: argocd type: Opaque stringData: username: git password:

Annotations Reference (Legacy)

For applications not using ImageUpdater CRD:

metadata: annotations: argocd-image-updater.argoproj.io/image-list: myimage=myregistry/myimage argocd-image-updater.argoproj.io/myimage.update-strategy: semver argocd-image-updater.argoproj.io/myimage.allow-tags: regexp:^[0-9]+.[0-9]+.[0-9]+$ argocd-image-updater.argoproj.io/write-back-method: git

Common Operations Check Image Updater Logs kubectl logs -n argocd -l app.kubernetes.io/name=argocd-image-updater -f

Force Update Check kubectl rollout restart deployment argocd-image-updater -n argocd

List Managed Applications kubectl get applications -n argocd -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.argocd-image-updater.argoproj.io/image-list}{"\n"}{end}'

Verify ImageUpdater CRDs kubectl get imageupdaters -n argocd kubectl describe imageupdater -n argocd

Troubleshooting Common Issues

Images not updating

Check logs for authentication errors Verify registry credentials are correct Ensure application is managed by Argo CD Check if update strategy matches your tagging scheme

Git write-back failing

Verify Git credentials secret exists Check branch name is correct Ensure repository URL is accessible Verify SSH key or token has write permissions

Wrong image version selected

Review update strategy configuration Check tag filtering rules (allow-tags, ignore-tags) Verify semver constraints are correct Debug Commands

Check Image Updater status

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

View detailed logs

kubectl logs -n argocd deployment/argocd-image-updater --tail=100

Check ImageUpdater CR status

kubectl get imageupdater -n argocd -o yaml

Namespace Scoping

The spec.namespace field in ImageUpdater CRD controls which namespace to discover Argo CD Applications from.

Single Namespace (Default) spec: namespace: argocd # Only discover Applications in argocd namespace

Multi-Namespace Patterns

For multi-tenant clusters where Applications exist in multiple namespaces:

Option 1: Deploy separate ImageUpdater CRs per namespace

apiVersion: argocd-image-updater.argoproj.io/v1alpha1 kind: ImageUpdater metadata: name: team-a-updater namespace: argocd spec: namespace: team-a-apps # Scope to team-a's Application namespace applicationRefs: - namePattern: "*"

apiVersion: argocd-image-updater.argoproj.io/v1alpha1 kind: ImageUpdater metadata: name: team-b-updater namespace: argocd spec: namespace: team-b-apps # Scope to team-b's Application namespace

Cross-Namespace Secrets

When ImageUpdater runs in argocd namespace but needs secrets from other namespaces:

Registry credentials: Use pullsecret:NAMESPACE/SECRET-NAME format Git credentials: Reference secrets with full namespace path RBAC: Grant ImageUpdater's ServiceAccount access via RoleBindings in target namespaces

Example: Grant secrets access in team-a namespace

apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: image-updater-secrets namespace: team-a # Target namespace with secrets roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: secret-reader subjects: - kind: ServiceAccount name: argocd-image-updater namespace: argocd # ImageUpdater's namespace

Best Practices Use specific version constraints - Avoid overly broad semver constraints in production Implement tag filtering - Use allow-tags/ignore-tags to exclude unwanted versions Use Git write-back for production - Ensures changes are tracked in Git Separate registries by environment - Different credentials for dev/staging/prod Monitor Image Updater logs - Set up alerting for update failures Test updates in staging first - Use different update policies per environment Limitations Only works with Argo CD managed applications Requires direct or API access to container registries Git write-back requires Argo CD v2.0+ Cannot update images in init containers by default (requires configuration) Additional Resources Official Documentation GitHub Repository Argo CD Documentation

See references/ directory for detailed guides on specific topics.