Argo CD入門｜Applicationの書き方と同期の仕組み

Argo CD は、Git に置いた Kubernetes の YAML（あるべき状態）と、クラスタで動いている状態を比べ続け、違いがあれば Git の状態にそろえる（同期する）ツールです。 この「Git を正とする」運用を GitOps と呼びます。何をどこに同期するかは、Application というカスタムリソースに書きます。

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web-prod
  namespace: argocd            # Application は Argo CD を入れた Namespace に置く
spec:
  project: default             # 必須
  source:                      # 何を（Git のどこを）
    repoURL: https://github.com/example/k8s-manifests.git
    targetRevision: main
    path: apps/web/overlays/prod
  destination:                 # どこへ（クラスタと Namespace）
    server: https://kubernetes.default.svc
    namespace: web-prod
  syncPolicy:                  # いつ・どう同期するか
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

確認環境：Argo CD v3.5.5。argocd CLI（GitHub リリースの linux-amd64 バイナリ）で argocd admin app generate-spec の出力とヘルプを確かめ、この記事の Application・ApplicationSet の YAML は v3.5.5 のソースにある CRD のスキーマ（manifests/crds）で検証しました。同期の動きは v3.5.5 のドキュメント（docs/user-guide・docs/operator-manual）と公式サイトで確かめました（確認日 2026年10月13日）。

Argo CD の同期の仕組み

 Git リポジトリ（あるべき状態）
        │  ① 取得して YAML を組み立てる（Kustomize・Helm・素の YAML）
        ▼
 Argo CD ── ② クラスタの状態と比べる（diff）──▶ Synced / OutOfSync
        │  ③ 同期（手動なら Sync ボタン・CLI、自動なら automated）
        ▼
 Kubernetes クラスタ（いまの状態）

自動同期は、Application が OutOfSync のときにだけ動きます。 ドキュメントには、次のことは自動同期では行わないとあります。

• 同じコミット（同じパラメーター）で一度成功したら、selfHeal が無い限り同期し直さない
• 同じコミットで失敗した同期を、そのまま再試行し続けない（retry の設定の範囲で再試行）
• 自動同期が有効な Application は、ロールバックできない

インストールと argocd CLI

ドキュメントの手順です。

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

# 初期パスワードと画面への接続
argocd admin initial-password -n argocd
kubectl port-forward svc/argocd-server -n argocd 8080:443
argocd login localhost:8080

CLI は GitHub のリリースから1つのバイナリで入ります。

curl -sSL -o argocd https://github.com/argoproj/argo-cd/releases/download/v3.5.5/argocd-linux-amd64
chmod +x argocd
./argocd version --client
# argocd: v3.5.5+a5038b0
#   BuildDate: 2026-10-12T10:37:42Z

ログイン前に argocd app list を実行すると、Argo CD server address unspecified で止まりました。argocd app 系のコマンドは、argocd login で接続先を決めてから使います。

Application の書き方（完成形）

Kustomize の overlay を本番に同期する Application です。この YAML は v3.5.5 の CRD のスキーマで検証を通りました。

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web-prod
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io   # Application を消したらリソースも消す
spec:
  project: default
  source:
    repoURL: https://github.com/example/k8s-manifests.git
    targetRevision: main                        # ブランチ・タグ・コミット SHA
    path: apps/web/overlays/prod                # kustomization.yaml があれば Kustomize として扱う
  destination:
    server: https://kubernetes.default.svc      # Argo CD と同じクラスタ
    namespace: web-prod
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - PruneLast=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m
  ignoreDifferences:                            # HPA が変える replicas は差分として見ない
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas
  revisionHistoryLimit: 10

CLI で YAML を作る：argocd admin app generate-spec

argocd admin app generate-spec を使うと、サーバーに接続せずに Application の YAML を出力できます。

argocd admin app generate-spec guestbook \
  --project default \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook --revision HEAD \
  --dest-server https://kubernetes.default.svc --dest-namespace guestbook \
  --sync-policy automated --auto-prune --self-heal \
  --sync-option CreateNamespace=true --sync-retry-limit 5

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
spec:
  destination:
    namespace: guestbook
    server: https://kubernetes.default.svc
  project: default
  source:
    path: guestbook
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    retry:
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m0s
      limit: 5
    syncOptions:
    - CreateNamespace=true

--sync-retry-limit 5 だけを指定して、backoff には 5s・2・3m0s が入りました。 ヘルプでは、これが --sync-retry-backoff-duration・--sync-retry-backoff-factor・--sync-retry-backoff-max-duration の既定値です。 --project を付けないと project: "" になりました。--set-finalizer を付けると、metadata.finalizers に resources-finalizer.argocd.argoproj.io が入りました。

Helm チャートを同期する Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: ingress-nginx
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://kubernetes.github.io/ingress-nginx   # Helm リポジトリ
    chart: ingress-nginx                                   # path ではなく chart
    targetRevision: 4.11.3                                 # チャートの版
    helm:
      releaseName: ingress-nginx
      valuesObject:                                        # values.yaml の中身を直接書く
        controller:
          replicaCount: 2
  destination:
    server: https://kubernetes.default.svc
    namespace: ingress-nginx
  syncPolicy:
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true

Argo CD は Helm チャートを helm template 相当で YAML にしてから適用します。 そのため helm list には出ません。Helm の書き方は、関連記事「Helm入門｜チャートの作り方とコマンド一覧」で扱っています。Kustomize の overlay の作り方は、関連記事「Kustomizeの使い方｜base・overlay・patchの書き方」で扱っています。

スキーマで弾かれる書き間違い

わざと間違えた Application を CRD のスキーマで検証すると、次の3つが見つかりました。

syncPolicy の一覧

prune: false のまま YAML をリポジトリから消しても、クラスタのリソースは残り、Application は OutOfSync になります。 画面では「消すべきリソース」として表示され、手動で同期するときに prune を選べます。

selfHeal の動き

selfHeal: true にすると、kubectl scale や kubectl edit でクラスタを直接変えても、Git の値に戻されます。HPA（オートスケーラー）が replicas を変える Deployment では、ignoreDifferences で /spec/replicas を外しておかないと、HPA と Argo CD が値を取り合います。 ignoreDifferences は既定では差分の表示にだけ効くので、同期でも外すには RespectIgnoreDifferences=true を付けます。

syncOptions の一覧

syncOptions は、Application 全体（spec.syncPolicy.syncOptions）と、リソースごとのアノテーション（argocd.argoproj.io/sync-options）の2か所で指定できます。 リソースのアノテーションが Application の指定より優先されます。複数はカンマ区切りで書きます。

リソースごとに指定する例です。

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
  annotations:
    argocd.argoproj.io/sync-options: Prune=false,Delete=false   # データは消さない

同期の順番：phase・sync wave・hook

Argo CD は、phase（PreSync → Sync → PostSync）→ wave の番号（小さい順）→ リソースの種類（Namespace が先など）の順で適用します。 wave はアノテーションで決め、指定しないと 0 です。wave の間には既定で 2 秒の待ちがあります（環境変数 ARGOCD_SYNC_WAVE_DELAY）。

# DB のマイグレーションを、アプリより先に Job で流す例
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: registry.example.com/web/migrate:1.4.0
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: web-settings
  annotations:
    argocd.argoproj.io/sync-wave: "-1"    # wave 0 の Deployment より先

選んだリソースだけを同期する（selective sync）ときは、hook は動きません。

ApplicationSet：Application をまとめて作る

ApplicationSet は、generator（パラメーターを作る部分）と template（Application のひな形）から、Application を自動で作ります。 環境ごと・クラスタごと・ディレクトリごとに Application を並べるときに使います。

List generator：dev と prod を1つの定義で

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: web
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]   # 無いキーを参照したらエラー
  generators:
    - list:
        elements:
          - env: dev
            branch: develop
          - env: prod
            branch: main
  template:
    metadata:
      name: 'web-{{.env}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/k8s-manifests.git
        targetRevision: '{{.branch}}'
        path: 'apps/web/overlays/{{.env}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: 'web-{{.env}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

これで web-dev（develop ブランチ → web-dev）と web-prod（main → web-prod）の2つの Application ができます。

Git generator：ディレクトリを足すだけで Application が増える

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: platform-addons
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
    - git:
        repoURL: https://github.com/example/k8s-manifests.git
        revision: main
        directories:
          - path: addons/*
          - path: addons/experimental
            exclude: true                    # このディレクトリは除く
  syncPolicy:
    applicationsSync: create-update          # ApplicationSet からは Application を消さない
    preserveResourcesOnDeletion: true        # ApplicationSet を消してもリソースは残す
  template:
    metadata:
      name: '{{.path.basename}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/k8s-manifests.git
        targetRevision: main
        path: '{{.path.path}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{.path.basename}}'

generator の一覧

applicationsSync の4つのポリシー

ドキュメントには、create-only・create-update でも、ApplicationSet 自体を削除したときの ownerReferences による Application の削除は防げないと注意があります。ApplicationSet の template に syncPolicy.automated を書いておくと、生成された Application 側で自動同期を止めても、ApplicationSet が書き戻します。

App of Apps：Application を Application で管理する

App of Apps は、「Application の YAML を置いたディレクトリ」を同期する親の Application を1つ作る方法です。 親を1つ登録すれば、子の Application が Git から作られます。

k8s-manifests/
├── argocd/
│   ├── root.yaml            # 親（最初に1回だけ kubectl apply）
│   └── apps/
│       ├── web-prod.yaml    # 子の Application
│       ├── ingress-nginx.yaml
│       └── cert-manager.yaml
└── apps/
    └── web/overlays/prod/   # 子が同期する実体

# argocd/root.yaml（親）
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/example/k8s-manifests.git
    targetRevision: main
    path: argocd/apps
    directory:
      recurse: true
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd          # 子の Application は argocd Namespace に作る
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

kubectl apply -n argocd -f argocd/root.yaml

ドキュメントでは、App of Apps は管理者向けの仕組みと注意しています。子の Application の project を書き換えれば、任意の AppProject に Application を作れるためです。親のリポジトリに push できる人を管理者に限り、project の変更はレビューで確かめるよう書かれています。

Application の削除と finalizer

App of Apps で親を消したときに子のリソースまで消すには、子の Application にも finalizer が必要です。 逆に、消えると困る本番の Application は、finalizer を付けるかどうかを決めてから作ります。

よく使う argocd CLI

argocd app の主なサブコマンドと、argocd app sync のフラグです（v3.5.5 のヘルプより）。

CI から同期を待つときは argocd app sync web-prod && argocd app wait web-prod --health --timeout 300 の形がよく使われます。GitHub Actions の書き方は、関連記事「CI/CDとは｜GitHub Actionsで最初のパイプラインを作るまで」で扱っています。

よくある質問

Q. 自動同期にしているのに、Git を変えてもすぐ反映されません。 A. Argo CD は既定で最大 3 分ごとに Git を見に行きます。すぐ反映したいときは、Git の Webhook を Argo CD に向けるか、argocd app get web-prod --refresh で取り直します。

Q. OutOfSync のまま直らないリソースがあります。 A. コントローラーやミューテーティング Webhook がクラスタ側で値を足している場合によく起きます。argocd app diff で差分の項目を確かめ、意図した差分なら ignoreDifferences で外します。

Q. Secret はどう管理しますか。 A. Git に平文で置かず、Sealed Secrets・External Secrets Operator などで暗号化した形や参照を置く方法がよく使われます。

Q. Kubernetes の基本から確認したいです。 A. Deployment・Service などの基本は、関連記事「Kubernetes入門｜主要リソースとYAMLの書き方、kubectl早見表」で扱っています。

まとめ

• Application は「Git のどこ」を「どのクラスタ・Namespace」へ同期するかの設定。project は必須
• 自動同期は syncPolicy.automated。prune・selfHeal はどちらも既定 false
• syncOptions は Application 全体とリソースのアノテーションの2か所。PVC には Prune=false,Delete=false などで守る
• 順番は phase → sync wave → 種類。マイグレーションは PreSync の Job
• 複数の Application は ApplicationSet（推奨）か App of Apps。削除の動きは finalizer で決まる

参考・出典

確認日はいずれも 2026年10月13日です。

• Argo CD ドキュメント「Getting Started」：https://argo-cd.readthedocs.io/en/stable/getting_started/
• Argo CD ドキュメント「Application Specification Reference」：https://argo-cd.readthedocs.io/en/stable/user-guide/application-specification/
• Argo CD ドキュメント「Automated Sync Policy」：https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/
• Argo CD ドキュメント「Sync Options」：https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/
• Argo CD ドキュメント「Sync Phases and Waves」：https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/
• Argo CD ドキュメント「Generators」（ApplicationSet）：https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators/
• Argo CD ドキュメント「Controlling if/when the ApplicationSet controller modifies Applications」：https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Controlling-Resource-Modification/
• Argo CD ドキュメント「Cluster Bootstrapping」（App of Apps）：https://argo-cd.readthedocs.io/en/stable/operator-manual/cluster-bootstrapping/
• Argo CD ドキュメント「App Deletion」：https://argo-cd.readthedocs.io/en/stable/user-guide/app_deletion/
• argoproj/argo-cd v3.5.5（manifests/crds・CLI）：https://github.com/argoproj/argo-cd/releases/tag/v3.5.5

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。