ArgoCD Image Updater

ArgoCD Image Updater automatically monitors container registries and updates application images when new versions are available. This page documents the configuration and management of image updates for FT Services.

Overview

ArgoCD Image Updater watches Harbor registry for new image tags matching configured patterns and automatically updates ArgoCD Application annotations, triggering redeployment.

Image Updater is configured for static environments only (dev-mysql, dev-oracle, latest-mysql, latest-oracle). Dynamic feature branch environments use fixed image tags.

Architecture

ArgoCD Image Updater Flow
Figure 1. ArgoCD Image Updater Flow

Configuration

Application Annotations

Image Updater is configured via annotations on ArgoCD Application resources:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: dev-mysql
  annotations:
    # Enable image updater
    argocd-image-updater.argoproj.io/image-list: |
      ftacs=hub.friendly-tech.com/ftacs/ftacs,
      ui-backend=hub.friendly-tech.com/ui/backend,
      portals=hub.friendly-tech.com/ui/portals

    # Update strategy per image
    argocd-image-updater.argoproj.io/ftacs.update-strategy: semver
    argocd-image-updater.argoproj.io/ui-backend.update-strategy: latest
    argocd-image-updater.argoproj.io/portals.update-strategy: latest

    # Allow tags matching pattern
    argocd-image-updater.argoproj.io/ftacs.allow-tags: regexp:^v[0-9]+\.[0-9]+\.[0-9]+$
    argocd-image-updater.argoproj.io/ui-backend.allow-tags: regexp:^(latest|dev|v.*)$
    argocd-image-updater.argoproj.io/portals.allow-tags: regexp:^(latest|dev|v.*)$

    # Write back method
    argocd-image-updater.argoproj.io/write-back-method: argocd

Annotation Reference

Annotation Description Required

image-list

Comma-separated list of images to watch (alias=image)

Yes

{alias}.update-strategy

How to select new tags: semver, latest, name, digest

No (default: semver)

{alias}.allow-tags

Regex pattern for allowed tags

No

{alias}.ignore-tags

Regex pattern for ignored tags

No

{alias}.helm.image-name

Helm values path for image name

Yes (for Helm)

{alias}.helm.image-tag

Helm values path for image tag

Yes (for Helm)

write-back-method

How to update: argocd or git

No (default: argocd)

Update Strategies

Strategy Description Example Pattern

semver

Follow semantic versioning, pick highest version

v1.0.0, 1.2.3

latest

Always use the most recently pushed tag

Any tag

name

Alphabetically latest tag name

dev, latest, main

digest

Update when image digest changes (for mutable tags)

latest (same tag, new digest)

Service Configuration

FT Services Image List

Service Harbor Path Helm Value Path Default Strategy

ftacs

hub.friendly-tech.com/ftacs/ftacs

ftacs.image.tag

semver

uiBackend

hub.friendly-tech.com/ui/backend

uiBackend.image.tag

latest

portals

hub.friendly-tech.com/ui/portals

portals.image.tag

latest

northboundApi

hub.friendly-tech.com/api/northbound-api

northboundApi.image.tag

latest

serviceApi

hub.friendly-tech.com/api/service-api

serviceApi.image.tag

latest

provisionApi

hub.friendly-tech.com/api/provision-api

provisionApi.image.tag

latest

ftDeviceNetwork

hub.friendly-tech.com/device/ft-device-network

ftDeviceNetwork.image.tag

latest

uiAiAgent

hub.friendly-tech.com/ui/ai-agent

uiAiAgent.image.tag

latest

ftConfigsService

hub.friendly-tech.com/configs/ft-configs-service

ftConfigsService.image.tag

latest

ftConfigsUi

hub.friendly-tech.com/configs/ft-configs-ui

ftConfigsUi.image.tag

latest

Environment Manager Integration

The Services Manager tab in Environment Manager provides a UI for configuring Image Updater:

Services Manager Features
Figure 2. Services Manager Features

Managing via UI

  1. Navigate to Environment Manager

  2. Click "Services Manager" tab

  3. Select static environment from dropdown

  4. For each service:

    • Toggle "Enable Image Updater"

    • Select update strategy

    • Configure tag pattern (optional)

  5. Click "Save Configuration"

  6. Changes are applied to ArgoCD Application annotations

Monitoring

Check Image Updater Logs

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

# Check for specific application
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-image-updater | grep "dev-mysql"

Verify Current Configuration

# Get application annotations
kubectl get application dev-mysql -n argocd -o jsonpath='{.metadata.annotations}' | jq

# Check image updater status
argocd app get dev-mysql -o yaml | grep "image-updater"

Check Update History

# View recent syncs triggered by image updater
kubectl get application dev-mysql -n argocd -o jsonpath='{.status.history}' | jq

# Check ArgoCD events
kubectl get events -n argocd --field-selector involvedObject.name=dev-mysql

Troubleshooting

Images Not Updating

Checklist

  1. Verify Image Updater is running

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

  2. Check annotations are correct

    kubectl get application dev-mysql -n argocd -o yaml | grep -A20 "annotations:"

  3. Verify tag pattern matches

    # List available tags in Harbor
curl -u "$USER:$PASS" "https://hub.friendly-tech.com/api/v2.0/projects/ftacs/repositories/ftacs/tags"

  4. Check Image Updater logs

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

Wrong Image Selected

Cause

Tag pattern too broad or update strategy mismatch

Solution
# Be more specific with allow-tags
argocd-image-updater.argoproj.io/ftacs.allow-tags: regexp:^v[0-9]+\.[0-9]+\.[0-9]+$

# Or use ignore-tags
argocd-image-updater.argoproj.io/ftacs.ignore-tags: regexp:^(dev|test|snapshot)

Harbor Authentication Errors

Check Secret Configuration
# Verify secret exists
kubectl get secret argocd-image-updater-secret -n argocd

# Check secret contents
kubectl get secret argocd-image-updater-secret -n argocd -o yaml

# Update credentials
kubectl create secret generic argocd-image-updater-secret \
  --from-literal=harbor.credentials="$HARBOR_USER:$HARBOR_PASS" \
  -n argocd --dry-run=client -o yaml | kubectl apply -f -

Best Practices

Tag Naming Convention

Environment Recommended Tags Update Strategy

Development

dev, latest

latest or digest

Staging

v1.0.0-rc1, semantic versions

semver with prerelease

Production

v1.0.0, stable semantic versions

semver (stable only)

Security Considerations

  • Use semver strategy for production to avoid unexpected updates

  • Configure ignore-tags to exclude development/test tags

  • Use allow-tags to whitelist specific patterns

  • Consider using digest strategy for mutable tags to detect actual changes

Performance Tuning

# Adjust check interval (default 2 minutes)
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-image-updater-config
  namespace: argocd
data:
  registries.conf: |
    registries:
    - name: Harbor
      api_url: https://hub.friendly-tech.com
      ping: yes
      credentials: secret:argocd/argocd-image-updater-secret#harbor.credentials
      defaultns: ftacs
      default: true

  # Check every 5 minutes instead of 2
  # Reduce load on Harbor registry
  interval: 5m

Related Documentation

Last updated: 2026-08-08 10:57:09 +0200