実際のアプリケーションは、レプリカ数、ホスト名、設定値など、わずかな点が異なる複数の環境で動作します。Argo CD は、プレーンな YAML、Helm チャート、Kustomize からデプロイでき、フォルダがどれを使っているかを自動的に検出します。このガイドでは、Kustomize のオーバーレイと Helm の values ファイルを使って 1 つのリポジトリで複数の環境を構成する方法と、設定変更で陥りやすい落とし穴を説明します。これまでのガイドの webapp の例を基にしています。

構成を選ぶ：ブランチではなくフォルダ

環境を長期間存続するブランチ（dev、staging、main）としてモデル化することもできますが、そうするとプロモーションはマージ作業になり、環境間の差異が広がりやすくなります。環境ごとにフォルダを持つ単一ブランチのほうが理解しやすく、すべての環境を並べて確認でき、1 つの環境への変更も通常の diff になります。

Kustomize はこのために作られています。共通の base と、異なる部分だけを変更する環境ごとの小さな overlay を使います。

Kustomize の base とオーバーレイを構築する

webapp-config/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml

base/kustomization.yaml は共通のリソースを列挙します。

resources:
  - deployment.yaml
  - service.yaml

base/deployment.yaml では、各オーバーレイが生成する ConfigMap から設定を読み込むようにコンテナを構成します。

          envFrom:
            - configMapRef:
                name: webapp-config

overlays/dev/kustomization.yaml:

resources:
  - ../../base
namespace: webapp-dev
replicas:
  - name: webapp
    count: 2
configMapGenerator:
  - name: webapp-config
    literals:
      - HEADER=Hello from dev

overlays/prod/kustomization.yaml も同様で、namespace: webapp-prod、count: 4、独自の HEADER の値を設定します。

各オーバーレイに 1 つの Application を向ける

Argo CD はパス内の kustomization.yaml を検出し、自動的にビルドします。環境ごとに 1 つの Application を作成します。

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: webapp-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/webapp-config.git
    targetRevision: HEAD
    path: overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: webapp-dev
  syncPolicy:
    syncOptions:
      - CreateNamespace=true
    automated:
      prune: true

webapp-prod では、名前、パス（overlays/prod）、namespace を変更します。本番の同期を人が承認できるように、automated を省くことも検討してください。

Helm の場合も形は同じですが、ソースがチャートになり、環境ごとの values ファイルを選択します。

  source:
    repoURL: https://github.com/your-org/webapp-config.git
    targetRevision: HEAD
    path: charts/webapp
    helm:
      valueFiles:
        - values-dev.yaml

valueFiles のパスはチャートフォルダからの相対パスで、後に指定したファイルが先のファイルを上書きします。

設定変更を意図的に扱う

ある環境の HEADER の値を変更し、各ツールの動作を比較します。

• Kustomize は、生成された ConfigMap の名前に内容のハッシュを付加します。新しい値は新しい ConfigMap（webapp-config-<hash>）を生成し、Deployment の参照を更新するため、Pod のロールアウトが発生します。古い ConfigMap は孤立し、prune されるまでアプリケーションは OutOfSync と表示されます。prune: true が有効なら、自動的に片付けられます。
• Helm は既存の ConfigMap をその場で更新します。Deployment の spec は変わらないため、稼働中の Pod は古い値を保持したままで、Argo CD や Kubernetes に再起動を促すものは何もありません。

Helm の標準的な対処法は、ConfigMap のチェックサムを Pod テンプレートに入れることです。そうすれば設定の変更でテンプレートが変わり、Pod がロールアウトされます。templates/deployment.yaml に次のように記述します。

  template:
    metadata:
      annotations:
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}

Deployment を手動で再起動する方法も一度なら有効ですが、Git に記録されないため、本来の目的に反します。

環境間で変更をプロモートする

この構成では、プロモーションは通常の commit の連続になります。まず dev オーバーレイを変更し（たとえば overlays/dev で kustomize edit set image webapp=nginx:1.26 を実行してイメージを更新）、自動同期で適用して確認します。次に overlays/prod に同じ変更を加えて同期します。本番を制御下に置いている場合は手動で行います。CI パイプラインで dev の commit を自動化し、プルリクエストや承認で本番の commit を制御できます。多数のクラスターや環境を 1 か所から運用するには、テンプレートから Application リソースを生成する Argo CD の ApplicationSet を検討してください。