Claude CodeでArgoCD Applicationマニフェストを書く手順
ArgoCDのApplicationカスタムリソースをClaude Codeで書く手順を、必須フィールドとよくあるミスとともに解説します。
Claude CodeでArgoCD Applicationを書くとは
ArgoCDのApplicationは、GitOpsでKubernetesにデプロイする対象を宣言的に定義するカスタムリソースです。apiVersion: argoproj.io/v1alpha1 と kind: Application を持つYAMLファイル1枚で、どのGitリポジトリのどのパスを、どのクラスタのどの名前空間へ同期するかを表します。
Claude CodeはこのYAMLファイルをリポジトリ内の他のマニフェストと同じ手順で編集できます。フィールド名を1つずつ手で調べる代わりに、リポジトリ構成とデプロイ先の情報をプロンプトで渡し、必須フィールドが揃ったApplicationを生成させ、その場でkubectlやargocdコマンドで検証する、という流れです。
前提条件
ArgoCD公式のGetting Startedガイドは、Applicationを作成する前に次を要求しています。
kubectlコマンドラインツールがインストール済みであることkubeconfigファイルが存在すること(既定の場所は~/.kube/config)- クラスタにCoreDNSが有効であること(microk8sの場合は
microk8s enable dns)
さらに、ArgoCD自体がクラスタにインストール済みで、argocd名前空間にサービスが立っている必要があります。ArgoCDのインストール自体はこの記事の対象外ですが、公式手順ではCRD(ApplicationSetなど)がkubectl applyのクライアントサイド処理では262KBの注釈サイズ制限を超えるため、--server-side --force-conflictsフラグ付きでのインストールが案内されています。
kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts \
-f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yamlApplication manifestの必須フィールド
ArgoCD公式のApplication Specificationドキュメントは、Applicationの全フィールドを1枚のサンプルYAMLで示しています。そのうち、最小構成で必ず埋める必要があるのは次の5系統です。
| フィールド | 役割 | 例 |
|---|---|---|
metadata.name | 役割Applicationオブジェクトの名前 | 例guestbook |
spec.project | 役割所属するAppProject | 例default |
spec.source.repoURL | 役割マニフェストを置くGitリポジトリ | 例https://github.com/argoproj/argocd-example-apps.git |
spec.source.path | 役割リポジトリ内のマニフェストのパス | 例guestbook |
spec.destination.server | 役割デプロイ先クラスタのAPIサーバーURL | 例https://kubernetes.default.svc |
spec.projectはAppProjectという別のリソースへの参照で、未作成の環境ではArgoCDが最初から持つdefaultプロジェクトを指定すれば動きます。spec.destinationはクラスタをserver(APIサーバーURLで指定)またはname(登録済みクラスタ名で指定)のいずれかで示し、ArgoCDが動いているクラスタ自身へデプロイする場合はhttps://kubernetes.default.svcを使います。
spec.sourceは単一のGit/Helmリポジトリを指す構文ですが、複数のリポジトリからマニフェストを合成する場合は複数形のspec.sources(リスト)を使う書き方も用意されています。Claude Codeに書かせるときは、単一ソースか複数ソースかを最初のプロンプトで明示すると生成結果がぶれません。
Claude Codeに書かせる手順
- リポジトリ構成をプロンプトで伝える: 「
repoURLはこのリポジトリ自身、pathはk8s/guestbook、デプロイ先はhttps://kubernetes.default.svcのguestbook名前空間」のように、Application自身が持つべき値を具体的に渡します。抽象的に「ArgoCDのApplicationを作って」と頼むと、公式サンプルにあるHelm用のvalueFilesやHelmのparametersなど、そのリポジトリでは使わないフィールドまで生成されがちです。 - 生成されたYAMLを
metadata.nameとspec.destination.namespaceだけ先に確認する: この2つを取り違えると、想定した名前空間ではなく別の名前空間にリソースが作られます。 kubectl apply --dry-run=serverで検証する: クラスタに実際に適用する前に、マニフェストの構文とAPIサーバー側のバリデーションを通します。- Gitにコミットしてから
argocd app createまたはkubectl applyで登録する: GitOpsの原則上、Application自身もGitで管理された状態から適用するのが望ましい流れです。 argocd app getで初期状態を確認し、argocd app syncで反映する: 登録直後のApplicationはGitの内容がまだクラスタに反映されていないため、Sync StatusはOutOfSync、Health StatusはMissingと表示されます。ここでargocd app syncを実行すると、リポジトリのマニフェストを取得して適用する処理が走ります。
kubectl apply --dry-run=server -f guestbook-app.yaml
argocd app create guestbook \
--repo https://github.com/argoproj/argocd-example-apps.git \
--path guestbook \
--dest-server https://kubernetes.default.svc \
--dest-namespace default
argocd app get guestbook
argocd app sync guestbookCLIから直接argocd app createで作成する方法も用意されていますが、CLIで作成したApplicationの定義はGitに残らないため、YAMLとしてリポジトリにコミットしてから適用するほうがGitOpsの構成管理という目的に合います。
syncPolicyでデプロイの自動度を決める
spec.syncPolicyは、Gitの変更をどこまで自動でクラスタへ反映するかを決めるフィールドです。省略した場合、公式UIの手順が示すとおり同期方針はManualになり、Git側の変更があっても手動でSyncボタンやコマンドを実行するまでクラスタには反映されません。
自動化したい場合はautomatedブロックを追加します。
spec:
syncPolicy:
automated:
enabled: true
prune: true
selfHeal: true
allowEmpty: false
syncOptions:
- CreateNamespace=true各フィールドの既定値と意味は次のとおりです。
| フィールド | 既定値 | 意味 |
|---|---|---|
automated.prune | 既定値false | 意味Git側から削除されたリソースをクラスタ側でも削除するか |
automated.selfHeal | 既定値false | 意味Git変更がないままクラスタ側だけ手で変更された差分を検知して戻すか |
automated.allowEmpty | 既定値false | 意味自動同期で全リソースを削除する操作を許可するか |
syncOptionsのCreateNamespace=true | 既定値未指定 | 意味spec.destination.namespaceで指定した名前空間が無ければ自動作成するか |
CreateNamespace=trueを入れ忘れると、デプロイ先の名前空間がまだクラスタに存在しない場合に同期が失敗します。事前に名前空間を作る手間を省きたいなら、この1行をsyncOptionsに加えておくと安全です。
完成イメージ: 最小構成のApplication YAML
ここまでのフィールドを1つのファイルにまとめると、次のような形になります。Claude Codeに書かせた結果がこの構造に近いかを、まず目視で確認します。
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
finalizers:
- resources-finalizer.argocd.argoproj.io
labels:
team: platform
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:
enabled: true
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=truemetadata.labelsはApplicationオブジェクトに任意のラベルを付与するフィールドです。spec.infoフィールドを使うと、Application詳細画面に任意のリンクやメモを追加表示することもできます。
spec.revisionHistoryLimitは、ロールバック用に保持する過去リビジョンの数を指定するフィールドです。既定値は10で、公式ドキュメントもこの値を増やすことは推奨していません。
CLAUDE.mdにクラスタ構成を書いておく
プロンプトで毎回クラスタURLや名前空間を伝える代わりに、リポジトリのCLAUDE.mdにクラスタ構成を書いておくと、Claude Codeが生成するApplicationのフィールドがぶれなくなります。
## ArgoCD Application
- デプロイ先クラスタのAPIサーバーURL: https://kubernetes.default.svc
- 名前空間の命名規則: `<チーム名>-<環境名>`(例: platform-prod)
- syncOptionsには CreateNamespace=true を必ず含めるこう書いておけば、「guestbookアプリをplatformチームのproduction環境に出すApplicationを作って」のように短く指示するだけで、spec.destination.serverや名前空間の命名、CreateNamespace=trueの付与を毎回明示しなくても、リポジトリ内の他のApplicationと同じ形式でCLAUDE.md側の規則に沿って生成されます。
外部クラスタにデプロイする場合
Application自身はArgoCDが動いているクラスタに置きますが、spec.destinationで指す先は別のクラスタでも構いません。ArgoCDが動いているクラスタ以外にデプロイする場合は、先にそのクラスタの認証情報をArgoCDへ登録しておく必要があります。
kubectl config get-contexts -o name
argocd cluster add <コンテキスト名>この登録によって、対象クラスタのkube-system名前空間にargocd-managerという管理用のServiceAccountが作られ、ArgoCDはこのアカウントのトークンを使ってデプロイと監視を行います。同一クラスタ内にデプロイする場合はこの手順は不要で、spec.destination.serverにhttps://kubernetes.default.svcを指定するだけで済みます。
Helm・Kustomizeのマニフェストを使う場合
spec.source.pathが指すディレクトリがHelmチャートやKustomizeのoverlayの場合は、spec.source.helmやspec.source.kustomizeにレンダリング方法を指定します。Helmチャートの値を上書きしたい場合は、spec.source.helm.valuesObjectにYAMLとして直接値を書くか、spec.source.helm.valueFilesでリポジトリ内の値ファイルを指定します。Claude Codeにプロンプトを渡すときは、「対象パスはHelmチャートで、values-prod.yamlを上書きに使う」のように、どちらの方式で値を渡すかを明示すると、生成されるフィールドが安定します。
差分を無視したいとき
HPA(Horizontal Pod Autoscaler)がDeploymentのreplicasを書き換えるケースのように、クラスタ側の変更を意図的に「ズレ」として無視したいフィールドがあります。spec.ignoreDifferencesに対象のグループ・kindとJSONポインタを指定すると、その差分はOutOfSync判定から除外されます。
spec:
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers:
- /spec/replicasよくあるつまずき
finalizersを付けずにApplicationを削除し、リソースが残る:metadata.finalizersにresources-finalizer.argocd.argoproj.ioを書いていないと、Applicationオブジェクト自体をkubectl deleteしても、それが管理していたDeploymentやServiceはクラスタに残り続けます。カスケード削除させたいなら明示的にこのfinalizerを追加します。spec.destination.namespaceとmetadata.namespaceを混同する:metadata.namespaceはArgoCD自身のインストール先(通常argocd)を指し、spec.destination.namespaceはデプロイ対象のリソースが実際に置かれる名前空間を指します。この2つは別物です。- 262KBの注釈サイズ制限でCRDの適用が失敗する: ArgoCD自体のインストール時に発生する制限で、
ApplicationSetなどの一部CRDはクライアントサイドのkubectl applyが使うlast-applied-configuration注釈のサイズ上限を超えます。--server-sideフラグを使えばこの注釈を保存しないため回避できます。 syncPolicyを省略して自動反映されないと思い込む:syncPolicyを書かなければ同期方針はManualになるため、Gitにpushしただけではクラスタに反映されません。自動反映が必要ならautomatedブロックを明示します。
クラスタ操作まで自動化したい場合
この記事で扱ったのは、GitリポジトリにApplicationのYAMLをコミットしてargocdコマンドで適用する、GitOpsの標準的な流れです。Application自体の作成や同期実行までClaude Codeのチャットから直接指示したい場合はArgoCD MCPサーバーでGitOpsデプロイをClaudeに任せる、デプロイ先のKubernetesクラスタ自体を操作したい場合はKubernetes MCPサーバーでClaudeからクラスタを操作するが参考になります。書き上げたマニフェストをコミットしてPRにする手順はClaude CodeでPRを作成する手順にまとめています。
まとめ
ArgoCDのApplicationマニフェストは、metadata.name・spec.project・spec.source・spec.destinationの4系統を埋めれば最小構成として動きます。Claude Codeに書かせるときは、リポジトリのパスとデプロイ先クラスタ・名前空間を具体的にプロンプトで渡し、生成後はkubectl apply --dry-run=serverで検証してからGitにコミットする流れにすると、想定と違う名前空間への適用やfinalizers忘れによるリソースの取り残しを避けられます。自動同期が必要ならsyncPolicy.automatedを追加し、CreateNamespace=trueも合わせて検討します。