pub async fn finalizer<K, ReconcileFut>(
api: &Api<K>,
finalizer_name: &str,
obj: Arc<K>,
reconcile: impl FnOnce(Event<K>) -> ReconcileFut,
) -> Result<Action, Error<ReconcileFut::Error>>
Expand description
Reconcile an object in a way that requires cleanup before an object can be deleted.
It does this by managing a ObjectMeta::finalizers
entry,
which prevents the object from being deleted before the cleanup is done.
In typical usage, if you use finalizer
then it should be the only top-level “action”
in your applier
/Controller
’s reconcile
function.
§Expected Flow
- User creates object
- Reconciler sees object
finalizer
addsfinalizer_name
toObjectMeta::finalizers
- Reconciler sees updated object
finalizer
runsEvent::Apply
- User updates object
- Reconciler sees updated object
finalizer
runsEvent::Apply
- User deletes object
- Reconciler sees deleting object
finalizer
runsEvent::Cleanup
finalizer
removesfinalizer_name
fromObjectMeta::finalizers
- Kubernetes sees that all
ObjectMeta::finalizers
are gone and finally deletes the object
§Guarantees
If Event::Apply
is ever started then Event::Cleanup
must succeed before the Kubernetes object deletion completes.
§Assumptions
finalizer_name
must be unique among the controllers interacting with the object
Event::Apply
and Event::Cleanup
must both be idempotent, and tolerate being executed several times (even if previously cancelled).
Event::Cleanup
must tolerate Event::Apply
never having ran at all, or never having succeeded. Keep in mind that
even infallible .await
s are cancellation points.
§Caveats
Object deletes will get stuck while the controller is not running, or if cleanup
fails for some reason.
reconcile
should take the object that the Event
contains, rather than trying to reuse obj
, since it may have been updated.
§Errors
Event::Apply
and Event::Cleanup
are both fallible, their errors are passed through as Error::ApplyFailed
and Error::CleanupFailed
, respectively.
In addition, adding and removing the finalizer itself may fail. In particular, this may be because of
network errors, lacking permissions, or because another finalizer
was updated in the meantime on the same object.