🔄 ArgoCD Replace機能完全ガイド: パッチが効かない時の必殺技

6月 17, 2026

—

KubernetesとArgoCDを運用していると、時々「このリソースは更新されず、エラーばかり出るな？」という状況に遭遇します。この時、私たちを救ってくれる魔法のようなオプションが、まさにReplace機能です。

今日は、ArgoCDのReplace機能とは何か、なぜ必要なのか、そして実際の運用環境でどのように適用するのかを深く掘り下げていきます！ 🚀

こんにちは！Kubernetesインフラを運用していると、kubectl applyでは解決できないリソースがしばしば現れます。通常、ArgoCDは既存のリソースを維持しつつ変更点のみを反映するPatch方式を使用しますが、特定の状況ではリソースを完全に新しいものに置き換える必要がある場合があります。

この時に使用するのが、まさにReplaceオプションです。これから、この機能のすべてをお伝えします！

1. Replaceとは何ですか？ 🤔

基本的に、ArgoCDはリソースを同期(Sync)する際、kubectl applyと類似した方式を使用します。つまり、既存のリソースに変更された部分だけをスッと挿入するStrategic Merge Patch方式を好みます。

しかし、Replace機能を有効にすると、ArgoCDは次のように動作します。

既存リソースの設定と新しい設定を比較します。
単純なパッチが不可能なリソース（Immutable fieldの変更など）の場合、既存リソースを丸ごと交換(Replace)するか、削除後に再生成します。

💡 例えるなら？

– Patch: 古いタイヤだけを新しいタイヤに交換すること。

– Replace: 車をまるごと新しいモデルに買い替えること。

2. なぜReplaceが必要なのですか？ ⚠️

すべてをパッチで解決できれば良いのですが、Kubernetesには

「一度設定すると変更できないフィールド（Immutable Fields）」

が存在します。

Service Selector: サービスが参照するPodのラベルは、実行中に変更できない場合が多いです。
Jobリソース: 既に実行中のJobのスペックを変更するには、必ず削除後に再生成する必要があります。
リソース容量超過: 時々、last-applied-configurationアノテーションのサイズが大きくなりすぎて、通常のapplyが失敗することがあります。（Kubernetesリソース容量制限の問題）

このような状況で、Replace=trueオプションは、手動でリソースを削除して再適用する手間を自動化してくれます。

3. 実践コード: Replaceの適用方法 💻

ArgoCDでReplace機能を適用する方法は、大きく分けて2つあります。

① アプリケーション全体に適用する (Sync Policy)

特定のアプリケーションに属するすべてのリソースが同期される際に、Replace方式を試行するように設定できます。

YAML

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/my-repo/manifests.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: my-namespace
  syncPolicy:
    syncOptions:
      # アプリ内のすべてのリソースに対してReplaceオプションを有効にします。
      - Replace=true

② 特定のリソースにのみ適用する (Annotation)

アプリケーション全体ではなく、問題となる特定のYAMLファイルにのみ個別に設定することも可能です。この方法はより安全で推奨されます。

YAML

apiVersion: v1
kind: Service
metadata:
  name: my-service
  annotations:
    # この特定のサービスリソースのみを同期する際にReplace方式を使用するよう指定します。
    argocd.argoproj.io/sync-options: Replace=true
spec:
  selector:
    app: my-new-app # もしこのフィールドが変更不可能でエラーになる場合、Replaceが解決してくれます！
  ports:
    - protocol: TCP
      port: 80
      targetPort: 9376

4. Replace vs Server-Side Apply ⚖️

最近のArgoCDでは、Server-Side Applyオプションもよく使われます。両者の違いを知ることが重要です。


区分	Replace	Server-Side Apply

—	—	—
動作方式	既存リソースを上書きまたは再生成	サーバー(K8s)が直接フィールド所有権を管理
主な目的	不変(Immutable)フィールドの変更問題の解決	大規模マニフェストの管理および衝突防止
危険度	中 (削除後に再生成する際にダウンタイム発生の可能性あり)	低 (最新のK8s標準方式)

—

5. 注意事項: 運用環境でのチェックリスト 🚨

Replace機能は強力ですが、無分別に使用すると危険を伴う可能性があります。

ダウンタイム発生: リソースを削除して再生成する過程で、ごく短い間サービスが中断される可能性があります。特にServiceやDeployment全体をReplaceする際には注意してください。
データ損失: PersistentVolumeClaim(PVC)のようにデータを保持するリソースに誤って使用すると、大切なデータが失われる可能性があります。（データ関連リソースには絶対に注意！）
最終手段: 可能な限り構造的な問題を先に解決し、本当にImmutableフィールドの変更が避けられない場合にのみ使用してください。

6. 要約 🏁

Replaceは、通常のパッチ（更新）が失敗した際に、リソースを強制的に置き換える機能です。
SyncOption=Replace=trueを通じて設定可能です。
Immutableフィールドの変更やマニフェストサイズの問題を解決するのに優れています。
しかし、ダウンタイムとデータ損失の可能性を常に念頭に置き、慎重に使用する必要があります。

🔄 ArgoCD Replace機能 完全ガイド: パッチが効かない時の必殺技