Argo CD 入門：GitOps 実践に向けたセットアップと主要コンポーネントの解説

Last updated at 2025-11-04Posted at 2025-11-03

はじめに

現在参画しているプロジェクトのアーキテクチャでは GitOps といわれる手法が取り入れられています。その中核を担うのが、Kubernetes ネイティブな継続的デリバリー（CD）ツールである Argo CD です。

Argo CD は、Git リポジトリを「信頼できる唯一の情報源（Single Source of Truth）」として、Kubernetes クラスターの状態を Git リポジトリで定義している望ましい状態に自動的に同期させる役割を担います。

この記事では、私がプロジェクトに参画する際に、アーキテクチャをスムーズにキャッチアップするために学習した内容について整理します。Argo CD のインストールと、その中核をなす主要コンポーネントについて調査・実践した内容をご覧ください。

Argo CD のインストールとマニフェストの理解

Argo CD の公式ドキュメントに従い、まずは基本的なインストールを行います。

# Argo CD 専用の名前空間を作成
kubectl create namespace argocd

# 公式マニフェストを適用
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

この install.yaml は何をしているのでしょうか？
リンク先を確認すると、約 25,000 行にも及ぶ巨大なマニフェストファイルでした。すべてを読むのは大変なので、Argo CD において重要な定義を3つのカテゴリに分けてまとめました。

1. CRD (Custom Resource Definition)

install.yaml の冒頭では、Argo CD が動作するために必要な「独自の言語」を Kubernetes に教えています。これが CRD (カスタムリソース定義) です。これにより、私たちは Deployment や Service と同じように、Application といった Argo CD 独自のカスタムリソースを kubectl で扱えるようになります。

applications.argoproj.io

Application は、Argo CD の最も中心的なリソースです。これこそが「1つの Git リポジトリ」と「1つのデプロイ先」を関連付ける定義ファイルです。

主な役割:
- source: どの Git リポジトリの、どのブランチ (targetRevision)、どのディレクトリ (path) を監視するかを定義します。
- destination: どの Kubernetes クラスター (server) の、どの名前空間 (namespace) にデプロイするかを定義します。
- syncPolicy: 自動同期 (automated) や、Git から消えたリソースをクラスターからも削除するか (prune: true) などの同期ルールを管理します。

applicationsets.argoproj.io

ApplicationSet は、その名の通り Application リソースの「セット（集合）」を自動生成するための強力なテンプレートエンジンです。

主な役割:
- テンプレート: Application の定義をテンプレート化できます。
- ジェネレーター: 「GitLab グループ内の全リポジトリ」や「特定のブランチパターン（例: feature/*）」、「複数のデプロイ先クラスター」といった条件から、複数の Application リソースを動的に生成・管理します。
- ユースケース: マルチクラスター運用や、ブランチごとのプレビュー環境の自動構築に不可欠です。

appprojects.argoproj.io

AppProject は、セキュリティとガバナンスを強化するための**「プロジェクト」という論理的なグループ**を定義します。

主な役割:
- アクセス制御 (RBAC): どの開発者（SSO グループ）が、どの AppProject にアクセスできるかを制限します。
- ソースリポジトリの制限: プロジェクトが参照できる Git リポジトリをホワイトリスト形式で限定できます。
- デプロイ先の制限: プロジェクトがデプロイできるクラスターや名前空間を制限できます。

2. Service Account と権限 (RBAC)

Argo CD は Kubernetes クラスター内で動作する自動化ツールであり、リソース（Deployment など）を作成・変更・削除するための強力な権限を必要とします。

install.yaml では、セキュリティのベストプラクティスである「最小権限の原則」に従い、コンポーネントごとに個別の ServiceAccount（サービスアカウント）を作成しています。

argocd-application-controller:
実際にリソースを同期する最も重要なコンポーネント。ClusterRole を通じて、Argo CD が管理するリソースに対する広範な操作権限が与えられます。
argocd-server:
UI/API サーバー。Secret（例: ログインセッション）の読み書きや、Application リソースの操作権限など、サーバー機能に必要な権限を持ちます。
argocd-repo-server:
Git リポジトリへのアクセスとマニフェストの解析のみを担当します。Kubernetes API へのアクセス権限は最小限に抑えられています。

このように役割を分離することでリスクを低減しています。

3. Core Components (Deployments)

最後に、install.yaml は Argo CD を構成する主要なコンポーネントを Deployment や StatefulSet としてデプロイします。

argocd-server (Deployment)
- 役割: 私たちが触れる Web UI と API サーバーです。DEX（下記）と連携し、ログイン認証や認可も担当します。
argocd-repo-server (Deployment)
- 役割: Git リポジトリとの通信を担当します。Git からマニフェストを取得し、Kustomize や Helm などのテンプレートを処理して、プレーンな Kubernetes YAML を生成します。
argocd-application-controller (StatefulSet)
- **役割:Application CRD の定義を監視し、argocd-repo-server が生成したマニフェストと、Kubernetes クラスターの現在の状態を比較します。
- 差分があれば「OutOfSync」と判断し、syncPolicy に従ってリソースを適用（同期）し、ヘルスチェックを実行します。
argocd-dex-server (Deployment)
- 役割: 認証プロバイダー。デフォルトのローカルユーザー（admin）管理のほか、OIDC や SAML（例: GitLab, Google）と連携した **SSO（シングルサインオン）**機能を提供します。
argocd-redis (Deployment)
- 役割: キャッシュサーバー。UI のセッション情報、Git の ETag、マニフェストのキャッシュなどを保存し、システム全体のパフォーマンスを向上させます。
argocd-notifications-controller (Deployment)
- 役割: 通知機能。同期の成功・失敗やヘルス状態の変化を検知し、Slack や Email などに通知を送信します。

宣言的なアプリケーションのセットアップ

続いて、 ArgoCD におけるアプリケーションのセットアップについて整理します。
このアプリケーションとは、どの Gitリポジトリをソースにするか、どの Kubernetesクラスター、Namespace にデプロイするかを決定する単位です。
install.yaml を適用し、Argo CD が起動しても、それだけでは何もデプロイされません。Argo CD に「何をデプロイしてほしいか」をアプリケーションの定義を通して伝える必要があります。

もちろん UI から手動でリポジトリを登録することも可能ですが、GitOps の原則に則るのであれば、「Argo CD に何をデプロイさせるか」という定義自体も Git で宣言的に管理するのがベストプラクティスです。

これは、先ほど学んだ Application CRD を使って実現できます。

# my-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd # Argo CDが稼働する名前空間に作成
  finalizers:
  - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc # デプロイ先クラスター
    namespace: guestbook # デプロイ先の名前空間
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

このような YAML ファイルを Git リポジトリにコミットし、kubectl apply -f my-app.yaml で一度だけクラスターに適用します。

この手法は App of Apps パターン と呼ばれ、Argo CD がこの my-app.yaml を監視し、guestbook アプリケーションのデプロイを自動的に開始・管理します。

Tips: 実際の Setup の様子、要点をかいつまんで、、、

ここでは、Argo CD で管理する Application リソースを宣言的に定義・同期する流れを、実際の操作例とともに紹介します。

⸻

1. GitLabでPersonal Access Token（PAT）を発行する

まず、Argo CDがGitLab上のリポジトリにアクセスできるようにするため、
Personal Access Token（PAT）を作成します。
これは Argo CD の argocd-repo-server がリポジトリをクローンする際の認証に使われます。

•	Token name: argocd-read ( 任意の名前 )
•	Scope: read_repository ( 最小限の権限 )
•	Expiration date: セキュリティのために設定

このトークンをArgo CDのUIまたはCLI経由で登録します。
CLIの場合は以下のように設定します。

argocd repo add https://gitlab.com/<group>/<repo>.git \
  --username <your-username> \
  --password <personal-access-token> \
  --name gitlab-repo

⸻

2. ApplicationをYAMLで定義する

GitOpsの基本は「状態をYAMLで宣言し、それをGitに保存する」ことです。
Argo CDが監視するGitリポジトリに、以下のような Application マニフェストを配置します。

# nginx-test-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-test
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitlab.com/sandbox9094443/gitops-sample.git
    targetRevision: HEAD
    path: .
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated: {} # 今回は手動syncに設定（必要に応じてコメントアウト）

このファイルをGitLab上にコミットします。
Argo CDはこのYAMLを検知し、Git上の定義どおりにKubernetesリソースを同期します。

( 今回はサンプルとして以下のようなマニフェストファイルをhttps://gitlab.com/sandbox9094443/gitops-sample.gitに置いています。 )

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx-app
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 1
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: my-nginx-service
spec:
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
  type: LoadBalancer # ローカルKubernetesではNodePortとして動作

⸻

3. 初回Sync：Gitの状態をクラスターへ反映

Argo CDのUIでアプリケーションが検出されると、初期状態は OutOfSync です。
これは「Git上にある定義（Desired State）」が、まだクラスターに適用されていない状態です。

「Sync」ボタンをクリックすると、Argo CDがGitリポジトリからマニフェストを取得し、
Kubernetes APIを介して Deployment や Service を作成します。

•	AUTO-CREATE NAMESPACE：Namespaceを自動作成
•	SERVER-SIDE APPLY：サーバー側で差分適用

⸻

4. 同期成功：Gitとクラスタが一致した状態

同期が完了すると、Sync Status が Synced に、App Health が Healthy に変わります。
Argo CD は、Git 上の定義どおりに Kubernetes 上のリソースを再現します。

nginx-test → Service → Deployment → Pod という構成がツリー表示され、
実際に Pod が起動していることが確認できます。

⸻

5. Gitの変更を検知してOutOfSyncへ

次に、GitLab上で app.yaml を編集し、Deployment の replicas を変更してみます。

変更をコミットすると、Argo CDのUI上で OutOfSync が再び検出されます。
これは、Git上の「望ましい状態」と、Kubernetes上の「現在の状態」がずれていることを示しています。

⸻

6. 再Sync：変更を自動で反映

「Sync」を再度実行すると、Argo CDが差分を適用し、
Podが3つにスケールされ、Gitの定義どおりの状態に戻ります。

Git → Argo CD → Kubernetes の変更伝播が、完全に自動化されていることが確認できます。

まとめ

Argo CD の install.yaml は、単なるインストールスクリプトではなく、CRD による Kubernetes の拡張、最小権限に基づいた RBAC 設定、そしてマイクロサービスとして連携する堅牢なコンポーネント群がすべて詰まったパッケージでした。

実務で「Argo CD がうまく動かない」といった問題に直面した際、argocd-repo-server（Git 接続）の問題なのか、argocd-application-controller（同期）の問題なのか、コンポーネントの役割を理解しているかどうかが、トラブルシューティングの速度に直結すると感じました。

今回の記事が、これから Argo CD を学び始める方の参考になれば幸いです。

追記：実務で見た、大規模な GitOps アーキテクチャ

Argo CD の基本コンポーネントや CRD を学習した後、私は実際に大規模なプロジェクトに配属されました。

そこで私が見たのは、学習で構築したサンプルのようなシンプルな構成ではなく、「関心の分離」 を追求した GitOps アーキテクチャでした。

1. リポジトリの分離

私が学習したサンプルでは、アプリケーションの定義（Application CRD）とデプロイするマニフェスト（Deployment.yaml など）が同一リポジトリで管理されることもありました。

しかし、実務では 役割（責任） に応じて、リポジトリが以下のように分離されていました。

① アプリケーションリポジトリ (Application Repo)
- 役割: アプリケーションのソースコードを管理します。
- CI の責務: コードをビルド・テストし、コンテナイメージを作成して GAR (Google Artifact Registry) にプッシュします。
② Helm Chart リポジトリ (Chart Repo)
- 役割: アプリケーションを Kubernetes にデプロイするための「テンプレート」（Helm Chart）を管理します。
- CI の責務: チャートをパッケージ化し、GAR に Helm OCI イメージとしてプッシュします。
③ アプリケーションマニフェストリポジトリ (Manifest Repo)
- 役割: **「設定」**を管理します。どのコンテナイメージとどの Helm Chart を使うかを values.yaml ファイルで定義します。
- GitOps のキー: リリースマネージャーが変更するのは、基本的にこのリポジトリの values.yaml だけです。
④ Argo CD アプリケーション定義リポジトリ (App of Apps Repo)
- 役割: Argo CD に「どのアプリケーションを監視すべきか」を教える役割を担います。
- GitOps の起点: Argo CD が最初に監視するのはこのリポジトリです。このリポジトリに Application CRD を追加すると、Argo CD はその指示に従い、③のリポジトリ（マニフェストリポジトリ）の監視を開始します。

2. 「values.yaml」が集約するリリース管理の利点

このアーキテクチャで最も印象的だったのは、デプロイ（リリース）行為が「values.yaml を変更するプルリクエスト」に集約される点です。

CI フェーズ（①と②）でコンテナイメージと Helm OCI イメージがビルドされ GAR に「準備」されても、それだけではまだ環境にはデプロイされません。

リリース担当者が「③ アプリケーションマニフェストリポジトリ」にある values.yaml を編集し、image.tag や chart.version を新しいバージョンに書き換えて Git にコミット（プッシュ）した瞬間、それが ArgoCD によって検知され、初めてデプロイが実行されます。

この「リリース＝ values.yaml の変更」という仕組みが、バージョン管理と監査（ガバナンス）を極めて容易にしていました。

バージョン管理の簡潔さ : 「現在、本番環境で動いているアプリケーションはどのバージョンか？」を知りたい時、クラスターに kubectl でアクセスする必要はありません。values.yaml の image.tag を見れば、それが唯一の正解です。Git のコミット履歴を追うだけで、過去にどのバージョンがデプロイされていたかも正確にわかります。
監査の容易さ : すべてのデプロイ変更は、Git のマージリクエストとして記録されます。これにより、 「誰が」「いつ」 そのリリースを承認し実行したのか、すべての証跡が Git 上に明確に残ります。インシデント発生時の原因調査や、変更の差し戻し（Revert）も、Git の操作で完結できます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up