ArgoCDとは？GitOpsの仕組みとインストール・Sync設定をコード付きで解説

ArgoCD（Argo CD）は、Gitリポジトリを「信頼できる唯一の情報源」として、Kubernetesクラスターの状態をマニフェストどおりに保ち続ける宣言的なGitOps継続的デリバリーツールです。この記事では、Gitを定期的に読みに行って差分を埋めるプル型同期の仕組みから、kubectlでの導入手順、Application・Sync・Self-healのYAML設定例、ApplicationSetで多数のアプリを束ねる書き方までを、公式ドキュメントの一次情報とそのまま動かせる設定例で追います。さらにCI/CDパイプラインやFlux CDとの役割分担、採用すべき条件と見送るべき場面まで、Kubernetes運用で迷う論点を実装者目線で示します。

まとめ：ArgoCDの仕組みとGitOps運用・採用判断の要点

ArgoCDは、Kubernetesへ何をデプロイするかをGit上のマニフェストで宣言し、クラスター内のArgoCDがそのGitを定期的に読みに行って、実際のクラスター状態を宣言状態へ継続的に近づけるプル型のGitOpsツールです。CIがコンテナイメージをビルドしてレジストリへ押し込むところまでを担い、ArgoCDはその先の「クラスターへ届ける」CDフェーズを引き受ける、と役割を分けると全体像が整理できます。

導入の入口はkubectl create namespace argocdと公式マニフェストの適用で、admin初期パスワードはargocd-initial-admin-secretから取り出します。同期の挙動はautomated・prune・selfHealの3フィールドで宣言的に決め、失敗時の再試行もretryに回数とバックオフを書いて制御する設計です。ArgoCDはArgoプロジェクトの一部としてCNCFのGraduatedプロジェクトに位置づけられ（Argoは2022年12月にGraduated到達）、本番Kubernetesのアプリ配信で広く使われています。

版番号は公式のリリース一覧で確認でき、2026年9月時点の安定版はv3.5系（最新はv3.5.2、v3.5.0は2026年8月にGA）で、v3.4系もv3.4.8としてパッチ提供が続いています。導入の是非は、Kubernetesを常時運用しておりデプロイの監査性・再現性を高めたいか、という条件で見極めます。後半の採用条件と見送り条件を自社の運用体制に当てはめて判断してください。

ArgoCDの仕組み：GitOpsとプル型同期でクラスターを保つ基本構造

ArgoCDを設計に落とすには、GitOpsという運用モデルと、ArgoCDがクラスター側から動く「プル型」であることを最初に押さえます。デプロイ先であるコンテナオーケストレーション（Kubernetes）の役割を前提に、Gitとクラスターの関係を捉えると構造が見通せます。

GitOpsという運用モデルとArgoCDが担う継続的な反映役割

GitOpsは、インフラやアプリの望ましい状態をすべてGitに宣言的マニフェストとして記述し、そのGitを唯一の情報源とする運用スタイルです。変更はkubectlの直接操作ではなくGitへのコミットとして残し、そこから自動でクラスターへ反映させるのが基本になります。これにより「今クラスターに何が入っているか」がGitの履歴とひも付き、変更の監査・レビュー・巻き戻しがコード管理の作法で回せるようになります。原則の定義はCNCFのワーキンググループが公開するOpenGitOpsの4原則にまとまっており、宣言的・版管理・自動反映・継続的な差分の埋め合わせ、の4点が判断の軸です。ArgoCDはこのうち反映と差分埋めを担い、Gitの宣言状態とクラスターの実状態を突き合わせて同期します。

GitOpsの4原則の中身や、CIからkubectl applyするPush型との違い、リポジトリ分割の設計はGitOpsとは：4原則とPush型との違いで整理しています。

プル型（Pull）同期と従来のプッシュ型デプロイの構造的な違い

従来のCIツールからのデプロイは、パイプラインがクラスターの認証情報を握って外からkubectl applyを打つプッシュ型でした。ArgoCDはこれを反転させ、クラスター内で動くArgoCD自身がGitを定期的にポーリングして差分を取り込むプル型を採ります。プル型では、クラスターの強い認証情報を外部のCIへ渡さずに済むため権限の露出が減り、クラスターから外向きにGitを読むだけで反映が完結する仕組みです。公式ドキュメントも自動同期の利点として「CI/CDパイプラインがArgoCDのAPIサーバーへ直接アクセスする必要がなくなる」点を挙げています。CIとCDの責務が切り離され、CI基盤が停止していてもクラスターはGitの宣言状態を保ち続けられる点が実務上の違いです。

Application・同期（Sync）・自己修復（Self-heal）というコア概念

ArgoCDの操作単位はApplicationというカスタムリソースで、「どのGitリポジトリのどのパスを、どのクラスターのどの名前空間へ反映するか」を1つのApplicationとして定義します。ArgoCDはApplicationごとにGitの宣言状態とクラスターの実状態を比較し、ずれていればSync（同期）で宣言状態へ寄せる仕組みです。人がクラスターを手で書き換えて宣言からずれた状態はドリフトと呼ばれ、ArgoCDのUI上でOutOfSyncとして可視化されます。Self-heal（自己修復）を有効にすると、こうした手動変更を検知して自動でGitの状態へ巻き戻すため、クラスターが宣言から乖離し続けるのを防げます。

ArgoCDをクラスターへインストールしてUIへログインする手順

ここからは実際に動かす手順です。前提はkubectlが入っており、kubeconfigで対象クラスターへ接続でき、CoreDNSが有効になっていることです。手順は公式のGetting Startedに沿っています。

kubectl applyでargocd名前空間へ本体を入れる作業手順

最初にargocd名前空間を作り、公式マニフェストを適用します。--server-sideと--force-conflictsを付けるのが要点で、理由は後述のよくある質問に整理しました。本番ではstableブランチではなく版を固定した参照に切り替えます。

kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl -n argocd get pods -w

適用するとargocd名前空間にAPIサーバー・リポジトリサーバー・アプリケーションコントローラー・Redis・ApplicationSetコントローラーが立ち上がります。既定インストールは自己署名証明書なので、CLIから触るときは証明書を信頼させるか--insecureを指定します。UI・SSO・マルチクラスターを使わないなら、コアコンポーネントだけの軽量構成も選択可能です。OpenShiftではこのマニフェストではなくOperator経由で入れるのが標準で、手順と既定インスタンスの権限はOpenShift GitOpsとは：Operatorのインストール手順とupstream Argo CDとの違い【1.21系】で解説しています。

admin初期パスワードを取り出しCLIでログインするまでの手順

初期のadminパスワードは自動生成され、argocd-initial-admin-secretというSecretのpasswordフィールドに平文で入っています。ポートフォワードでAPIサーバーへ通し、CLIでログインするまでが、一連の実行手順です。運用ではargocd-serverサービスをLoadBalancerへ変えるか、Ingressで公開経路を決めます。

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d
kubectl port-forward svc/argocd-server -n argocd 8080:443
argocd login localhost:8080 --username admin --insecure

ログイン後はWeb UIとCLIの双方から同じApplicationを操作できます。CLIだけで済ませるならargocd login --coreでkubeconfig経由の接続へ切り替えられ、ポートフォワードとパスワード取得を省けます。初期パスワードは確認後に変更し、Secretそのものも消す運用が安全です。

Applicationマニフェストを書いて最初の同期を走らせる

Applicationはカスタムリソースなので、YAMLで宣言してargocd名前空間へ適用します。sourceにGitのリポジトリとパスとリビジョン、destinationに反映先を書く形で、以下は公式サンプルを対象にした最小構成です。

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
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

適用した直後の状態はOutOfSyncで、argocd app sync guestbookを打つと宣言状態がクラスターへ反映されます。argocd app get guestbookで同期状態とヘルス状態を確認し、リソースツリーのどこで詰まっているかを切り分けます。ここまで通れば、以降はGitへのコミットが反映のトリガーです。pathの代わりにHelm chartを同期する場合や、Argo CD自体をHelm chartで入れる場合はArgoCDでHelm chartを使う方法で設定例を解説しています。

Syncポリシー・ApplicationSetを宣言で設定する実装の作業手順

単一アプリの同期だけならApplication1つで足りますが、実運用では複数チーム・複数環境・複数クラスターへ広がります。ArgoCDはそこを束ねる機能を備えており、規模に応じて使い分けます。

automated・prune・selfHealをYAMLで書き分ける設定例

同期をいつ走らせるかはSyncポリシーで決める設計です。Manualは差分が出てもUIやCLIから人が承認して初めて反映する方式で、本番のように反映タイミングを握りたい環境に向きます。Automaticはコミットを検知して自動反映する方式で、ここにprune（Gitから消したリソースをクラスターからも削除）とselfHeal（手動変更の自動巻き戻し）を組み合わせると、Gitが常にクラスターの正となる仕組みです。公式のAutomated Sync Policyによると、pruneは安全弁として既定で無効であり、自動削除を許すには明示的に有効化する必要があります。

spec:
  syncPolicy:
    automated:
      enabled: true
      prune: true
      selfHeal: true

開発環境はAutomatic＋selfHealで手離れさせ、本番はManualで承認を挟む環境別のポリシー設計が定石になります。enabledをfalseにすると、prune・selfHeal・allowEmptyを書いたまま自動同期だけを止められ、切り戻しのスイッチに使えます。ただしApplicationSetが生成したApplicationでは、生成物側のautomatedを直接書き換えても効かない点に注意してください。

同期失敗時のretryとbackoffを数値で決める設定の手順

同期は必ず成功するとは限らないので、失敗時の再試行を数値で決めておきます。retryに回数と指数バックオフを書くと、基準待ち時間から倍率をかけて上限まで伸ばす挙動を指定する設定です。limitに-1を指定すると無制限に再試行するため、本番では上限を必ず入れます。

spec:
  syncPolicy:
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

この例では初回は5秒後、以降は倍率2で待ち時間を伸ばし、上限3分で打ち切る設定です。イメージのプル失敗や依存リソースの作成順といった一時的な失敗はここで吸収でき、恒久的な失敗はUIのOutOfSync表示から追えます。再試行を増やすほど障害の検知は遅れるので、監視のアラート設計と合わせて数値を決めてください。

App of AppsとApplicationSetで多数のアプリを束ねる作業

アプリが増えるとApplicationを1つずつ手で作るのが重くなります。App of Appsパターンは、子Applicationを束ねる親Applicationを1つ置き、親を同期すれば配下のアプリ群がまとめて展開される構成です。ApplicationSetは、クラスター一覧やGitのディレクトリ構造をもとに複数のApplicationを自動生成する仕組みで、generatorにList・Cluster・Git・Matrixなどが用意されています。ApplicationSetコントローラーはArgo CD v2.3以降で本体に同梱されています。

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
  namespace: argocd
spec:
  goTemplate: true
  generators:
  - clusters: {}
  template:
    metadata:
      name: 'guestbook-{{.name}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/infra-team/cluster-deployments.git
        targetRevision: HEAD
        path: guestbook
      destination:
        server: '{{.server}}'
        namespace: guestbook

この定義はArgoCDに登録済みのクラスターを列挙し、クラスターごとにApplicationを1本ずつ生成します。「同じアプリを10クラスターへ」といった横展開をテンプレート化でき、規模が大きいほど効き方が変わります。開発チームへ開放するときは、反映先が広がる性質を踏まえて権限設計を先に固めてください。ジェネレーター別の書き方と削除・段階同期の設定はArgoCD ApplicationSetの使い方で解説しています。

Web UI・CLIとRBAC・SSOによるチーム単位の運用統制

ArgoCDはアプリの依存関係や同期状態をツリーで見せるWeb UIと、パイプラインへ組み込みやすいCLI（argocdコマンド）の両方を持ちます。どのアプリがOutOfSyncかがひと目で分かり、障害時の切り分けを速められます。統制面では、SSO連携（OIDCなど）でシングルサインオンを効かせ、RBACの設定でチームごとに触れるプロジェクトや操作を絞ることが可能です。宣言状態そのものはIaC（Infrastructure as Code）の考え方と地続きで、インフラもアプリもGit管理へ寄せると運用の一貫性が高まります。インフラ側をKubernetesの制御ループで払い出すなら、Crossplaneによるクラウドインフラの管理と組み合わせ、アプリのCDとインフラのプロビジョニングを分業させる構成も選べます。

ArgoCDを採用すべき条件とCI/CD・Fluxとの使い分け

ここでは判断を言い切ります。ArgoCDはGitOpsの反映を強力に自動化する一方、Kubernetesを常時運用する前提とGit中心の運用規律を要求します。自社のどこにArgoCDを差し込むかを、条件付きで見極めてください。

ArgoCDの採用が効くワークロードの条件と導入設計を始める起点

採用が効くのは、Kubernetesクラスターを継続運用しており、デプロイの監査性・再現性・巻き戻しやすさを底上げしたい、複数環境や複数クラスターへ同じ構成を横展開したい、手動オペレーションによる構成のずれを止めたい、という条件が重なるときです。こうしたKubernetes基盤とGitOps運用を自社へ取り入れるなら、AWS・Google Cloudを含むクラウドインフラ構築の相談窓口で、クラスター設計やSyncポリシー方針、権限統制の妥当性を相談する進め方があります。ArgoCDを動かす基盤としては、マネージドKubernetesのAmazon EKSのようにコントロールプレーンを委ねられるサービスから入ると、立ち上げの負荷を抑えられます。

CI/CDパイプラインとの役割分担（ArgoCDはCIではない）

誤解しやすいのは、ArgoCDがCIまで担うと考えてしまう点です。ArgoCDが引き受けるのはあくまでCD（クラスターへの反映）で、ソースのテストやコンテナイメージのビルドといったCIフェーズは別途GitHub Actionsや、Kubernetes上でパイプラインをCRDとして定義するTektonなどのCIツールが担います。全体像はCI/CDの仕組みと導入判断を押さえたうえで、CIがイメージをビルドしてマニフェスト用のGitを更新し、その先をArgoCDが同期する分業に落とすと役割が濁りません。この分離により、CI基盤の障害がクラスターの状態維持に波及しなくなります。あわせて押さえたいのは、ArgoCDが反映するのはマニフェストの状態であって、カナリアのように重みを段階的に上げながらメトリクスで昇格を判断する制御は持たない点です。そこを自動化するなら、Rolloutリソースで手順を宣言するArgo Rolloutsのカナリア・ブルーグリーン設定と自動ロールバックの実装を重ねる構成になります。なお、ビルドやデータ処理のように終わりのあるジョブをKubernetes上でDAGとして順に流す役目は、同じArgoプロジェクトのArgo Workflows（DAG・WorkflowTemplate・CronWorkflowの実装）が担います。

Flux CDと比べたときの選び分けとArgoCDを見送るべき場面

GitOpsツールの代表格にはArgoCDとFlux CDがあり、どちらもCNCFのGitOps系プロジェクトです。ArgoCDは視認性の高いWeb UIと、Application中心のマルチテナント運用に強みがあり、開発チームが同期状態を目で追いたい現場に向きます。Fluxはコントローラー分割の軽量な構成でGit中心の自動化に寄っており、UIより宣言と自動化を優先する現場に向く設計です。一方で見送るべきなのは、そもそもKubernetesを使っていない、あるいはアプリが1本で環境も1つしかなく、GitOpsの規律とツール運用のコストに見合わないケースです。少数のアプリを手動デプロイで回せているうちは、ArgoCDの導入がかえって運用の重さを増やします。反映後の状態を見張るKubernetesの監視・モニタリングとセットで体制を組めるかも、採用可否の分かれ目です。GKE・Cloud Runへのマネージドな継続的デリバリーを選ぶなら、Google CloudのCloud Deployが有力な選択肢です。

ArgoCD v3.5系へアップグレードする前に確認する非互換点

版を上げるときは、まず公式のアップグレード手引きで飛ばす版を含めた注意事項を順に読みます。ArgoCDはマイナー版ごとに非互換の告知がまとまっているため、v3.3系からv3.5系へ2段飛ばしで上げるならv3.4系の注意事項も対象です。パッチ版は複数系列へ同日に出る運用で、2026年8月27日にはv3.5.2とv3.4.8が同時に公開されました。実務では検証クラスターで先に上げ、Applicationの同期とヘルス表示が崩れないかを見てから本番へ回します。install.yamlの参照をstableから版固定へ切り替えると、意図しないタイミングで版が動くのを防げます。修正版と脆弱性の一覧はArgo CDの脆弱性一覧と対処で、系列ごとに照合できます。

よくある質問

ArgoCDの導入検討で実装者から多く挙がる質問を、一次情報に基づいて簡潔に整理します。

ArgoCDとFlux CDはどちらを選ぶべきですか？

どちらもCNCFのGitOps継続的デリバリーツールで、Gitを情報源にクラスターを同期する目的は同じです。ArgoCDは同期状態を可視化するWeb UIとApplication中心のマルチテナント運用が強みで、チームで同期状態を目視したい現場に向きます。Fluxはコントローラー分割の軽量構成でGit中心の自動化に寄る設計です。UIとマルチテナント統制を重視するならArgoCD、軽量な自動化を重視するならFluxが分岐の起点になります。Fluxの構成（GitOps Toolkit）や導入手順はFlux CDとはの解説記事を参照してください。

ArgoCDのプル型はプッシュ型のデプロイと何が違いますか？

プッシュ型はCIパイプラインがクラスターの認証情報を持って外から反映するのに対し、プル型はクラスター内のArgoCDがGitを読みに行って自ら反映します。プル型ではクラスターの強い認証情報を外部CIへ渡さずに済み、権限の露出を抑えられるのが利点です。またCIとCDが分離されるため、CI基盤が停止してもクラスターはGitの宣言状態を保ち続けられます。

ArgoCDのSelf-heal（自己修復）とは何ですか？

クラスターを人が手で書き換えてGitの宣言状態からずれた（ドリフトした）ときに、その変更を検知して自動でGitの状態へ巻き戻す機能です。設定はspec.syncPolicy.automated.selfHealをtrueにするか、argocd app setに--self-healを付けて有効化します。Automatic Syncと合わせて使うとGitが常にクラスターの正となり、手動オペレーションによる構成の乖離が積み上がるのを防ぐ仕組みです。本番など反映タイミングを握りたい環境では、あえて無効にして手動承認を挟む設計もとれます。

ApplicationSetとApp of Appsはどう使い分けますか？

App of Appsは親Applicationで子Applicationを束ね、親を同期すれば配下がまとめて展開される構成で、少数のアプリ群を階層でまとめたいときに向きます。ApplicationSetはクラスター一覧やディレクトリ構造から複数のApplicationを自動生成する仕組みで、同じ構成を多数のクラスターや環境へテンプレート展開したいときに向く方式です。横展開の規模が大きいほど効き方が際立ちます。

ArgoCDのインストールでserver-side applyを指定するのはなぜですか？

ApplicationSetをはじめ一部のCRDが、クライアント側適用が使うアノテーションの262KB上限を超えるためです。--server-sideを付けると直前の適用内容をアノテーションへ書かなくなるので、この上限に当たりません。--force-conflictsは他のツールが管理していたフィールドの所有権を引き取る指定で、新規導入とアップグレードの双方で通ります。ただしマニフェストで定義済みのフィールドへ加えた独自の変更は上書きされる点に注意してください。

ArgoCDはCI/CDのどこを担いますか？

ArgoCDが担うのはCD（クラスターへの反映）で、CI（テストやコンテナイメージのビルド）は別のCIツールが担当します。一般的な分業は、CIがイメージをビルドしてマニフェスト用のGitを更新し、その差分をArgoCDが同期する形です。ArgoCD単体ではビルドを行わないため、CIツールと組み合わせて初めてCI/CD全体が完成します。

関連記事

• CI/CDとは？仕組み・パイプライン・導入すべき企業の判断基準：CDフェーズを含む上位概念
• コンテナオーケストレーションとは？Kubernetesの役割と自社への要否：デプロイ先の前提知識
• Flux CDとは？GitOps Toolkitの仕組みとArgo CDとの違い：同じGitOps系ツールの比較対象
• Amazon EKSとは？仕組み・ノード提供形態と料金モデル：ArgoCDを動かす基盤の実装先
• IaCとは？Infrastructure as Codeの仕組み・メリットと導入判断：GitOpsと地続きの考え方
• Kubernetes監視・モニタリング：メトリクス/ログ/ダッシュボード設計：同期した後の運用監視
• ArgoCD MCPの使い方：mcp-for-argocdでAIエージェントにSync・ログ調査を任せる設定と権限設計【v0.9.0】：AIエージェントからArgo CDを操作する構成と権限設計