Function kube_runtime::finalizer::finalizer

source · 
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>>
where
    K: Resource + Clone + DeserializeOwned + Serialize + Debug,
    ReconcileFut: TryFuture<Ok = Action>,
    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

  1. User creates object
  2. Reconciler sees object
  3. finalizer adds finalizer_name to ObjectMeta::finalizers
  4. Reconciler sees updated object
  5. finalizer runs Event::Apply
  6. User updates object
  7. Reconciler sees updated object
  8. finalizer runs Event::Apply
  9. User deletes object
  10. Reconciler sees deleting object
  11. finalizer runs Event::Cleanup
  12. finalizer removes finalizer_name from ObjectMeta::finalizers
  13. 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 .awaits 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.