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

はじめに

私たちは普段、アプリケーションのコードを Git で厳格に管理しています。プルリクエストでレビューを行い、履歴を残し、いつでも過去のバージョンに戻せるようにしています。

では、そのアプリが動くインフラ（Kubernetes）の設定はどうでしょうか？　もし、インフラの設定変更だけが属人的なコマンド操作で行われているのであれば、そこには大きなリスクが潜んでいます。

GitOps は、Git リポジトリを「唯一の真実の情報源（Single Source of Truth）」と定義し、Kubernetes の状態を Git に自動追従させる手法です。

今回は、開発者が安心してリリースできる環境を作るための「GitOps」の中核を担うツールである ArgoCD のインストールと、その主要コンポーネントについて調査・実践した内容をご覧ください。

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 (カスタムリソース定義) です。これにより、Application 等の Argo CD 独自のカスタムリソースを、Deployment や Service 等と同じように Kubernetes のリソースとして扱えるようになります。

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. Core Components

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

argocd-server
- 私たちが触れる Web UI と API サーバーです。ログイン認証や認可も部分的に担当します。
argocd-repo-server
- Git リポジトリとの通信を担当します。Git からマニフェストを取得し、Kustomize や Helm などのテンプレートを処理して、プレーンな Kubernetes YAML を生成します。
argocd-application-controller
- Application CRD の定義を監視し、argocd-repo-server が生成したマニフェストと、Kubernetes クラスターの現在の状態を比較します。
- 差分があれば「OutOfSync」と判断し、syncPolicy に従ってリソースを適用（同期）し、ヘルスチェックを実行します。

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

続いて、 ArgoCD におけるアプリケーションのセットアップについて整理します。 Argo CD の Application リソースは、デプロイ元の 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/xxxx/gitops-sample.git # project 名はマスクしています
    targetRevision: HEAD
    path: .
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated: {} # 今回は手動syncに設定（必要に応じてコメントアウト）

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

( 今回はサンプルとして以下のようなマニフェストファイルを https://gitlab.com/xxxx/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 を学び始める方の参考になれば幸いです。