Contents
スポンサードリンク
1️⃣ Argo CD 2026 のマルチクラスターサポート概要
Argo CD は 2026 年にリリースされた v2.9（GitHub Release Notes）で、Cluster API と ApplicationSet の連携が標準機能として組み込まれました。これにより、クラスタの追加・削除をコードベースだけで完結させられる「GitOps × Cluster‑API」モデルが実現します。本節では、主な拡張ポイントと公式情報への参照先をまとめます。
- Cluster API 連携：
clusterctlが生成したクラスタ情報が自動で Argo CD のClusterSecretに反映され、ApplicationSet のClusterGeneratorが即座に利用可能になります（詳細はArgo CD Docs – Cluster API Integration）。 - ClusterGenerator 強化：ラベルセレクタ (
labelSelector) とテンプレート変数が追加され、環境別に柔軟なフィルタリングができるようになりました。 - CLI／UI の統一：
argocd cluster addに--upsertオプションが新設され、既存シークレットの上書きと同時に認証方式を切り替えられます。
参考: AWS ブログ「Argo CD がマルチクラスター対応を拡張」(リンク)、Zenn 記事「Cluster API と Argo CD の実践」(リンク)
2️⃣ 対象クラスタの認証方法と登録手順
この章では、代表的な 3 種類の認証方式をそれぞれコード例付きで解説します。どの方法でも CLI と UI が同一 API を呼び出す ため、結果は常に一致します。
2.1 ServiceAccount トークン認証
ServiceAccount（SA）トークンは最もシンプルかつ RBAC と組み合わせやすい方式です。以下の手順で argocd-manager SA を作成し、トークンを取得・登録します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# 1. SA 作成 & ClusterRoleBinding 設定 kubectl create serviceaccount argocd-manager -n kube-system kubectl create clusterrolebinding argocd-manager-binding \ --clusterrole=cluster-admin \ --serviceaccount=kube-system:argocd-manager # 2. トークン取得（bash 変数に格納） SA_TOKEN=$(kubectl -n kube-system get secret $(kubectl -n kube-system get sa argocd-manager -o jsonpath="{.secrets[0].name}") -o go-template="{{ .data.token | base64decode }}") # 3. Argo CD にクラスタ登録 argocd login $ARGOCD_HOST --username admin --password $ARGOCD_PASSWORD --insecure argocd cluster add https://<CLUSTER_ENDPOINT> \ --service-account-token $SA_TOKEN \ --upsert |
留意点：トークンは期限が無いため、
cronjob等で定期的にローテーションするパイプラインを併用すると安全です。
2.2 kubeconfig インポート
開発者が日常的に使う kubeconfig をそのままインポートできるので、学習コストが低くなります。v2.9 では複数コンテキストの一括登録が可能です。
|
1 2 3 |
# 任意のコンテキストを選択してクラスタ追加 argocd cluster add --kubeconfig ~/.kube/config --context dev-cluster --upsert |
- メリット：ローカルと同一認証情報で Argo CD が動作するため、環境差異が減ります。
- 注意点：
kubeconfigに OIDC など外部 IdP の設定が含まれる場合は、有効期限切れに備えて定期的なトークン更新を忘れないでください。
2.3 OIDC 連携
企業環境では SSO が必須になるケースが多く、Argo CD の Dex と連携した OIDC 設定が推奨されます。2026 年版では Cluster API 用 OIDC プラグイン が公式に提供されています。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
# argocd-cm.yaml（Dex 設定例） apiVersion: v1 kind: ConfigMap metadata: name: argocd-cm namespace: argocd data: dex.config: | connectors: - type: oidc id: google name: Google config: issuer: https://accounts.google.com clientID: <CLIENT_ID> clientSecret: $dex.google.clientSecret |
|
1 2 3 4 5 6 7 8 9 10 |
# クラスタ側の OIDC 設定例（ConfigMap） apiVersion: v1 kind: ConfigMap metadata: name: oidc-config namespace: kube-system data: oidc-issuer-url: https://accounts.google.com client-id: <CLIENT_ID> |
|
1 2 3 4 5 |
# クラスタ追加コマンド（OIDC 認証） argocd cluster add https://<CLUSTER_ENDPOINT> \ --auth-provider oidc \ --upsert |
- ポイント：トークンの有効期限は IdP が自動管理するため、長期運用に向いています。
2.4 CLI と UI の使い分け
| 項目 | CLI の特徴 | UI の特徴 |
|---|---|---|
| 自動化 | スクリプト化で GitOps パイプラインに組み込みやすい | ウィザード形式で設定ミスを可視化 |
| 可視性 | ログ出力で変更履歴が取得可能 | シークレット内容（期限・名前空間）を UI で即確認 |
どちらの方法でも ClusterSecret は同一リソースになるため、運用上は好みとシーンに合わせて選択してください。
3️⃣ Argo CD Projects と RBAC によるアクセス制御
3.1 Project の基本構造と必須項目
2026 年版では destinations と sourceRepos が 必須 となり、未設定の場合は全リソースへのアクセスがブロックされます。以下は Production 用プロジェクトの例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
apiVersion: argoproj.io/v1alpha1 kind: AppProject metadata: name: prod-project spec: description: Production 環境向け Project destinations: - namespace: prod server: https://prod-cluster-1.example.com - namespace: prod server: https://prod-cluster-2.example.com sourceRepos: - https://github.com/your-org/prod-configs.git clusterResourceWhitelist: - group: "*" kind: "*" |
ポイント：
destinationsに列挙した組み合わせだけがデプロイ可能になるため、誤った環境へのリリースを防げます。
3.2 ホワイトリストによるクラスタ・名前空間制御
| プロジェクト | 許可サーバー URL | 許可 Namespace |
|---|---|---|
| dev-project | https://dev-cluster.example.com | dev, test |
| prod-project | https://prod-cluster-1.example.com https://prod-cluster-2.example.com |
prod |
この表に記載された組み合わせ以外は UI がエラーを返すため、運用者は安全に作業できます。
3.3 RBAC ポリシーとの統合
Argo CD の RBAC は policy.csv に定義します。以下は管理者ロールと開発者ロールの典型的な設定例です。
|
1 2 3 4 5 6 |
p, role:admin, applications, *, */*, allow g, alice, role:admin p, role:dev, projects, get, dev-project, allow g, bob, role:dev |
- 効果：
adminは全プロジェクトを閲覧・編集でき、devロールはdev-projectのみ操作可能です。Projects と RBAC を組み合わせることで「最小権限の原則」を簡潔に実装できます。
4️⃣ ApplicationSet と ClusterGenerator による自動マルチクラスター展開
4.1 ClusterGenerator の構文とラベルフィルタ
v2.9 では labelSelector が追加され、特定ラベルが付いたクラスタだけを対象にできます。以下は environment=prod ラベルのクラスタ向けテンプレートです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: prod-multi-cluster spec: generators: - cluster: selector: matchLabels: environment: prod # prod ラベルが付いたクラスタだけ対象 template: metadata: name: '{{name}}-myapp' spec: project: prod-project source: repoURL: https://github.com/your-org/app-configs.git targetRevision: HEAD path: helm/myapp destination: server: '{{server}}' # 各クラスタの API サーバ URL が自動展開 namespace: prod syncPolicy: automated: prune: true selfHeal: true |
ポイント：新しいクラスタが
environment=prodを付与して作成されるだけで、同一 Helm チャートが自動的にデプロイされます。
4.2 App of Apps パターンで環境別管理
以下は dev / staging / prod の 3 環境を 1 つの ApplicationSet で管理する例です。環境追加はリストに行を足すだけで完了します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: env-app-of-apps spec: generators: - list: elements: - env: dev namespace: dev project: dev-project repoURL: https://github.com/your-org/dev-configs.git - env: staging namespace: staging project: stag-project repoURL: https://github.com/your-org/staging-configs.git - env: prod namespace: prod project: prod-project repoURL: https://github.com/your-org/prod-configs.git template: metadata: name: '{{env}}-root-app' spec: project: '{{project}}' source: repoURL: '{{repoURL}}' targetRevision: HEAD path: apps destination: server: https://kubernetes.default.svc namespace: '{{namespace}}' syncPolicy: automated: prune: true selfHeal: true |
- 利点：環境追加時に YAML の行を1つ増やすだけで、CI/CD パイプラインの変更が最小限に抑えられます。
5️⃣ Helm と Kustomize のハイブリッド構成と SyncPolicy 設定
5️⃣1 ベストプラクティス：Helm + Kustomize の併用
Argo CD v2.9 では helm.parameters と kustomize.patchesStrategicMerge を同一 Application 内で使用可能です。共通設定は Helm、環境固有の差分は Kustomize パッチで上書きします。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: myapp-hybrid spec: project: prod-project source: repoURL: https://github.com/your-org/charts.git targetRevision: HEAD chart: myapp helm: parameters: - name: image.tag value: "v1.4.2" kustomize: patchesStrategicMerge: - overlays/prod/ingress-patch.yaml # 環境固有の Ingress 設定 destination: server: https://prod-cluster-1.example.com namespace: prod syncPolicy: automated: prune: true selfHeal: true syncOptions: - CreateNamespace=true |
ポイント：Helm が提供する変数で共通イメージタグを管理し、Kustomize のパッチで Ingress ホスト名だけを上書きできるため、コードの重複が減ります。
5️⃣2 Auto‑sync / Prune / Self‑heal の実装例と留意点
| オプション | 機能概要 | 推奨シーン |
|---|---|---|
autoSync (automated) |
リポジトリ変更を検知して即時 sync | 継続的デプロイが必要なマイクロサービス |
prune |
目的外リソースを自動削除 | 環境のクリーンアップや CRD のバージョン切替 |
selfHeal |
手動で変更されたリソースを元に戻す | 高可用性が求められるインフラコンポーネント |
注意点
- prune は対象 namespace を限定しないと、誤削除のリスクがあります。
- selfHeal が有効な状態で Terraform 等他ツールが同一リソースを管理すると競合が起きやすくなるため、所有権は明確に分離してください。
6️⃣ トラブルシューティングと CI/CD パイプライン統合ベストプラクティス
6️⃣1 認証エラー・RBAC 設定ミスの診断手順
- Argo CD Server のログ確認
bash
kubectl logs -n argocd deployment/argocd-server -c server | grep -i auth - ClusterSecret 内容チェック
bash
kubectl -n argocd get secret <cluster-secret> -o yaml - RBAC ポリシーのテスト
bash
argocd rbac policy test --user alice --action get --resource applications
多くは ServiceAccount のロールバインディング不足、または OIDC トークン期限切れが原因です。
6️⃣2 同期失敗・名前空間競合の対処法
- 名前空間競合：
kubectl get applications -A | grep Errorでステータスを抽出し、spec.destination.namespaceが重複していないか確認。 - 同期エラー：Argo CD UI の Events タブまたは CLI
argocd app wait <app> --healthで詳細ログを取得。Helm テンプレートの構文エラーや Kustomize パッチの適用失敗が多いです。
6️⃣3 GitHub Actions / GitLab CI と連携するフロー
| ステップ | 内容 |
|---|---|
| Webhook 設定 | リポジトリ側で Argo CD の Webhook を有効化し、push／pull_request 時に自動 sync をトリガー |
| ClusterSecret 更新 | CI ジョブで AWS/GCP Secret Manager から最新トークンを取得し、argocd cluster add --upsert でシークレットを更新 |
| Lint & Build | helm lint と kustomize build を実行し、マニフェストの構文エラーを事前に検出 |
| Sync 実行 & 待機 | argocd app sync <app> → argocd app wait <app> --health でデプロイ完了を確認 |
GitHub Actions のサンプルワークフロー
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
name: Deploy to Production on: push: branches: [ main ] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install Argo CD CLI run: | curl -sSL -o /usr/local/bin/argocd \ https://github.com/argoproj/argo-cd/releases/download/v2.9.0/argocd-linux-amd64 chmod +x /usr/local/bin/argocd - name: Login to Argo CD env: ARGOCD_PASSWORD: ${{ secrets.ARGOCD_PASSWORD }} run: | argocd login ${{ vars.ARGOCD_HOST }} \ --username admin --password "$ARGOCD_PASSWORD" --insecure - name: Sync Production AppSet run: | argocd app sync prod-root-app argocd app wait prod-root-app --health |
- ベストプラクティス：
app waitを必ず実行し、CI が失敗したときにロールバックやアラートを出す仕組みを入れると安心です。
7️⃣ まとめ
- マルチクラスター自動化は Cluster API + ApplicationSet の統合が鍵。2026 年版 v2.9 で標準化された
ClusterGeneratorにより、クラスタ追加だけで同一 Helm チャートが即座に展開できます。 - 認証方式は ServiceAccount、kubeconfig、OIDC のいずれでも CLI と UI が同一 API を呼び出すため、運用ポリシーに合わせて選択してください。
- Projects + RBAC による最小権限化で、環境・クラスタ単位のアクセス制御が明示的に管理できます。
- Helm と Kustomize のハイブリッド構成は共通設定と環境差分をシンプルに保ちつつ、
autoSync / prune / selfHealによる安定運用を実現します。 - トラブルシューティングはログ・ClusterSecret・RBAC テストで迅速に切り分けし、CI/CD では Webhook＋シークレット自動更新＋同期待機のフローを標準化すると、完全な GitOps が構築できます。
これらのポイントを踏まえて環境に合わせた実装を行えば、最新 Argo CD を活用した安全・スケーラブルなマルチクラスター運用が可能になります。ぜひ公式ドキュメントと本ガイドを併せて試してみてください。
スポンサードリンク