🏗️ Argo CDアーキテクチャ完全解剖: GitOpsの心臓部を覗く

6月 22, 2026

—

こんにちは！Kubernetes環境で宣言的継続的デリバリー（Declarative CD）を可能にするArgo CD。「Gitにプッシュすればデプロイされる」という単純な結果の裏には、非常に精巧に設計されたマイクロサービスアーキテクチャが隠されています。

今回は、Argo CDを構成する主要コンポーネント、それらの間のデータフロー、そしてなぜこのような構造で設計されたのかについて深く掘り下げていきます。🛠️

https://argo-cd.readthedocs.io/en/stable/operator-manual/architecture/

1. 🌐 Argo CDアーキテクチャ概要 (High-level View)

Argo CDは、大きく分けて3つの主要サービスで構成されるマイクロサービスアーキテクチャです。各サービスは独立した役割を果たし、クラスター内部で有機的に通信します。

主要コンポーネント

API Server: ユーザーと外部ツールのゲートウェイ
Repository Server (Repo Server): ソースコード(Git)管理の中心
Application Controller: クラスターの状態を監視する脳

2. 🚦 API Server: ゲートウェイとセキュリティ

API Serverは、ユーザー(UI/CLI)や外部システム(CIツール)がArgo CDと対話するための唯一の窓口です。gRPC/RESTサーバーとして実装されています。

認証および認可 (AuthN/AuthZ): ユーザーが誰であるかを確認し、argocd-rbac-cmで定義された権限をチェックします。
アプリケーション管理: アプリケーションの作成、変更、削除リクエストを処理します。
RBAC適用: 特定のプロジェクト(AppProject)に対するアクセス制御を実行します。

💡 ヒント: 以前に扱ったScoped Tokenも、このAPI Serverが検証・処理する重要なセキュリティ要素です。

3. 📂 Repository Server: ソースの真実 (Source of Truth)

Repository Serverは内部キャッシュを保持し、Gitリポジトリのマニフェストを管理します。

マニフェスト生成: GitにあるHelm、Kustomize、または生のYAMLファイルを、Argo CDが理解できる純粋なKubernetesオブジェクトとしてレンダリングします。
キャッシングエンジン: 毎回Gitから取得すると遅くなるため、変更がない場合はローカルキャッシュを活用してパフォーマンスを最大化します。
Kustomize/Helmサポート: 以前議論したkustomize.path設定などを通じて、特定のバイナリバージョンでレンダリング作業を実行するのがここです。

💻 (参考) Repo Serverカスタム設定例

以前学んだInitContainerの手法を使って、Repo ServerにHelmリポジトリを事前登録する設定のアーキテクチャ上の位置を確認してください。

YAML

# argocd-repo-serverは、レンダリングのために外部Helmリポジトリと通信できる状態である必要があります。
containers:
- name: argocd-repo-server
  env:
  - name: ARGOCD_REPO_SERVER_HELM_BIN
    value: "/usr/local/bin/kustomize-v5" # カスタムバイナリを使用する場合

4. 🧠 Application Controller: 状態の守護者

このコンポーネントこそが、Argo CDの「脳」であり、GitOpsの核となるエンジンです。

継続的監視 (Continuous Monitoring): 現在実行中のクラスターの状態(Live State)とGitで定義された状態(Desired State)を絶えず比較します。
状態判断 (Health Assessment): 私たちがargocd-cmで定義したresource.customizations.health Luaスクリプトが実行される場所がここです。
自動復旧 (Self-Healing): クラスターで誰かが手動で設定を変更した場合、Gitの状態に自動的に戻す作業を実行します。

5. 🔄 データフロー: デプロイが発生する過程

ユーザーがSyncボタンを押したときにアーキテクチャ内部で何が起こるかを段階的に見ていきましょう。

ユーザーリクエスト: ユーザーがUI/CLIを通じてAPI ServerにSyncコマンドを送信します。
マニフェストリクエスト: API ServerはRepo Serverに「最新コミットバージョンでマニフェストをレンダリングして」とリクエストします。
レンダリング: Repo ServerはGitからコードを取得し（またはキャッシュから）、Helm/Kustomizeを実行して最終的なYAMLを作成します。
比較と実行: Application Controllerは、受け取ったYAML(Desired)と現在のクラスターの状態(Live)を比較し、変更点のみをクラスターに適用(Apply)します。
状態更新: デプロイが完了すると、Controllerは最終状態を記録し、UIにSyncedまたはHealthyバッジを表示します。

6. 🏗️ 高度なアーキテクチャ: HA(High Availability)構成

運用環境では、サービス中断を防ぐために各コンポーネントを高可用性モードで運用します。

Redis: Repo Serverのキャッシュデータを保存する外部ストレージとして機能し、複数のRepo Serverが状態を共有できるようにします。
Sharding: 管理するクラスターが数千に及ぶ場合、Application Controllerを複数に分割（Sharding）して負荷を分散します。

💻 Controller Sharding設定例 (argocd-cmd-params-cm)

YAML

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cmd-params-cm
data:
  # 1つのコントローラーが担当するクラスターの数を制限し、シャーディングを促します。⚖️
  controller.replicas: "2"
  controller.cluster.sharding.algorithm: "round-robin"

📝 要約テーブル: アーキテクチャコンポーネント比較


コンポーネント	主要な役割	関連設定ファイル	比喩

—	—	—	—
API Server	認証、認可、API提供	argocd-rbac-cm	案内デスク
Repo Server	マニフェストレンダリング、キャッシング	argocd-cm (kustomize)	翻訳・設計局
Controller	状態比較、同期、復旧	argocd-cm (health)	現場監督
Redis	データキャッシュ共有		共同メモ帳

—

💡 終わりに

Argo CDのアーキテクチャは、「状態を定義する場所(Git)」と「状態を維持する場所(Cluster)」の間のギャップを埋めるために、徹底的に分業化されています。この構造を理解することで、トラブルシューティングが発生した際にどのコンポーネントのログを見るべきかが明確になります。

ログインできない場合は？ → API Server
Gitの変更が反映されない場合は？ → Repo Server
デプロイは完了したが、Progressingのままの場合は？ → Application Controller

皆様のクラスターを守る、これらの見えないヒーローたちの構造を理解する一助となれば幸いです！ 🎯