mcpField
A
argocd-image-updater

argocd-image-updater

github.com/julianobarbosa云与 DevOps1454 次安装2 天前更新
代码仓库

关于 argocd-image-updater

此 Skill 用于配置 ArgoCD Image Updater；该工具检查容器镜像仓库，并更新由 Argo CD 管理的 Kubernetes 工作负载镜像引用。内容介绍更新策略、写回方式、凭据、命名空间范围和故障排查。

主要功能

  1. 01配置 semver、newest-build、digest 和 alphabetical 策略
  2. 02通过 Argo CD 或 Git 写回变更
  3. 03设置镜像仓库与 Git 凭据
  4. 04将发现范围限定到应用命名空间
  5. 05排查镜像选择和更新失败

适用场景

  1. 01自动更新 Argo CD 应用的镜像
  2. 02通过摘要跟踪可变镜像标签
  3. 03将生产环境镜像变更提交到 Git
  4. 04在多个命名空间应用不同更新范围

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/julianobarbosa/claude-code-skills --skill argocd-image-updater

安装后在 Claude Code 中输入/argocd-image-updater确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

ArgocdImageUpdater/Workflows/
ConfigureImageUpdater.md
CreateImageUpdaterCrds.md
ResolveDrift.md
references/
authentication.md
git-write-back.md
installation.md
troubleshooting.md
update-strategies.md
samples/
argocd-api-writeback.yaml
authentication-secrets.yaml
basic-imageupdater.yaml
git-writeback.yaml
multi-image-app.yaml
semver-strategy.yaml

详细介绍

ArgoCD Image Updater 技能

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

快速参考

安装（基础）
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/config/install.yaml
使用 Helm 安装
helm repo add argo https://argoproj.github.io/argo-helm
helm install argocd-image-updater argo/argocd-image-updater -n argocd

核心概念

更新策略
策略说明使用场景
semver带约束的语义化版本需要版本控制的生产应用
newest-build最近构建的镜像CI/CD 流水线、开发环境
digest通过 SHA 摘要跟踪可变标签使用 latest 或其他可变标签时
alphabetical按字典顺序排序（CalVer、自定义方案）日历版本、自定义方案
更新方法（回写）
方法说明持久性
argocd通过 Argo CD API 更新（默认）伪持久化（重启后仍保留）
git将更改提交到 Git 仓库永久（需要 Argo CD v2.0+）

ImageUpdater CRD（v1.0.0+）

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

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"

更新策略配置

Semver 策略

最适合使用语义化版本的生产应用：

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 策略

适用于需要使用最近推送镜像的 CI/CD 流水线：

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

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

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

适用于 CalVer 或自定义版本方案：

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

Git 回写配置

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

apiVersion: argocd-image-updater.argoproj.io/v1alpha1
kind: ImageUpdater
metadata:
  name: my-image-updater
  namespace: argocd
spec:
  namespace: argocd
  writeBackConfig:
    method: "git"
    gitConfig:
      repository: "[email protected]: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"
回写目标
目标说明
.argocd-source-<appName>.yaml默认值，创建参数覆盖文件
kustomization更新 kustomization.yaml
helmvalues:<path>更新指定的 Helm values 文件

身份验证

使用 Kubernetes Secret 进行仓库身份验证
apiVersion: v1
kind: Secret
metadata:
  name: docker-registry-secret
  namespace: argocd
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded-docker-config>

在 ImageUpdater 中引用：

spec:
  registries:
    - name: myregistry
      prefix: myregistry.example.com
      credentials: pullsecret:argocd/docker-registry-secret
用于回写的 Git 凭据
apiVersion: v1
kind: Secret
metadata:
  name: git-creds
  namespace: argocd
type: Opaque
stringData:
  username: git
  password: <your-token-or-password>

注解参考（旧版）

适用于未使用 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

常见操作

检查 Image Updater 日志
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-image-updater -f
强制检查更新
kubectl rollout restart deployment argocd-image-updater -n argocd
列出受管理的应用
kubectl get applications -n argocd -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.argocd-image-updater\.argoproj\.io/image-list}{"\n"}{end}'
验证 ImageUpdater CRD
kubectl get imageupdaters -n argocd
kubectl describe imageupdater <name> -n argocd

故障排除

常见问题

  1. 镜像未更新

    • 检查日志中是否有身份验证错误
    • 确认仓库凭据正确
    • 确保应用由 Argo CD 管理
    • 检查更新策略是否与标签方案匹配

  2. Git 回写失败

    • 确认 Git 凭据 Secret 存在
    • 检查分支名称是否正确
    • 确保仓库 URL 可访问
    • 确认 SSH 密钥或令牌具有写入权限

  3. 选择了错误的镜像版本

    • 检查更新策略配置
    • 检查标签筛选规则（allow-tags、ignore-tags）
    • 确认 semver 约束正确
调试命令
# 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

命名空间范围

ImageUpdater CRD 中的 spec.namespace 字段控制从哪个命名空间发现 Argo CD Applications。

单个命名空间（默认）
spec:
  namespace: argocd  # Only discover Applications in argocd namespace
多命名空间模式

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

# 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
跨命名空间密钥

当 ImageUpdater 在 argocd 命名空间中运行，但需要使用其他命名空间中的密钥时：

  1. 镜像仓库凭据：使用 pullsecret:NAMESPACE/SECRET-NAME 格式
  2. Git 凭据：使用完整的命名空间路径引用密钥
  3. RBAC：通过目标命名空间中的 RoleBinding 授予 ImageUpdater 的 ServiceAccount 访问权限
# 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

最佳实践

  1. 使用具体的版本约束——避免在生产环境中使用过于宽泛的 semver 约束
  2. 实施标签筛选——使用 allow-tags/ignore-tags 排除不需要的版本
  3. 在生产环境中使用 Git 回写——确保更改在 Git 中留有记录
  4. 按环境隔离镜像仓库——为开发、预发布和生产环境使用不同的凭据
  5. 监控 Image Updater 日志——为更新失败设置告警
  6. 先在预发布环境中测试更新——按环境使用不同的更新策略

限制

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

其他资源

具体主题的详细指南请参阅 references/ 目录。

评论

支持 Markdown