🛠️ Argo CD x Kustomize マスターガイド: イメージオーバーライドとバージョン固定テクニック

6月 16, 2026

—

Kubernetes環境でGitOpsを実践する際に最もよく使われるツール組み合わせが、まさにArgo CDとKustomizeです。しかし、運用をしていると、特定の環境でのみイメージを少し変更したい場合や、Kustomizeのバージョンによってビルド結果が異なり困る状況に遭遇することがあります。

今日は、Argo CD ApplicationでKustomizeイメージタグをオーバーライド(Override)する具体的な場所と方法、そして特定のKustomizeバージョンを固定(Pinning)してビルドの安定性を確保する方法まで、非常に詳細に掘り下げていきます！ 🚀

こんにちは！今日は、Argo CDを通じてKustomizeマニフェストをデプロイする際に、運用効率を最大化できる2つの主要なテクニックをご紹介します。たった10分投資するだけで、皆さんのGitOpsパイプラインをさらに一段階アップグレードできます。

1. Kustomizeイメージタグはどこでオーバーライドできますか？ 🖼️

一般的にKustomizeを使用する際は、kustomization.yamlファイルにimagesフィールドを定義します。しかし、Argo CDを使用すると、Gitリポジトリを直接修正することなく、Applicationリソースレベルでイメージを動的に変更できます。

① Argo CD Application Manifest (YAML)での設定

最も推奨される方法です。Applicationリソースのspec.source.kustomizeパスにオーバーライドするイメージ情報を宣言します。

📝 コード例と説明

YAML

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-kustomize-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/my-infra.git
    targetRevision: HEAD
    path: overlays/production
    # Kustomize関連の設定を定義するセクションです。
    kustomize:
      # ここでイメージタグをオーバーライドします。
      # kustomization.yamlで定義されたイメージ名を見つけて、新しいタグに置換します。
      images:
        - name: my-api-image         # 元のイメージ名
          newName: my-api-image     # (オプション) イメージ名を変更する場合
          newTag: v2.0.0-release    # 新しいタグバージョンを指定 👈 重要！
  destination:
    server: https://kubernetes.default.svc
    namespace: prod

② Argo CD CLIを通じたリアルタイム変更

CIパイプライン（Jenkins、GitHub Actionsなど）でデプロイ直前にタグを変更したい場合に便利です。

Bash

# 特定のアプリケーションのイメージタグを即座に変更するコマンド
argocd app set my-kustomize-app --kustomize-image my-api-image=v2.0.0-release

③ Argo CD Web UIでの変更

ユーザーインターフェース（UI）でも可能です。

Applicationにアクセス -> PARAMETERSタブをクリック -> Kustomizeセクションでimages項目を修正。

2. 特定のKustomizeバージョンを固定(Pinning)する方法 📌

Argo CDは内蔵のKustomizeバイナリを使用します。しかし、ローカルで使用するバージョンとArgo CD内部のバージョンが異なる場合、マニフェストのレンダリング結果が異なり、OutOfSyncが発生したり、デプロイエラーが発生したりする可能性があります。これを防ぐためにバージョンを固定する方法は大きく2つあります。

① Argo CD ConfigMap (argocd-cm)の修正 ⚙️

Argo CD設定ファイルであるargocd-cmを修正して、デフォルトで使用するKustomize実行ファイルのパスを指定できます。ただし、この方法はArgo CDがサポートする範囲内でのみ可能です。

YAML

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  # kustomize.buildOptionsなどを通じてビルドオプションを制御できます。
  kustomize.buildOptions: "--load-restrictor LoadRestrictionsNone"

② カスタムツール（サイドカーコンテナ）の活用 📦

最も確実で強力な方法です。Argo CDのrepo-serverに、希望するバージョンのKustomizeバイナリをインストールしたサイドカーコンテナをアタッチするか、イメージをカスタムして特定のバージョンを含めます。

📝 Argo CD Repo-Serverカスタム例 (Docker)

Dockerfile

# Argo CD公式イメージをベースとして使用
FROM argoproj/argocd:v2.8.4

# root権限に切り替えてインストールを進める
USER root

# 希望する特定のバージョンのKustomizeをダウンロード (例: v5.0.0)
RUN curl -L https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv5.0.0/kustomize_v5.0.0_linux_amd64.tar.gz | tar -xz && 
    mv kustomize /usr/local/bin/kustomize-v5

# 再びargocdユーザーに戻す
USER 999

その後、argocd-cmでこのカスタムバイナリを使用するように設定するか、**Config Management Plugin (CMP)**を定義して使用します。

3. 要約と実務チェックリスト 📊


作業内容	場所 / 方法	備考

—	—	—
イメージタグ変更	Application Spec (spec.source.kustomize.images)	Git修正なしで環境別タグ分離可能
一時イメージ変更	Argo CD CLI / Web UI	迅速なテストおよび手動デプロイに適している
Kustomizeバージョン固定	argocd-repo-serverカスタムバイナリインストール	一貫したビルド結果を保証（強く推奨）
ビルドオプション追加	argocd-cm内のkustomize.buildOptions	フラグ（–enable-alpha-pluginsなど）追加時に使用

—

🏁 終わりに

Kustomizeイメージオーバーライドは、Argo CDを真の**「環境別設定ツール」**に変えます。また、Kustomizeバージョンを明確に固定する習慣は、「私のコンピューターでは動くのに、サーバーではなぜ動かないのか？」という古典的な問題を根本的に解決します。

皆さんのプロジェクト状況に合わせて、最も適切なオーバーライド方式を選択してください！ 🛠️