argocd-image-updater

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

ArgoCD Image Updater 是一款为Argo CD管理的Kubernetes工作负载实现容器镜像更新自动化的工具。它会检查容器镜像仓库中的新版本镜像，并根据可配置的更新策略，更新工作负载的清单以使用最新版本。

Quick Reference

快速参考

Installation (Basic)

基础安装

bash

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/config/install.yaml

bash

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/config/install.yaml

Installation with Helm

使用Helm安装

bash

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

bash

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

策略	说明	适用场景
`semver`	带约束的语义化版本控制	采用版本控制的生产环境应用
`newest-build`	最新构建的镜像	CI/CD流水线、开发环境
`digest`	通过SHA摘要跟踪可变标签	使用 `latest` 或其他可变标签的场景
`alphabetical`	字典序排序（日历版本、自定义规则）	日历版本控制、自定义版本规则

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+)

方式	说明	持久化特性
`argocd`	通过Argo CD API更新（默认方式）	伪持久化（重启后仍保留）
`git`	将变更提交到Git仓库	永久持久化（需要Argo CD v2.0+版本）

ImageUpdater CRD (v1.0.0+)

ImageUpdater CRD（v1.0.0+）

The recommended configuration approach uses the ImageUpdater Custom Resource Definition:

yaml

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"

推荐的配置方式是使用ImageUpdater自定义资源定义（CRD）：

yaml

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

Semver策略

Best for production applications with semantic versioning:

yaml

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)

最适合采用语义化版本控制的生产环境应用：

yaml

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

Semver约束规则：

```
1.x
```
或
```
1.*
```
- 任意1.x.x版本
```
1.2.x
```
- 任意1.2.x版本
```
>=1.0.0 <2.0.0
```
- 范围约束
```
~1.2.3
```
- 补丁版本变更（>=1.2.3 <1.3.0）
```
^1.2.3
```
- 小版本变更（>=1.2.3 <2.0.0）

Newest-Build Strategy

Newest-Build策略

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

yaml

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

适用于需要最新推送镜像的CI/CD流水线场景：

yaml

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

Digest Strategy

Digest策略

Track mutable tags (like

latest

) via their SHA digest:

yaml

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

通过SHA摘要跟踪可变标签（如

latest

）：

yaml

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

Alphabetical Strategy

Alphabetical策略

For CalVer or custom versioning schemes:

yaml

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

适用于日历版本（CalVer）或自定义版本规则：

yaml

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

Git Write-Back Configuration

Git回写配置

For permanent, GitOps-native updates:

yaml

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"

用于实现GitOps原生的永久更新：

yaml

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-<appName>.yaml`	Default, creates parameter override file
`kustomization`	Updates kustomization.yaml
`helmvalues:<path>`	Updates specified Helm values file

目标	说明
`.argocd-source-<appName>.yaml`	默认方式，创建参数覆盖文件
`kustomization`	更新kustomization.yaml文件
`helmvalues:<path>`	更新指定的Helm values文件

Authentication

认证配置

Registry Authentication with Kubernetes Secret

使用Kubernetes Secret进行镜像仓库认证

yaml

apiVersion: v1
kind: Secret
metadata:
  name: docker-registry-secret
  namespace: argocd
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded-docker-config>

Reference in ImageUpdater:

yaml

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

yaml

apiVersion: v1
kind: Secret
metadata:
  name: docker-registry-secret
  namespace: argocd
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded-docker-config>

在ImageUpdater中引用：

yaml

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

Git Credentials for Write-Back

用于回写的Git凭证

yaml

apiVersion: v1
kind: Secret
metadata:
  name: git-creds
  namespace: argocd
type: Opaque
stringData:
  username: git
  password: <your-token-or-password>

yaml

apiVersion: v1
kind: Secret
metadata:
  name: git-creds
  namespace: argocd
type: Opaque
stringData:
  username: git
  password: <your-token-or-password>

Annotations Reference (Legacy)

注解参考（旧版方式）

For applications not using ImageUpdater CRD:

yaml

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

适用于未使用ImageUpdater CRD的应用：

yaml

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

查看Image Updater日志

bash

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

bash

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

Force Update Check

强制触发更新检查

bash

kubectl rollout restart deployment argocd-image-updater -n argocd

bash

kubectl rollout restart deployment argocd-image-updater -n argocd

List Managed Applications

列出受管理的应用

bash

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

bash

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

验证ImageUpdater CRD

bash

kubectl get imageupdaters -n argocd
kubectl describe imageupdater <name> -n argocd

bash

kubectl get imageupdaters -n argocd
kubectl describe imageupdater <name> -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

镜像未更新
- 查看日志排查认证错误
- 验证镜像仓库凭证是否正确
- 确认应用由Argo CD管理
- 检查更新策略是否与标签规则匹配
Git回写失败
- 验证Git凭证Secret是否存在
- 检查分支名称是否正确
- 确认仓库地址可访问
- 验证SSH密钥或令牌是否具备写入权限
选择了错误的镜像版本
- 检查更新策略配置
- 查看标签过滤规则（allow-tags、ignore-tags）
- 验证semver约束是否正确

Debug Commands

调试命令

bash

undefined

bash

undefined

Check Image Updater status

查看Image Updater状态

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

查看ImageUpdater CR状态

kubectl get imageupdater -n argocd -o yaml

undefined

kubectl get imageupdater -n argocd -o yaml

undefined

Namespace Scoping

命名空间范围

The

spec.namespace

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

ImageUpdater CRD中的

spec.namespace

字段用于控制从哪个命名空间发现Argo CD应用。

Single Namespace (Default)

单命名空间（默认）

yaml

spec:
  namespace: argocd  # Only discover Applications in argocd namespace

yaml

spec:
  namespace: argocd  # 仅从argocd命名空间发现应用

Multi-Namespace Patterns

多命名空间模式

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

yaml

undefined

适用于应用分布在多个命名空间的多租户集群：

yaml

undefined

Option 1: Deploy separate ImageUpdater CRs per namespace

选项1：为每个命名空间部署独立的ImageUpdater CR

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

undefined

apiVersion: argocd-image-updater.argoproj.io/v1alpha1 kind: ImageUpdater metadata: name: team-a-updater namespace: argocd spec: namespace: team-a-apps # 范围限定为team-a的应用命名空间 applicationRefs: - namePattern: "*"

apiVersion: argocd-image-updater.argoproj.io/v1alpha1 kind: ImageUpdater metadata: name: team-b-updater namespace: argocd spec: namespace: team-b-apps # 范围限定为team-b的应用命名空间

undefined

Cross-Namespace Secrets

跨命名空间Secret

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

yaml

undefined

当ImageUpdater在

argocd

命名空间运行，但需要访问其他命名空间的Secret时：

镜像仓库凭证：使用
```
pullsecret:NAMESPACE/SECRET-NAME
```
格式
Git凭证：使用完整命名空间路径引用Secret
RBAC：通过目标命名空间中的RoleBinding为ImageUpdater的ServiceAccount授予访问权限

yaml

undefined

Example: Grant secrets access in team-a namespace

示例：授予在team-a命名空间的Secret访问权限

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

undefined

apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: image-updater-secrets namespace: team-a # 包含Secret的目标命名空间 roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: secret-reader subjects:

kind: ServiceAccount name: argocd-image-updater namespace: argocd # ImageUpdater所在的命名空间

undefined

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

使用具体版本约束 - 生产环境避免使用过于宽泛的semver约束
实现标签过滤 - 使用allow-tags/ignore-tags排除不需要的版本
生产环境使用Git回写 - 确保变更在Git中可追踪
按环境分离镜像仓库 - 开发/预发布/生产环境使用不同的凭证
监控Image Updater日志 - 为更新失败设置告警
先在预发布环境测试更新 - 为不同环境配置不同的更新策略

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)

仅适用于Argo CD管理的应用
需要直接或通过API访问容器镜像仓库
Git回写需要Argo CD v2.0+版本
默认无法更新初始化容器中的镜像（需额外配置）

Additional Resources

额外资源

See

references/

directory for detailed guides on specific topics.

查看

references/

目录获取特定主题的详细指南。