Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

【ITニュース解説】What changed in Argo CD 3.5 for ops teams upgrading from 3.x

2026年11月04日に「Dev.to」が公開したITニュース「What changed in Argo CD 3.5 for ops teams upgrading from 3.x」について初心者にもわかりやすく解説しています。

作成日: 更新日:

ITニュース概要

Argo CD 3.xから3.5へのアップグレードには計画的な手順が求められる。まず現在の状態をバックアップし、バージョン間の変更点を事前に確認する。ステージング環境でテスト実施後、本番適用。ロールバック手段も確保し、アップグレード後の状態を必ず検証する。

ITニュース解説

Argo CDは、GitOpsという考え方に基づいて、Kubernetesクラスター上のアプリケーションのデプロイや管理を自動化するための強力なツールである。多くの企業で採用されており、そのバージョンアップはシステムの安定稼働に直結するため、慎重に進める必要がある。今回のニュース記事では、Argo CDの既存バージョン3.xから最新の3.5へアップグレードする際の具体的な手順と注意点が解説されている。

まず、Argo CDのアップグレードは単にバージョン番号を上げるだけの手順ではないと理解することが重要だ。現在のシステムが3.2や3.3といったバージョンで稼働しており、数百ものアプリケーションを管理している場合、3.5へのアップグレードは、まるで精密機械を分解・再構築するようなものだ。ニュース記事では、Argo CD 3.5が2026年8月にリリースされ、その後もパッチリリースが続き、現在では3.5.6が最新であることが示されている。なぜ古いバージョンを使い続けるのは良くないかというと、ソフトウェアの公式サポートは通常、最も新しいマイナーバージョンにのみ提供されるため、アップグレードを先延ばしにすると、もし問題が発生したときに公式のサポートを受けられなくなるリスクが高まるからだ。だから、早めのアップグレードが推奨される。

アップグレードを始める前に、いくつかの重要な準備が必要となる。まず、Kubernetesクラスターに対する十分な権限があることを確認する。具体的には、Argo CDが稼働している名前空間での管理者権限と、Kubernetesクラスター全体で「カスタムリソース定義(CRD)」や「クラスターロール」といった設定を適用できる権限が必要になる。次に、Argo CDを操作するためのコマンドラインツール(argocd CLI)のバージョンを、アップグレード先のサーバーバージョンに合わせる必要がある。CLIのバージョンが古いと、新しいサーバーAPIに対して予期せぬ動作をすることがあるからだ。また、本番環境の構成を模倣した非本番環境のArgo CDインスタンスを用意することも不可欠だ。本番環境にある実際のアプリケーションや設定(argocd-cmやargocd-rbac-cmといった設定ファイル)を再現したテスト環境がなければ、アップグレードによる影響を正確に評価することはできない。Argo CDのインストール方法(例えば、Kubernetesの生マニフェストを直接適用しているのか、Kustomizeというツールを使っているのか、それともHelmチャートというパッケージ管理ツールを使っているのか)も明確にしておく必要がある。それぞれの方法でバージョンの指定方法が異なるため、自分の環境に合った手順を選ぶためだ。最後に、現在利用しているKubernetesクラスターのバージョンと、ターゲットとなるArgo CD 3.5の互換性を公式ドキュメントで確認しておく必要がある。もしKubernetesのバージョンが古すぎたり新しすぎたりすると、Argo CDが正常に動作しない可能性もある。さらに、古いingress-nginxコントローラーをArgo CDのフロントエンドとして使っている場合は注意が必要だ。これは2026年3月にサポートが終了しており、セキュリティ上の問題が修正されないため、Gateway APIなどの新しい技術への移行を別途計画すべきだ。この移行とArgo CDのアップグレードを同時に行うと、もし問題が発生した場合にどちらが原因か特定が難しくなるため、別々のタイミングで行うのが賢明である。

次に、現在のArgo CDの状態を記録しておく必要がある。これは、アップグレード後に何か問題が発生したときに、元の状態に戻したり、アップグレード前後の変化を比較したりするために重要だ。具体的には、まず現在稼働しているargocd CLIとサーバーのバージョンを記録する。その後、argocd admin exportコマンドを使って、Argo CDが管理しているすべてのアプリケーション、プロジェクト、設定、そしてシークレットなどの情報をYAMLファイルとしてエクスポートする。このエクスポートファイルには、リポジトリへの認証情報やクラスターの機密情報が含まれる可能性があるため、厳重に暗号化して安全な場所に保管することを忘れてはならない。また、argocd app listコマンドを使って、すべてのアプリケーションの名前、同期ステータス、ヘルスステータスを一覧で取得し、これを「ベースライン」として保存しておく。このベースラインがあれば、アップグレード後にどのアプリケーションの状態が変わったかを簡単に比較できる。エクスポートしたファイルには、既に「OutOfSync」(同期されていない)や「Degraded」(状態が低下している)なアプリケーションも含まれるが、これらはアップグレードによる問題ではないことを認識しておくことが重要だ。もしこのようなアプリケーションがあった場合、アップグレード後に新バージョンのせいにしないよう、事前に把握しておくべきだ。

現在の状態を把握したら、アップグレードノートを注意深く読み込む作業に移る。Argo CDの公式ドキュメントには、「オペレーターマニュアル」という運用者向けのマニュアルがあり、その中にアップグレードに関する詳細な情報が記載されている。重要なのは、現在のバージョンから3.5までの間にリリースされたすべてのマイナーバージョン(例えば、現在のバージョンが3.2なら、3.3へのアップグレードノート、そして3.4へのアップグレードノート、最後に3.5へのアップグレードノート)を順番に読むことだ。一つでも飛ばしてしまうと、デフォルト設定の変更など、気づかないうちに重要な変更点を見落とす可能性がある。これらのノートを読みながら、変更点を「設定ファイルの修正が必要な破壊的変更」「実行時の挙動が変わるデフォルト設定の変更」「将来的に削除される非推奨機能」の3つに分類し、自分の環境の設定ファイル(argocd-cm、argocd-cmd-params-cm、argocd-rbac-cmなど)と照らし合わせて確認する。特に注意すべきは、Argo CDがKubernetesのリソースをどのように追跡したり、Gitとの差分をどのように比較したりするかに関する設定だ。これらの設定が変わると、アップグレード後に数百ものアプリケーションがいきなり「OutOfSync」状態になる可能性があるため、もし関連する変更点があれば、非本番環境でargocd app diffコマンドを使って実際のアプリケーションで動作をテストすることが非常に重要だ。また、Argo CDのrepo-serverというコンポーネントにバンドルされているHelmやKustomizeといったツールのバージョンが変更されることもあり、これにより同じGitのコードでもレンダリングされるKubernetesマニフェストの内容が変わってしまう可能性もあるため、これらの依存関係も確認する必要がある。

次に、いよいよ非本番環境でのリハーサルを行う。この時、Argo CDのバージョン指定には「stable」のような変動するタグではなく、v3.5.6のような具体的なパッチバージョンを正確に指定することが非常に重要だ。Argo CDのカスタムリソース定義(CRD)は非常に大きいため、適切に適用するためには、Kubernetesの「サーバーサイド適用(Server-Side Apply)」という機能を使うことが推奨されている。これは、kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.5.6/manifests/install.yamlというコマンドで実行できる。この際、自分のArgo CDの構成(標準的なインストールか、高可用性(HA)構成か)に合わせて、適切なマニフェストファイル(manifests/install.yamlまたはmanifests/ha/install.yaml)を選ぶ必要がある。もしHA構成なのに標準インストールのマニフェストを適用してしまうと、HAを構成するコンポーネントが置き換わってしまう可能性があるため注意が必要だ。適用後、argocd-server、argocd-repo-server、argocd-application-controllerといった主要なArgo CDコンポーネントが正常にロールアウトされているかを確認する。もしKustomizeやHelmを使っている場合は、それぞれの設定ファイルでバージョンを更新し、実際に適用する前に差分(変更点)を確認することが強く推奨される。ここで--force-conflictsというオプションを使っているが、これはアップストリームのマニフェストが設定する全てのフィールドの所有権を強制的に取得するという意味だ。もし手動で変更していたり、別の方法で設定していたフィールドがある場合、それらの変更がリセットされてしまう可能性があるため、事前に差分をよく確認しておく必要がある。

非本番環境でのリハーサルが成功したら、本番環境への適用に進む。これは、システムの負荷が低い時間帯に行うべきだ。大規模なリリースが同期中など、システムが忙しい時間帯は避けるべきである。Argo CDのアプリケーションコントローラーが再起動すると、すべてのアプリケーションの状態を再調整するため、一時的にrepo-serverやKubernetesのAPIサーバーに大きな負荷がかかることが予想される。大規模な環境では、この負荷がアップグレードの本当のコストとなることもある。本番環境に適用する際は、万が一の事態に備えて、明確なロールバック計画を用意しておくことが不可欠だ。まず、前のバージョンのArgo CDマニフェストを再度適用することで、バージョンを戻すことができる。もしArgo CD自身の状態が破損してしまった場合は、ステップ1でエクスポートしておいたバックアップファイルを使って、argocd admin importコマンドで復元できる。しかし、Argo CDのカスタムリソース定義(CRD)のスキーマ変更は、常にきれいに元に戻せるとは限らないため、ステージング環境での徹底的なリハーサルこそが、実際のリスクを軽減する最も重要な手段であると理解しておくべきだ。インシデント発生中やシステム変更の凍結期間中、あるいはアップグレード後の初期調整を監視できる人がいない状況では、アップグレードを行うべきではない。また、一つのArgo CDインスタンスで複数のKubernetesクラスターを管理している場合は、まず影響の少ないサブのクラスターからアップグレードすることを検討すると良い。これにより、万が一の問題発生時の影響範囲を限定することができる。

アップグレードが完了したら、システムが正常に動作しているかを入念に検証し、テストする必要がある。まずは、argocd versionコマンドでサーバーが目的のバージョン(例: v3.5.6)を報告していることを確認する。次に、ステップ1で取得したベースラインと比較するために、現在のアプリケーションの同期ステータスとヘルスステータスを再度取得し、ベースラインファイルと差分を確認する。もし差分がなければ、すべてのアプリケーションがアップグレード前と同じ状態を保っていることを意味し、問題はない。もし差分があれば、それらが調査すべきアプリケーションとなる。それぞれのアプリケーションについてargocd app diff <name>コマンドを実行し、差分の原因が、マニフェストのレンダリング方法の変更、リソースの追跡方法の変更、あるいはGitリポジトリと実際のクラスター状態の間の本当の変更によるものなのかを特定する。さらに、使い捨てのアプリケーションを一つ用意し、それを同期させ、Gitリポジリトリでそのアプリケーションの設定値を変更し、Argo CDがその変更を検出し、Kubernetesクラスターに正常に適用できるかという一連のフローをテストする。これは、Argo CDがGitOpsツールとして本来の機能を果たせるかを最終確認するためだ。長期的な信頼性を得るためには、Argo CDが公開しているPrometheusという監視ツール用のメトリクスも監視することが有効だ。特に、argocd_app_infoというメトリクスを同期ステータスやヘルスステータスでグループ化し、アップグレード前の形に戻っているかを確認する。また、argocd_app_sync_totalというメトリクスで、予期しない失敗した同期やエラーになった同期が増加していないかを監視する。Podの再起動状況やrepo-serverのログも確認し、もし1時間以上再起動が繰り返されるようであれば、リソースの制限値を見直す必要があるかもしれない。

まとめると、Argo CD 3.xから3.5へのアップグレードは、主に「公式ドキュメントを読み込み、慎重に計画し、非本番環境で徹底的にリハーサルする」という工程が重要となる。具体的には、まずargocd admin exportコマンドで現在のArgo CDの状態をスナップショットとして保存する。次に、現在のバージョンから3.5までのすべてのマイナーバージョンのアップグレードノートを順番に、そして詳細に読み込む。そして、自分のインストール方法とトポロジー(標準かHAか)に合ったマニフェストを使って、v3.5.6などの特定のパッチバージョンを固定し、Kubernetesのサーバーサイド適用機能を使って非本番環境に適用し、動作を確認する。最後に、アップグレード前後のアプリケーションの状態を比較し、問題がないことを確認する。これらのプロセスを進める間は、Argo CDの公式ドキュメントを常に手元に開いておくことが推奨される。デフォルト設定や各種フラグはバージョン固有のものが多いため、この記事の内容も公式ドキュメントと照らし合わせて確認しながら進めるべきだ。

関連コンテンツ

関連IT用語