// Module included in the following assemblies:
//
// * machine_management/deleting-machine.adoc
// Others TBD.

//Placement considerations: Is this general info? Does it go with deletion docs? CPMS docs? etcd docs? Possibly some combo of those, or perhaps etcd as an example of a use case?

:_mod-docs-content-type: CONCEPT
[id="machine-lifecycle-hook-deletion_{context}"]
= Lifecycle hooks for the machine deletion phase

[role="_abstract"]
You can use lifecycle hooks to modify the process of machine deletion. Machine lifecycle hooks are points in the reconciliation lifecycle of a machine where the normal lifecycle process can be interrupted.

For example, you might use a `preDrain` lifecycle hook to maintain etcd quorum when deleting a control plane machine.

[id="machine-lifecycle-hook-deletion-terms_{context}"]
== Terminology and definitions

To understand the behavior of lifecycle hooks for the machine deletion phase, you must understand the following concepts:

Reconciliation:: Reconciliation is the process by which a controller attempts to make the real state of the cluster and the objects that it comprises match the requirements in an object specification.

Machine controller:: The machine controller manages the reconciliation lifecycle for a machine. For machines on cloud platforms, the machine controller is the combination of an {product-title} controller and a platform-specific actuator from the cloud provider.
+
In the context of machine deletion, the machine controller performs the following actions:
+
--
* Drain the node that is backed by the machine.
* Delete the machine instance from the cloud provider.
* Delete the `Node` object.
--

Lifecycle hook:: A lifecycle hook is a defined point in the reconciliation lifecycle of an object where the normal lifecycle process can be interrupted. Components can use a lifecycle hook to inject changes into the process to accomplish a desired outcome.
+
There are two lifecycle hooks in the machine `Deleting` phase:
+
--
* `preDrain` lifecycle hooks must be resolved before the node that is backed by the machine can be drained.
* `preTerminate` lifecycle hooks must be resolved before the instance can be removed from the infrastructure provider.
--

Hook-implementing controller:: A hook-implementing controller is a controller, other than the machine controller, that can interact with a lifecycle hook. A hook-implementing controller can do one or more of the following actions:
+
--
* Add a lifecycle hook.
* Respond to a lifecycle hook.
* Remove a lifecycle hook.
--
+
Each lifecycle hook has a single hook-implementing controller, but a hook-implementing controller can manage one or more hooks.

[id="machine-lifecycle-hook-deletion-order_{context}"]
== Machine deletion processing order

In {product-title} {product-version}, there are two lifecycle hooks for the machine deletion phase: `preDrain` and `preTerminate`. When all hooks for a given lifecycle point are removed, reconciliation continues as normal.

.Machine deletion flow
image::310_OpenShift_machine_deletion_hooks_0223.png["The sequence of events in the machine `Deleting` phase."]

The machine `Deleting` phase proceeds in the following order:

. An existing machine is slated for deletion for one of the following reasons:
** A user with `cluster-admin` permissions uses the `oc delete machine` command.
** The machine gets a `machine.openshift.io/delete-machine` annotation.
** The machine set that manages the machine marks it for deletion to reduce the replica count as part of reconciliation.
** The cluster autoscaler identifies a node that is unnecessary to meet the deployment needs of the cluster.
** A machine health check is configured to replace an unhealthy machine.
. The machine enters the `Deleting` phase, in which it is marked for deletion but is still present in the API.
. If a `preDrain` lifecycle hook exists, the hook-implementing controller that manages it does a specified action.
+
Until all `preDrain` lifecycle hooks are satisfied, the machine status condition `Drainable` is set to `False`.
. There are no unresolved `preDrain` lifecycle hooks and the machine status condition `Drainable` is set to `True`.
. The machine controller attempts to drain the node that is backed by the machine.
** If draining fails, `Drained` is set to `False` and the machine controller attempts to drain the node again.
** If draining succeeds, `Drained` is set to `True`.
. The machine status condition `Drained` is set to `True`.
. If a `preTerminate`  lifecycle hook exists, the hook-implementing controller that manages it does a specified action.
+
Until all `preTerminate` lifecycle hooks are satisfied, the machine status condition `Terminable` is set to `False`.
. There are no unresolved `preTerminate` lifecycle hooks and the machine status condition `Terminable` is set to `True`.
. The machine controller removes the instance from the infrastructure provider.
. The machine controller deletes the `Node` object.

