argocd-image-updater

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 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"

更新戦略の設定

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 の認証情報を含むシークレットが存在することを確認します
   • ブランチ名が正しいことを確認します
   • リポジトリ 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 Application の検出対象となる名前空間を制御します。

単一の名前空間（デフォルト）

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

複数の名前空間のパターン

Application が複数の名前空間に存在するマルチテナントクラスター向けです。

# 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. 環境ごとにレジストリを分ける - dev/staging/prod で異なる認証情報を使用します
5. Image Updater のログを監視する - 更新の失敗を検知するアラートを設定します
6. まずステージング環境で更新をテストする - 環境ごとに異なる更新ポリシーを使用します

制限事項

• Argo CD で管理されているアプリケーションでのみ動作します
• コンテナレジストリへの直接アクセスまたは API アクセスが必要です
• Git 書き戻しには Argo CD v2.0 以降が必要です
• デフォルトでは init コンテナ内のイメージを更新できません（設定が必要です）

追加リソース

• 公式ドキュメント
• GitHub リポジトリ
• Argo CD ドキュメント

各トピックの詳細なガイドについては、references/ ディレクトリを参照してください。