Function kube_runtime::finalizer::finalizer [−][src]
pub async fn finalizer<K, ReconcileFut>(
api: &Api<K>,
finalizer_name: &str,
obj: K,
reconcile: impl FnOnce(Event<K>) -> ReconcileFut
) -> Result<ReconcilerAction, Error<ReconcileFut::Error>> where
K: Resource + Clone + DeserializeOwned + Serialize + Debug,
ReconcileFut: TryFuture<Ok = ReconcilerAction>,
ReconcileFut::Error: StdError + 'static,
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
to [ObjectMeta::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
from [ObjectMeta::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.