ArgoCD GitOpsマルチクラスタデプロイメントパターン

複数の分散型クラスタにわたるKubernetesデプロイメント操作を管理するには、環境のずれをなくし、アクセス管理を簡素化し、継続的な宣言的調整を保証するための一元化されたコントロールプレーンが必要です。エンジニアリング組織が単一のKubernetesクラスタから数十の環境固有または地理的に分散したターゲットクラスタにスケールアップする際、クラスタの状態を手動で、または断片的なCIスクリプトを介して管理すると、デプロイメントの失敗やセキュリティの見落としにつながります。ArgoCDでマルチクラスタGitOpsパターンを実装することで、Gitに保存されたアプリケーションマニフェストをすべてのターゲット環境で自動的に調整する統一されたハブアンドスポークアーキテクチャを確立できます。

マルチクラスタArgoCDセットアップにおけるハブアンドスポークアーキテクチャの仕組み

マルチクラスタArgoCDセットアップにおけるハブアンドスポークアーキテクチャは、コアとなるArgoCDコントロールプレーンコンポーネントを単一の専用管理ハブクラスタにデプロイし、KubernetesサービスアカウントとTLSシークレットクレデンシャルを介してスポーククラスタを登録することで機能します。中央ハブクラスタは、Applicationコントローラ、APIサーバー、およびApplicationSetコントローラを実行し、宣言的な変更のためにGitリポジトリを継続的に監視します。スポークターゲットクラスタは、完全なArgoCDインストールを必要とせず、セキュアなAPI接続を介して中央ハブクラスタから直接アプリケーションリソースマニフェストを受信する管理されたエンドポイントとして動作します。

管理ハブクラスタは、argocd名前空間にKubernetes Secretのセットを保持します。各Secretは、ターゲットクラスタAPI URL、TLS CA証明書、およびサービスアカウントベアラートークンを含むターゲットスポーククラスタエンドポイントを表します。開発者がGitに構成の更新をコミットすると、中央のArgoCD Applicationコントローラはターゲットマニフェストを評価し、リモートスポーククラスタAPIエンドポイントと直接通信します。この一元化された設計により、すべてのターゲット環境に個別のArgoCDインスタンスをインストール、更新、および監視するオーバーヘッドがなくなるため、クラスタ管理が簡素化されます。

リモートスポーククラスタを中央管理ハブに登録するには、argocd cluster add CLIコマンドを使用するか、KubernetesにクラスタSecretを直接宣言します。

apiVersion: v1
kind: Secret
metadata:
  name: spoke-cluster-us-east-1
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
    environment: production
    region: us-east-1
type: Opaque
stringData:
  name: production-us-east-1
  server: https://api.prod-useast1.k8s.example.com:6443
  config: |
    {
      "bearerToken": "eyJhbGciOiJSUzI1NiIs...",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
      }
    }

environment: productionやregion: us-east-1のようなラベルがクラスタシークレットメタデータに直接適用されていることに注目してください。これらのラベルにより、ArgoCD ApplicationSetコントローラはクラスタターゲットを動的にクエリし、アプリケーションマニフェストファイルを手動で更新することなく、新しく参加したスポーククラスタにアプリケーションを自動的にデプロイできます。

ハブアンドスポークコントロールプレーン構造のアーキテクチャビューを次に示します。

                                +---------------------------+
                                | Git Repository            |
                                | (Declarative State)       |
                                +---------------------------+
                                              |
                                              | 1. Watches Commits
                                              v
+-----------------------------------------------------------------------------------+
| Management Hub Cluster (ArgoCD Control Plane)                                    |
| +-------------------------+   +------------------------+   +--------------------+ |
| | Application Controller  |   | ApplicationSet Engine  |   | Cluster Secrets    | |
| +-------------------------+   +------------------------+   +--------------------+ |
+-----------------------------------------------------------------------------------+
       | 2. Reconciles Spoke A         | 3. Reconciles Spoke B        | 4. Reconciles Spoke C
       v                               v                              v
+--------------------+       +--------------------+        +--------------------+
| Spoke Cluster A    |       | Spoke Cluster B    |        | Spoke Cluster C    |
| (Dev / US-East)    |       | (Prod / US-East)   |        | (Prod / EU-West)   |
+--------------------+       +--------------------+        +--------------------+

ApplicationSetコントローラはどのようにマルチクラスタデプロイメントを自動化しますか？

ApplicationSetコントローラは、Cluster、List、Git、Matrixジェネレータなどの宣言的ジェネレータアルゴリズムを使用して、複数のArgoCD Applicationカスタムリソースを動的に生成することで、マルチクラスタデプロイメントを自動化します。すべてのターゲットクラスタに対して個別のApplication YAMLマニフェストを手動で記述および保守する代わりに、単一のApplicationSetリソースがクラスタシークレットまたはGitディレクトリツリーを監視し、インフラストラクチャの拡張に応じて子アプリケーションを自動的に作成、更新、または削除します。

Clusterジェネレータは、特定のラベルセレクタに一致するargocd名前空間に登録されているすべてのクラスタSecretを評価します。一致するクラスタごとに、ジェネレータは{{name}}、{{server}}などのテンプレートパラメータとラベルメタデータ値をApplicationSet specのtemplateブロックに設定します。新しいスポーククラスタSecretが登録されると、コントローラはそのイベントを検出し、数秒以内に新しいクラスタをターゲットとする対応するApplicationオブジェクトをプロビジョニングします。

ClusterジェネレータとKustomizeオーバーレイを組み合わせた、完全で本番環境対応のApplicationSetマニフェストを次に示します。

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: payment-service-multi-cluster
  namespace: argocd
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            environment: production
  template:
    metadata:
      name: 'payment-service-{{name}}'
    spec:
      project: default
      source:
        repoURL: 'https://github.com/company-org/payment-service-gitops.git'
        targetRevision: HEAD
        path: 'overlays/{{metadata.labels.region}}'
      destination:
        server: '{{server}}'
        namespace: payment-system
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

この本番マニフェストでは、ジェネレータは登録されたクラスタをフィルタリングしてenvironment: productionに一致させます。一致する各クラスタについて、Gitリポジトリパスをoverlays/{{metadata.labels.region}}として動的に計算し、デプロイメントの宛先を{{server}}に設定します。このパターンにより、region: us-east-1でタグ付けされたクラスタは、カスタムCI/CDスクリプトループを記述することなく、overlays/us-east-1からKustomizeオーバーレイ構成を自動的にプルします。

複数の選択戦略を組み合わせる場合、Matrixジェネレータを使用すると、ClusterジェネレータとGitディレクトリジェネレータをペアにするなど、複数の子ジェネレータを相互参照できます。このマトリックスの組み合わせにより、単一の統合されたApplicationSet定義を使用して、50のターゲットクラスタにわたって数十の異なるマイクロサービスを同時にデプロイできます。

Sync Wavesを使用してロールアウトの順序とシーケンスを制御する方法

Sync Wavesを使用してロールアウトの順序とシーケンスを制御するには、Kubernetesマニフェストにargocd.argoproj.io/sync-waveアノテーションを追加して、リソースが作成、更新、または検証される正確な順序を指示します。デフォルトでは、ArgoCDはアプリケーション内のすべてのリソースを同時に適用します。これは、データベースの移行が完了する前やカスタムリソース定義（CRD）が登録される前にアプリケーションポッドが起動した場合にデプロイメントの失敗を引き起こす可能性があります。Sync Wavesは、リソースを負の整数値から正の整数値までの順序付けられた実行フェーズに編成します。

ArgoCDは、最も低いウェーブ番号（例：ウェーブ-5）から始まる昇順の数値順で同期ウェーブを評価します。コントローラは現在のウェーブに属するすべてのリソースを適用し、そのウェーブ内のすべてのリソースが正常な状態に達するまで待機し、その後、次の高いウェーブ（例：ウェーブ0）に属するリソースの評価に進みます。ウェーブ-2のリソースがヘルスチェックに失敗したり、クラッシュループに入ったりした場合、同期操作は直ちに停止し、後続のデプロイメントステップの実行を防止します。

デプロイメントロールアウトの前にデータベース移行ジョブを順序付けるために同期ウェーブアノテーションを適用する例を次に示します。

# Step 1: Database Migration Job (Sync Wave -2)
apiVersion: batch/v1
kind: Job
metadata:
  name: schema-migration-v2
  namespace: production
  annotations:
    argocd.argoproj.io/sync-wave: "-2"
    argocd.argoproj.io/hook: Sync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: ghcr.io/company-org/db-migrator:v2.1.0
restartPolicy: Never
---
# Step 2: Main Application Deployment (Sync Wave 0)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-api
  namespace: production
  annotations:
    argocd.argoproj.io/sync-wave: "0"
spec:
  replicas: 5
  template:
    spec:
      containers:
        - name: api
          image: ghcr.io/company-org/payment-api:v2.1.0

Sync WavesとArgoCDリソースフック（PreSync、Sync、PostSync、およびSyncFail）を組み合わせることで、システムエンジニアはデプロイメントライフサイクルイベントを完全に制御できます。データベース移行ジョブにargocd.argoproj.io/hook: Syncをアノテーションすると、ArgoCDは同期フェーズ中にジョブを実行し、argocd.argoproj.io/hook-delete-policy: HookSucceededは正常な実行時に完了した移行ポッドリソースを自動的にクリーンアップします。

ステージング環境と本番環境にわたる複雑なマルチクラスタロールアウトの場合、Sync WavesをArgo Rolloutsなどのプログレッシブデリバリーツールと組み合わせます。Argo Rolloutsは、カナリアおよびブルー/グリーン戦略でデプロイメント機能を拡張し、クラスタ全体のプロモーションを完了する前に、ライブ本番トラフィックの5%を新しくデプロイされたスポーククラスタポッドにルーティングし、Prometheusエラーレートメトリクスを自動的に分析できます。

KustomizeとHelmオーバーレイを使用して環境固有の構成を管理する方法

環境固有の構成を管理するには、共通のリソース定義を含むベースマニフェストディレクトリと、KustomizeまたはHelm valuesファイルを使用する環境オーバーレイディレクトリにGitリポジトリを構造化します。ベースインフラストラクチャテンプレートと環境固有のパラメータを明確に分離することで、コアアプリケーション仕様がDRY（Don't Repeat Yourself）を維持しつつ、個々のスポーククラスタがレプリカ数、イングレスドメイン、リソース制限をオーバーライドできるようになります。

Kustomizeオーバーレイ構造を使用する場合、base/ディレクトリは、すべてのクラスタで共有される汎用的なDeployment、Service、およびConfigMapマニフェストを定義します。各環境オーバーレイフォルダ（例：overlays/staging、overlays/prod-us-east、overlays/prod-eu-west）には、共通のベースをインポートし、リソースクォータの調整、レプリカ数、カスタム環境変数などのパッチ変更を適用するkustomization.yamlファイルが含まれています。

マルチクラスタKustomizeデプロイメントの典型的な本番Gitリポジトリディレクトリ構造を次に示します。

payment-service-gitops/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   ├── replica_patch.yaml
    │   └── kustomization.yaml
    ├── prod-us-east-1/
    │   ├── configmap_patch.yaml
    │   ├── ingress_patch.yaml
    │   └── kustomization.yaml
    └── prod-eu-west-1/
        ├── configmap_patch.yaml
        └── kustomization.yaml

本番オーバーレイターゲットのkustomization.yamlの内容を検査します。

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
metadata:
  name: prod-us-east-1-overlay

resources:
  - ../../base

patchesStrategicMerge:
  - replica_patch.yaml

configMapGenerator:
  - name: app-config
    behavior: merge
    literals:
      - REGION=us-east-1
      - LOG_LEVEL=warn
      - DB_MAX_CONNECTIONS=100

組織がKustomizeよりもHelmチャートパッケージングを好む場合、ArgoCDはカスタムHelm valuesファイルを渡したり、Application仕様で個々のパラメータ値を直接オーバーライドしたりすることをネイティブにサポートしています。Applicationテンプレート内でvalueFiles配列を使用すると、複数のvaluesファイルを連結し、共有のvalues-prod.yamlベースラインを適用し、その後にクラスタ固有のvalues-us-east-1.yamlオーバーライドファイルを適用できます。

AppProjectコントロールを介してマルチテナント分離とセキュリティを強制する方法

マルチテナント分離とセキュリティを強制するには、ArgoCD AppProjectカスタムリソースを定義して、特定のエンジニアリングチームがアクセスできるソースGitリポジトリ、ターゲットクラスタの宛先、名前空間の境界、および許可されるKubernetesリソースの種類を制限します。デフォルトでは、ArgoCDアプリケーションはdefaultプロジェクトに属しており、接続されている任意のターゲットクラスタに任意のリソースタイプをデプロイするための無制限のアクセスを許可します。専用のAppProjectマニフェストを作成することで、テナントチーム間の厳格なRBAC境界を確立します。

AppProjectリソースは、関連するアプリケーションのグループを囲む論理的なセキュリティ境界として機能します。仕様は、sourceRepos（どのGitリポジトリがマニフェストを提供できるか）、destinations（どのクラスタAPIサーバーと名前空間がデプロイメントを受け入れることができるか）、およびclusterResourceWhitelist（NamespacesやCRDなどのどのクラスタスコープのリソースを管理できるか）の明示的なホワイトリスト配列を定義します。

テナントエンジニアリングチームを分離する本番環境のAppProjectマニフェストを次に示します。

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: checkout-team-project
  namespace: argocd
spec:
  description: "Isolated project boundary for Checkout service team"
  sourceRepos:
    - 'https://github.com/company-org/checkout-*.git'
  destinations:
    - server: 'https://api.prod-useast1.k8s.example.com:6443'
      namespace: checkout-production
    - server: 'https://api.staging.k8s.example.com:6443'
      namespace: checkout-staging
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
  namespaceResourceBlacklist:
    - group: ''
      kind: ResourceQuota
  roles:
    - name: developer
      description: "Developer read-only and sync access"
      policies:
        - p, proj:checkout-team-project:developer, applications, get, checkout-team-project/*, allow
        - p, proj:checkout-team-project:developer, applications, sync, checkout-team-project/*, allow
      groups:
        - "github-org:checkout-developers"

このセキュリティ仕様では、checkout-developers GitHub組織チームに属する開発者は、checkout-team-projectに割り当てられたアプリケーションに対してのみ同期操作をトリガーできます。さらに、このプロジェクトのアプリケーションは、checkout-productionまたはcheckout-staging以外の名前空間への書き込みを厳しく禁止されており、共有スポーククラスタで実行されている隣接するテナントワークロードを不正なクロス名前空間変更から保護します。

悪意のある構成がクラスタレベルのセキュリティ設定を変更するのを防ぐには、namespaceResourceBlacklistブロックを使用して機密性の高いKubernetesリソースタイプを制限します。ResourceQuota、LimitRange、またはClusterRoleBindingなどのリソースをブラックリストに登録することで、テナントチームがクラスタセキュリティポリシーを変更したり、割り当てられたリソース制限を超えたりするのを防ぎます。

マルチクラスタ同期の健全性とメトリクスを監視する方法

マルチクラスタ同期の健全性を監視するには、ArgoCD Application ControllerによってエクスポートされたPrometheusメトリクスをスクレイピングし、Grafanaダッシュボードを構成し、ArgoCD Notificationsを使用して自動化されたSlackまたはPagerDutyアラートを送信します。すべてのスポーククラスタにわたるテレメトリ監視を一元化することで、プラットフォームエンジニアは同期の失敗、同期外の構成ドリフト、API接続の切断を即座に検出できます。

ArgoCDは、アプリケーションコントローラデプロイメントのポート8082で広範なPrometheusメトリクスをエクスポートします。argocd_app_infoなどのメトリクスは、管理対象アプリケーションごとのアクティブな同期ステータス、ヘルスステータス、およびターゲットクラスタの宛先を記録し、argocd_app_reconcile_countはリモートスポーククラスタエンドポイントにわたるコントローラ調整パフォーマンスを追跡します。

本番環境でマルチクラスタArgoCDの健全性を監視するための主要なPromQLクエリを次に示します。

# 1. Count of Applications currently Out of Sync across all spoke clusters
sum(argocd_app_info{sync_status!="Synced"}) by (dest_server, name)

# 2. Count of Applications in Degraded Health state
sum(argocd_app_info{health_status="Degraded"}) by (dest_server, name)

# 3. Average reconciliation latency for spoke cluster API calls (seconds)
rate(argocd_app_reconcile_bucket{le="10"}[5m]) / rate(argocd_app_reconcile_count[5m])

ArgoCD Notificationsコントローラをデプロイすると、リアルタイムのアプリケーションライフサイクルイベントに基づいて自動アラートをトリガーできます。ApplicationまたはApplicationSetマニフェストにrecipients: slack:devops-alertsをアノテーションすることで、リモートスポーククラスタで同期操作が失敗するたびに、ArgoCDはGitコミットメタデータ、差分リンク、および失敗ログを含む即時Slack通知を送信します。

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: payment-service-prod
  annotations:
    notifications.argoproj.io/subscribe.on-sync-failed.slack: devops-alerts
    notifications.argoproj.io/subscribe.on-health-degraded.slack: devops-alerts

プロアクティブなアラートとGrafanaダッシュボードの視覚化を統合することで、マルチクラスタGitOpsデプロイメント全体で高い運用信頼性が保証されます。プラットフォームチームは、リモートクラウドリージョンへの接続におけるネットワーク遅延の急増を特定し、Git認証のタイムアウトに対処し、アプリケーションのパフォーマンスがエンドユーザーエクスペリエンスに影響を与える前に、失敗した同期フックを解決できます。

ArgoCDマルチクラスタデプロイメントに関するよくある質問

ArgoCDはリモートスポーククラスタとどのように安全に認証しますか？

ArgoCDは、中央管理ハブクラスタのKubernetes Secret内に安全に保存されているKubernetes Service AccountベアラートークンまたはX.509クライアント証明書を使用して、リモートスポーククラスタと認証します。argocd cluster addを使用してスポーククラスタを登録すると、CLIクライアントはスポーククラスタのkube-system名前空間内に専用のargocd-manager ServiceAccountを作成し、長期間有効なAPIベアラートークンを生成し、ターゲットクラスタのクレデンシャルを暗号化されたSecretとしてハブクラスタに保存します。

中央のArgoCDハブクラスタがクラッシュした場合、スポーククラスタで実行中のワークロードはどうなりますか？

中央のArgoCDハブクラスタがクラッシュしたり、ネットワーク接続を失ったりしても、スポーククラスタで実行中のアプリケーションワークロードは完全に影響を受けずに実行され続けます。ArgoCDはインラインランタイムプロキシではなく、非同期調整エンジンとして動作します。スポーククラスタのポッド、サービス、およびイングレスルールは完全に機能し続けます。中央ハブクラスタが回復すると、ArgoCDはGitリポジトリの監視を再開し、停止中に発生した状態の変更を調整します。

マルチクラスタGitOpsワークフローでシークレット管理を安全に処理する方法は？

シークレット管理を安全に処理するには、Bitnami Sealed Secrets、Mozilla SOPSなどのシークレット暗号化ツール、またはExternal Secrets Operator（ESO）とAWS Secrets ManagerまたはHashiCorp Vaultを組み合わせた外部シークレットオペレータを使用します。プレーンテキストのシークレット値をGitリポジトリにコミットしないでください。External Secrets Operatorを使用すると、宣言的なExternalSecretマニフェストをGitにコミットし、各スポーククラスタで実行されているESOが実行時にVaultまたはAWS Secrets Managerから生のシークレットペイロードを直接フェッチします。

ArgoCD同期ポリシーにおける自動プルーニングと自己修復の違いは何ですか？

自動プルーニング（prune: true）は、対応するマニフェストファイルがGitリポジトリから削除されたときに、ArgoCDにKubernetesリソースをスポーククラスタから自動的に削除するように指示します。自己修復（selfHeal: true）は、kubectlを介してスポーククラスタリソースに直接行われた手動変更をArgoCDに自動的に上書きまたは元に戻すように指示し、クラスタの状態をGitの宣言的な真実のソースと一致させます。

単一の大きなApplicationSetを実行すべきか、複数の小さなApplicationSetを実行すべきか？

単一の巨大なApplicationSetマニフェストですべての組織ワークロードを管理するのではなく、アプリケーションドメイン、サービス層、またはエンジニアリングチームの責任によって論理的にグループ化された複数の小さなApplicationSetを実行すべきです。ApplicationSetを分割することで、構成変更時の爆発半径を減らし、トラブルシューティングを簡素化し、異なるチームが異なる同期ポリシー、クラスタ選択ラベル、およびRBAC権限を構成できるようになります。

バルク同期中にArgoCDがリモートスポーククラスタAPIサーバーを過負荷にしないようにするにはどうすればよいですか？

APIサーバーの過負荷を防ぐには、ArgoCD Application Controllerの--app-resync-periodおよび--status-processorsフラグを調整し、ApplicationSet specジェネレータ内でsyncOptions: Limit=1またはmaxConcurrency設定を構成します。再同期間隔をデフォルトの3分から10〜15分に増やすと、リモートスポークAPIサーバーへの継続的な読み取りクエリ負荷が軽減され、信頼性の高い調整頻度が維持されます。

App-of-Appsブートストラップパターンとは何ですか？また、ApplicationSetと比較してどうですか？

App-of-Appsパターンは、単一のマスターArgoCD Applicationが複数の子ApplicationリソースのYAMLマニフェストを含むGitリポジトリディレクトリを指す宣言的なブートストラップパターンです。App-of-Appsパターンは静的なクラスタトポロジにはうまく機能しますが、ApplicationSetsは動的なマルチクラスタ環境で優れた機能を提供します。これは、ApplicationSetがプログラムジェネレータを使用して、シークレットラベルとGitブランチ構造に基づいてクラスタエンドポイントを動的に検出するためです。

おすすめ記事

• Advanced CI/CD: Blue-Green Deployments and Canary Releases
• High-Performance Observability with eBPF in Kubernetes: Bypassing the Sidecar Tax
• Kubernetes HPA with Custom Prometheus Metrics: Beyond CPU Scaling (2026)
• Prometheus Grafana Alerting and Burn Rate Design