# ファイナライザー(Finalizers)

LLMS index: [llms.txt](/llms.txt)

---

<!-- overview -->

<p>ファイナライザーは、削除対象としてマークされたリソースを完全に削除する前に、特定の条件が満たされるまでKubernetesを待機させるための名前空間付きのキーです。
ファイナライザーは、削除されたオブジェクトが所有していたリソースをクリーンアップするように<a class='glossary-tooltip' title='クラスターの状態をAPIサーバーから取得、見張る制御ループで、現在の状態を望ましい状態に移行するように更新します。' data-bs-toggle='tooltip' data-bs-placement='top' href='/ja/docs/concepts/architecture/controller/' target='_blank' aria-label='コントローラー'>コントローラー</a>に警告します。</p>
<p>Kubernetesにファイナライザーが指定されたオブジェクトを削除するように指示すると、Kubernetes APIはそのオブジェクトに<code>.metadata.deletionTimestamp</code>を追加し削除対象としてマークして、ステータスコード<code>202</code>(HTTP &quot;Accepted&quot;)を返します。
コントロールプレーンやその他のコンポーネントがファイナライザーによって定義されたアクションを実行している間、対象のオブジェクトは終了中の状態のまま残っています。
それらのアクションが完了したら、そのコントローラーは関係しているファイナライザーを対象のオブジェクトから削除します。
<code>metadata.finalizers</code>フィールドが空になったら、Kubernetesは削除が完了したと判断しオブジェクトを削除します。</p>
<p>ファイナライザーはリソースの<a class='glossary-tooltip' title='Kubernetesがクラスターリソースをクリーンアップするために使用するさまざまなメカニズムの総称です。' data-bs-toggle='tooltip' data-bs-placement='top' href='/ja/docs/concepts/architecture/garbage-collection/' target='_blank' aria-label='ガベージコレクション'>ガベージコレクション</a>を管理するために使うことができます。
例えば、コントローラーが対象のリソースを削除する前に関連するリソースやインフラをクリーンアップするためにファイナライザーを定義することができます。</p>

ファイナライザーを利用すると、対象のリソースを削除する前に特定のクリーンアップを行うよう<a class='glossary-tooltip' title='クラスターの状態をAPIサーバーから取得、見張る制御ループで、現在の状態を望ましい状態に移行するように更新します。' data-bs-toggle='tooltip' data-bs-placement='top' href='/ja/docs/concepts/architecture/controller/' target='_blank' aria-label='コントローラー'>コントローラー</a>に警告することで、<a class='glossary-tooltip' title='An entity in the Kubernetes system, representing part of the state of your cluster.' data-bs-toggle='tooltip' data-bs-placement='top' href='/ja/docs/concepts/overview/working-with-objects/#kubernetes-objects' target='_blank' aria-label='オブジェクト'>オブジェクト</a>の<a class='glossary-tooltip' title='Kubernetesがクラスターリソースをクリーンアップするために使用するさまざまなメカニズムの総称です。' data-bs-toggle='tooltip' data-bs-placement='top' href='/ja/docs/concepts/architecture/garbage-collection/' target='_blank' aria-label='ガベージコレクション'>ガベージコレクション</a>を制御することができます。

大抵の場合、ファイナライザーは実行されるコードを指定することはありません。
その代わり、一般的にはアノテーションのように特定のリソースに関するキーのリストになります。
Kubernetesはいくつかのファイナライザーを自動的に追加しますが、自分で追加することもできます。

## ファイナライザーはどのように動作するか {#how-finalizers-work}

マニフェストファイルを使ってリソースを作るとき、`metadata.finalizers`フィールドの中でファイナライザーを指定することができます。
リソースを削除しようとするとき、削除リクエストを扱うAPIサーバーは`finalizers`フィールドの値を確認し、以下のように扱います。

  * 削除を開始した時間をオブジェクトの`metadata.deletionTimestamp`フィールドに設定します。
  * `metadata.finalizers`フィールドが空になるまでオブジェクトが削除されるのを阻止します。
  * ステータスコード`202`(HTTP "Accepted")を返します。

ファイナライザーを管理しているコントローラーは、オブジェクトの削除がリクエストされたことを示す`metadata.deletionTimestamp`がオブジェクトに設定されたことを検知します。
するとコントローラーはリソースに指定されたファイナライザーの要求を満たそうとします。
ファイナライザーの条件が満たされるたびに、そのコントローラーはリソースの`finalizers`フィールドの対象のキーを削除します。
`finalizers`フィールドが空になったとき、`deletionTimestamp`フィールドが設定されたオブジェクトは自動的に削除されます。
管理外のリソース削除を防ぐためにファイナライザーを利用することもできます。

ファイナライザーの一般的な例は`kubernetes.io/pv-protection`で、これは`PersistentVolume`オブジェクトが誤って削除されるのを防ぐためのものです。
Podが`PersistentVolume`オブジェクトを利用中の場合、Kubernetesは`pv-protection`ファイナライザーを追加します。
`PersistentVolume`を削除しようとすると`Terminating`ステータスになりますが、ファイナライザーが存在しているためコントローラーはボリュームを削除することができません。
Podが`PersistentVolume`の利用を停止するとKubernetesは`pv-protection`ファイナライザーを削除し、コントローラーがボリュームを削除します。


<div class="alert alert-info" role="note"><h4 class="alert-heading">備考:</h4><ul>
<li>
<p>オブジェクトを<code>DELETE</code>すると、Kubernetesはそのオブジェクトに削除タイムスタンプを追加し、削除待ちとなったオブジェクトの<code>.metadata.finalizers</code>フィールドへの変更をただちに制限し始めます。
既存のファイナライザーを削除する(<code>finalizers</code>リストからエントリーを削除する)ことはできますが、新しいファイナライザーを追加することはできません。
また、いったん設定された<code>deletionTimestamp</code>を変更することもできません。</p>
</li>
<li>
<p>削除がリクエストされた後は、このオブジェクトを復活させることはできません。
唯一の方法は、削除して同様のオブジェクトを新しく作成することです。</p>
</li>
</ul>
</div>



<div class="alert alert-info" role="note"><h4 class="alert-heading">備考:</h4>カスタムファイナライザー名は、<code>example.com/finalizer-name</code>のように公開された修飾されたファイナライザー名で<strong>なければなりません</strong>。
Kubernetesはこの形式を強制しており、いずれかのカスタムファイナライザーに対して修飾されたファイナライザー名を使用していない変更については、APIサーバーがオブジェクトへの書き込みを拒否します。</div>


## オーナーリファレンス、ラベル、ファイナライザー {#owners-labels-finalizers}

<a class='glossary-tooltip' title='ユーザーにとって意味があり関連性のある識別属性を、オブジェクトにタグ付けするものです。' data-bs-toggle='tooltip' data-bs-placement='top' href='/ja/docs/concepts/overview/working-with-objects/labels' target='_blank' aria-label='ラベル'>ラベル</a>のように、
[オーナーリファレンス](/docs/concepts/overview/working-with-objects/owners-dependents/)はKubernetesのオブジェクト間の関係性を説明しますが、利用される目的が異なります。
<a class='glossary-tooltip' title='クラスターの状態をAPIサーバーから取得、見張る制御ループで、現在の状態を望ましい状態に移行するように更新します。' data-bs-toggle='tooltip' data-bs-placement='top' href='/ja/docs/concepts/architecture/controller/' target='_blank' aria-label='コントローラー'>コントローラー</a>がPodのようなオブジェクトを管理するとき、関連するオブジェクトのグループの変更を追跡するためにラベルを利用します。
例えば、<a class='glossary-tooltip' title='完了まで実行される有限またはバッチのタスク。' data-bs-toggle='tooltip' data-bs-placement='top' href='/ja/docs/concepts/workloads/controllers/job/' target='_blank' aria-label='Job'>Job</a>がいくつかのPodを作成するとき、JobコントローラーはそれらのPodにラベルを付け、クラスター内の同じラベルを持つPodの変更を追跡します。

Jobコントローラーは、Podを作成したJobを指す*オーナーリファレンス*もそれらのPodに追加します。
Podが実行されているときにJobを削除すると、Kubernetesはオーナーリファレンス(ラベルではない)を使って、クリーンアップする必要のあるPodをクラスター内から探し出します。

また、Kubernetesは削除対象のリソースのオーナーリファレンスを認識して、ファイナライザーを処理します。

状況によっては、ファイナライザーが依存オブジェクトの削除をブロックしてしまい、対象のオーナーオブジェクトが完全に削除されず予想以上に長時間残ってしまうことがあります。
このような状況では、対象のオーナーと依存オブジェクトの、ファイナライザーとオーナーリファレンスを確認して問題を解決する必要があります。


<div class="alert alert-info" role="note"><h4 class="alert-heading">備考:</h4>オブジェクトが削除中の状態で詰まってしまった場合、削除を続行するために手動でファイナライザーを削除することは避けてください。
通常、ファイナライザーは理由があってリソースに追加されているものであるため、強制的に削除してしまうとクラスターで何らかの問題を引き起こすことがあります。
そのファイナライザーの目的を理解しており、かつ別の方法でそれを達成できる場合にのみ行うべきです(例えば、依存オブジェクトを手動でクリーンアップするなど)。</div>


## 次の項目

* Kubernetesブログの[ファイナライザーを利用した削除の制御](/blog/2021/05/14/using-finalizers-to-control-deletion/)をお読みください。