# argoproj-labs/argocd-image-updater architecture

> Architecture diagram of the GitHub repository argoproj-labs/argocd-image-updater, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/argoproj-labs/argocd-image-updater
- Repository: https://github.com/argoproj-labs/argocd-image-updater

## Overview

Argo CD Image Updater watches ImageUpdater custom resources, discovers configured application images, checks registry tags against update policies, and writes image parameter overrides through Argo CD or Git. Registry webhooks provide an event-triggered update path alongside reconciliation. The tree and README establish these capabilities; sampled controller and webhook code confirms reconciliation and webhook wiring, but unsampled implementation details limit finer-grained call edges.

Main entry points: [`internal/controller/reconcile.go`](https://github.com/argoproj-labs/argocd-image-updater/blob/master/internal/controller/reconcile.go) (Update run), [`internal/controller/imageupdater_controller.go`](https://github.com/argoproj-labs/argocd-image-updater/blob/master/internal/controller/imageupdater_controller.go) (Reconciler), [`registry-scanner/pkg/image/image.go`](https://github.com/argoproj-labs/argocd-image-updater/blob/master/registry-scanner/pkg/image/image.go) (Image discovery), [`pkg/argocd/update.go`](https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/argocd/update.go) (Override writing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_cr["ImageUpdater CR"]
  node_controller["Reconciler"]
  node_reconcile["Update run<br/>[reconcile.go]"]
  node_status["Status tracking<br/>[status.go]"]
  node_metrics["Metrics<br/>[metrics.go]"]
end

subgraph group_discovery["Image discovery"]
  node_scanner["Image discovery<br/>[image.go]"]
  node_imagepolicy["Tag selection<br/>[version.go]"]
  node_registryclient["Registry client<br/>[client.go]"]
end

subgraph group_updates["Update delivery"]
  node_argocd["Argo CD integration<br/>[argocd.go]"]
  node_overrides["Override writing<br/>[update.go]"]
  node_git["Git access<br/>[client.go]"]
  node_prservice["Pull requests<br/>[pr_service.go]"]
end

subgraph group_events["Registry events"]
  node_webhookserver["Webhook server<br/>[server.go]"]
  node_webhookhandlers["Event handlers<br/>[webhook.go]"]
end

node_operator(("Operator"))
node_kubernetes[("Kubernetes API")]
node_registry[("Container registry")]
node_gitrepo[("Git repository")]
node_scm["SCM provider"]
node_webhookactor(("Registry webhook"))

node_operator -->|"configures"| node_cr
node_controller -->|"reads and updates"| node_kubernetes
node_kubernetes -->|"sends changes"| node_controller
node_controller -->|"runs updates"| node_reconcile
node_reconcile -->|"discovers images"| node_scanner
node_scanner -->|"selects tags"| node_imagepolicy
node_scanner -->|"queries"| node_registryclient
node_registryclient -->|"reads manifests and tags"| node_registry
node_reconcile -->|"loads applications"| node_argocd
node_reconcile -->|"writes overrides"| node_overrides
node_overrides -->|"updates parameters"| node_argocd
node_overrides -->|"commits changes"| node_git
node_git -->|"pushes overrides"| node_gitrepo
node_reconcile -.->|"requests PR"| node_prservice
node_prservice -.->|"opens PR or MR"| node_scm
node_reconcile -->|"records result"| node_status
node_status -->|"updates status"| node_kubernetes
node_reconcile -->|"records metrics"| node_metrics
node_webhookactor -->|"sends event"| node_webhookserver
node_webhookserver -->|"dispatches event"| node_webhookhandlers
node_webhookhandlers -->|"triggers check"| node_reconcile

click node_cr "https://github.com/argoproj-labs/argocd-image-updater/blob/master/api/v1alpha1/imageupdater_types.go"
click node_controller "https://github.com/argoproj-labs/argocd-image-updater/blob/master/internal/controller/imageupdater_controller.go"
click node_reconcile "https://github.com/argoproj-labs/argocd-image-updater/blob/master/internal/controller/reconcile.go"
click node_status "https://github.com/argoproj-labs/argocd-image-updater/blob/master/internal/controller/status.go"
click node_argocd "https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/argocd/argocd.go"
click node_scanner "https://github.com/argoproj-labs/argocd-image-updater/blob/master/registry-scanner/pkg/image/image.go"
click node_imagepolicy "https://github.com/argoproj-labs/argocd-image-updater/blob/master/registry-scanner/pkg/image/version.go"
click node_registryclient "https://github.com/argoproj-labs/argocd-image-updater/blob/master/registry-scanner/pkg/registry/client.go"
click node_overrides "https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/argocd/update.go"
click node_git "https://github.com/argoproj-labs/argocd-image-updater/blob/master/ext/git/client.go"
click node_prservice "https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/argocd/pr_service.go"
click node_webhookserver "https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/webhook/server.go"
click node_webhookhandlers "https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/webhook/webhook.go"
click node_metrics "https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/metrics/metrics.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cr,node_controller,node_reconcile,node_status,node_metrics toneBlue
class node_scanner,node_imagepolicy,node_registryclient,node_kubernetes,node_registry,node_gitrepo toneAmber
class node_argocd,node_overrides,node_git,node_prservice,node_webhookactor toneMint
class node_webhookserver,node_webhookhandlers toneRose
class node_operator,node_scm toneIndigo
```

## Components

### Control plane

- [ImageUpdater CR](https://github.com/argoproj-labs/argocd-image-updater/blob/master/api/v1alpha1/imageupdater_types.go): `api/v1alpha1/imageupdater_types.go`
- [Reconciler](https://github.com/argoproj-labs/argocd-image-updater/blob/master/internal/controller/imageupdater_controller.go): `internal/controller/imageupdater_controller.go`
- [Update run](https://github.com/argoproj-labs/argocd-image-updater/blob/master/internal/controller/reconcile.go): `internal/controller/reconcile.go`
- [Status tracking](https://github.com/argoproj-labs/argocd-image-updater/blob/master/internal/controller/status.go): `internal/controller/status.go`
- [Metrics](https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/metrics/metrics.go): `pkg/metrics/metrics.go`

### Image discovery

- [Image discovery](https://github.com/argoproj-labs/argocd-image-updater/blob/master/registry-scanner/pkg/image/image.go): `registry-scanner/pkg/image/image.go`
- [Tag selection](https://github.com/argoproj-labs/argocd-image-updater/blob/master/registry-scanner/pkg/image/version.go): `registry-scanner/pkg/image/version.go`
- [Registry client](https://github.com/argoproj-labs/argocd-image-updater/blob/master/registry-scanner/pkg/registry/client.go): `registry-scanner/pkg/registry/client.go`

### Update delivery

- [Argo CD integration](https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/argocd/argocd.go): `pkg/argocd/argocd.go`
- [Override writing](https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/argocd/update.go): `pkg/argocd/update.go`
- [Git access](https://github.com/argoproj-labs/argocd-image-updater/blob/master/ext/git/client.go): `ext/git/client.go`
- [Pull requests](https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/argocd/pr_service.go): `pkg/argocd/pr_service.go`

### Registry events

- [Webhook server](https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/webhook/server.go): `pkg/webhook/server.go`
- [Event handlers](https://github.com/argoproj-labs/argocd-image-updater/blob/master/pkg/webhook/webhook.go): `pkg/webhook/webhook.go`

### Other components

- **Operator**
- **Kubernetes API**
- **Container registry**
- **Git repository**
- **SCM provider**
- **Registry webhook**

## Connections

- Operator → ImageUpdater CR: configures
- Reconciler → Kubernetes API: reads and updates
- Kubernetes API → Reconciler: sends changes
- Reconciler → Update run: runs updates
- Update run → Image discovery: discovers images
- Image discovery → Tag selection: selects tags
- Image discovery → Registry client: queries
- Registry client → Container registry: reads manifests and tags
- Update run → Argo CD integration: loads applications
- Update run → Override writing: writes overrides
- Override writing → Argo CD integration: updates parameters
- Override writing → Git access: commits changes
- Git access → Git repository: pushes overrides
- Update run → Pull requests: requests PR
- Pull requests → SCM provider: opens PR or MR
- Update run → Status tracking: records result
- Status tracking → Kubernetes API: updates status
- Update run → Metrics: records metrics
- Registry webhook → Webhook server: sends event
- Webhook server → Event handlers: dispatches event
- Event handlers → Update run: triggers check