【ITニュース解説】controller-runtime: What Happens When You Do Partial Server-Side Apply?

Kubernetesのシステム開発、特にリソースの状態を自動的に維持・管理する「コントローラー」を作成する上で、Server-Side Apply（SSA）という機能の理解はシステムエンジニアにとって非常に重要である。SSAは、複数のシステムやユーザーが同じKubernetesリソースの設定を共同で管理する際に、意図しない変更の衝突を避け、それぞれの責任範囲を明確にしながら宣言的な設定を可能にするための仕組みだ。この機能の挙動を正しく把握することは、安定したシステムを構築し、予期せぬリソースの変更や削除を防ぐために不可欠である。

SSAの基本的な考え方は、ユーザーやコントローラーが望むリソースの最終的な状態を定義した「マニフェスト」という設定情報をKubernetesに提供し、Kubernetesがその宣言に基づいて実際のシステム状態を調整するというものである。SSAが単にマニフェストの内容をリソースに適用するだけでなく、「どの設定項目（フィールド）を誰が管理しているか」という情報をKubernetesの内部に記録する点が特徴である。この「誰が」にあたるのが「フィールドマネージャー」であり、フィールドマネージャーは特定のリソースの特定フィールドに対する管理責任、すなわち「所有権」を持つことになる。これにより、複数のフィールドマネージャーが同じリソースの異なる部分を同時に、かつ安全に管理できるよう設計されている。

しかし、このSSAを、マニフェストに全ての設定項目を含めず、一部のみを記述した「部分的なマニフェスト」で繰り返し適用する場合、その挙動には注意が必要である。特に、以前は特定のフィールドを管理していたフィールドマネージャーが、その後のマニフェスト適用時にそのフィールドを省略した場合に何が起こるかについて、誤解があると意図しないデータ削除やバグに繋がりかねない。

具体的な例として、カスタムリソース「Cat」を用いた実験を考える。まず、「cat-owner」という名前のフィールドマネージャーが、Catリソースのspec.breed（猫の品種）フィールドのみを定義したマニフェストを適用したとする。この操作により、Catリソースにはspec.breed: "Maine Coon"という情報が設定される。この時、Kubernetes内部のmanagedFieldsという部分には、「cat-owner」がspec.breedを管理しているという情報が記録される。このmanagedFieldsは、各フィールドマネージャーがどのフィールドの所有権を持っているかを追跡するための重要な記録である。

次に、同じ「cat-owner」が、今度はCatリソースのspec.color（猫の色）フィールドのみを定義したマニフェストを適用する。このマニフェストにはspec.breedは含まれていない。この2回目の適用後、Catリソースの状態を確認すると、spec.color: "Black"という情報は追加されている一方で、以前設定されていたspec.breedフィールドは完全に削除されてしまっていることがわかる。そして、managedFieldsの記録も、「cat-owner」が管理するフィールドがspec.breedからspec.colorへと更新されている。

この現象は、SSAの「宣言的な所有権管理」という根本的な設計思想に基づいている。Kubernetesの公式ドキュメントが示すように、「マニフェストからフィールドを削除してそのマニフェストを適用した場合、Server-Side Applyはそのフィールドが他のフィールドマネージャーによっても所有されているかどうかを確認する。もしそのフィールドが他のどのフィールドマネージャーにも所有されていない場合、そのフィールドはライブオブジェクトから削除されるか、デフォルト値があればそれにリセットされる」というルールが適用される。

先の実験では、最初の適用で「cat-owner」がspec.breedの唯一の所有者となった。2回目の適用で「cat-owner」がspec.breedをマニフェストに含めなかったことは、SSAにとって「cat-ownerはもうspec.breedを管理したくない」という明確な意思表示として解釈される。他にspec.breedを管理しているマネージャーが存在しなかったため、SSAはこのフィールドが不要になったと判断し、実際のCatリソースから削除したのである。これは、管理されなくなった古いデータがリソース内に残り続けることを防ぐための「クリーンアップ機能」として機能する。したがって、意図せずにフィールドが削除される事態を避けるためには、あるフィールドマネージャーが管理したい全てのフィールドを、適用するマニフェストに毎回確実に含める必要があるということを理解する必要がある。

では、複数のフィールドマネージャーが同時に存在する状況ではどうなるだろうか。先ほどの例でspec.colorのみが存在するCatリソースの状態から、「age-controller」という新しいフィールドマネージャーが、spec.age（猫の年齢）フィールドのみを定義したマニフェストを適用するシナリオを考える。この適用後、リソースの状態はspec.color: "Black"とspec.age: 3の両方を持つことになる。注目すべきは、先に「cat-owner」が管理していたspec.colorフィールドが、この新しいマネージャーの適用によっても全く影響を受けずに残っている点である。

この場合、managedFieldsには「age-controller」がspec.ageを管理しているという記録と、「cat-owner」がspec.colorを管理しているという記録の二つが明確に存在する。それぞれのフィールドマネージャーは、自分が管理するフィールドの所有権を独立して持ち、他のマネージャーが管理するフィールドには干渉しない。これにより、「age-controller」はspec.ageの所有権を主張し、その情報をCatリソースに追加したが、「cat-owner」が管理するspec.colorには影響を与えなかったのである。

これらの実験から、Server-Side Applyを効果的に利用するための二つの重要な原則が導き出される。一つは「マニフェストの完全性」の原則である。あるフィールドマネージャーが特定のKubernetesリソースのフィールドを管理する場合、そのマネージャーが管理したいと考える全てのフィールドを、適用するマニフェストに毎回含める必要がある。もし管理対象のフィールドをマニフェストから省略した場合、それは「そのフィールドの管理をやめる」という意思表示と見なされ、他のマネージャーがそのフィールドを所有していない限り、そのフィールドはリソースから削除されてしまう。

もう一つは「オーナーシップの独立性」の原則である。複数のフィールドマネージャーが同じリソースに対して協調して作業する場合でも、それぞれのマネージャーは自分が責任を持つフィールドだけをマニフェストに記述すればよい。他のマネージャーが管理しているフィールドについて考慮したり、自分のマニフェストに含めたりする必要はない。SSAはそれぞれのマネージャーの管理範囲を正確に把握し、互いに競合することなく共存できるようなメカニズムを提供している。

KubernetesにおけるServer-Side Applyは、複数のシステムやチームが協力して複雑なアプリケーションやインフラを管理する現代のIT環境において、非常に強力かつ不可欠な機能である。フィールドが「意図せず消える」現象は、SSAのバグではなく、むしろその堅牢な宣言的設定管理を実現するための「仕様」であると理解することが極めて重要だ。このSSAの挙動を深く理解することで、システムエンジニアはより安全で信頼性の高いKubernetesコントローラーを開発し、リソース管理における予期せぬ問題を未然に防ぐことができるだろう。