Merge pull request #108928 from openshift-cherrypick-robot/cherry-pick-107857-to-enterprise-4.17

[enterprise-4.17] OSDOCS-17042 Deleting Machine CQA

Author: bscott-rh

machine_management/deleting-machine.adoc

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can delete a specific machine.
+[role="_abstract"]
+If you need to remove a machine from your cluster, you can delete a specific machine. If the machine is part of a machine set, deleting the machine can help troubleshoot and resolve unhealthy nodes and other technical issues.
 
 //Deleting a specific machine
 include::modules/machine-delete.adoc[leveloffset=+1]

modules/machine-delete.adoc

@@ -7,11 +7,12 @@
 [id="machine-delete_{context}"]
 = Deleting a specific machine
 
-You can delete a specific machine.
+[role="_abstract"]
+To remove a machine from your cluster, or restart a machine that is part of a machine set, you can use the {oc-first} to delete a specific machine.
 
 [IMPORTANT]
 ====
-Do not delete a control plane machine unless your cluster uses a control plane machine set.
+Do not delete a control plane machine unless your cluster uses a control plane machine set. If the machine that you delete belongs to a machine set, a new machine is immediately created to satisfy the specified number of replicas.
 ====
 
 .Prerequisites
@@ -40,11 +41,11 @@ The command output contains a list of machines in the `<clusterid>-<role>-<cloud
 $ oc delete machine <machine> -n openshift-machine-api
 ----
 +
+Replace `<machine>` with the name of the machine.
++
 [IMPORTANT]
 ====
 By default, the machine controller tries to drain the node that is backed by the machine until it succeeds. In some situations, such as with a misconfigured pod disruption budget, the drain operation might not be able to succeed. If the drain operation fails, the machine controller cannot proceed removing the machine.
 
 You can skip draining the node by annotating `machine.openshift.io/exclude-node-draining` in a specific machine.
-====
-+
-If the machine that you delete belongs to a machine set, a new machine is immediately created to satisfy the specified number of replicas.
+====

modules/machine-lifecycle-hook-deletion-etcd.adoc

@@ -6,7 +6,8 @@
 [id="machine-lifecycle-hook-deletion-etcd_{context}"]
 = Quorum protection with machine lifecycle hooks
 
-For {product-title} clusters that use the Machine API Operator, the etcd Operator uses lifecycle hooks for the machine deletion phase to implement a quorum protection mechanism.
+[role="_abstract"]
+To protect etcd quorum on {product-title} clusters that use the Machine API Operator, the etcd Operator uses lifecycle hooks for the machine deletion phase to implement a quorum protection mechanism.
 
 By using a `preDrain` lifecycle hook, the etcd Operator can control when the pods on a control plane machine are drained and removed. To protect etcd quorum, the etcd Operator prevents the removal of an etcd member until it migrates that member onto a new node within the cluster.
 
@@ -47,9 +48,11 @@ metadata:
 spec:
   lifecycleHooks:
     preDrain:
-    - name: EtcdQuorumOperator <1>
-      owner: clusteroperator/etcd <2>
+    - name: EtcdQuorumOperator
+      owner: clusteroperator/etcd
   ...
 ----
-<1> The name of the `preDrain` lifecycle hook.
-<2> The hook-implementing controller that manages the `preDrain` lifecycle hook.
+where:
+
+`spec.lifecycleHooks.preDrain.name`:: Specifies the name of the `preDrain` lifecycle hook.
+`spec.lifecycleHooks.preDrain.owner`:: Specifies the hook-implementing controller that manages the `preDrain` lifecycle hook.

modules/machine-lifecycle-hook-deletion-format.adoc

@@ -6,6 +6,7 @@
 [id="machine-lifecycle-hook-deletion-format_{context}"]
 = Deletion lifecycle hook configuration
 
+[role="_abstract"]
 The following YAML snippets demonstrate the format and placement of deletion lifecycle hook configurations within a machine set:
 
 .YAML snippet demonstrating a `preDrain` lifecycle hook
@@ -18,12 +19,14 @@ metadata:
 spec:
   lifecycleHooks:
     preDrain:
-    - name: <hook_name> <1>
-      owner: <hook_owner> <2>
+    - name: <hook_name>
+      owner: <hook_owner>
   ...
 ----
-<1> The name of the `preDrain` lifecycle hook.
-<2> The hook-implementing controller that manages the `preDrain` lifecycle hook.
+where:
+
+`<hook_name>`:: Specifies the name of the `preDrain` lifecycle hook.
+`<hook_owner>`:: Specifies the hook-implementing controller that manages the `preDrain` lifecycle hook.
 
 .YAML snippet demonstrating a `preTerminate` lifecycle hook
 [source,yaml]
@@ -35,13 +38,14 @@ metadata:
 spec:
   lifecycleHooks:
     preTerminate:
-    - name: <hook_name> <1>
-      owner: <hook_owner> <2>
+    - name: <hook_name>
+      owner: <hook_owner>
   ...
 ----
-<1> The name of the `preTerminate` lifecycle hook.
-<2> The hook-implementing controller that manages the `preTerminate` lifecycle hook.
+where:
 
+`<hook_name>`:: Specifies the name of the `preDrain` lifecycle hook.
+`<hook_owner>`:: Specifies the hook-implementing controller that manages the `preDrain` lifecycle hook.
 
 [id="machine-lifecycle-hook-deletion-example_{context}"]
 == Example lifecycle hook configuration
@@ -57,18 +61,19 @@ metadata:
   ...
 spec:
   lifecycleHooks:
-    preDrain: <1>
+    preDrain:
     - name: MigrateImportantApp
       owner: my-app-migration-controller
-    preTerminate: <2>
+    preTerminate:
     - name: BackupFileSystem
       owner: my-backup-controller
     - name: CloudProviderSpecialCase
-      owner: my-custom-storage-detach-controller <3>
+      owner: my-custom-storage-detach-controller
     - name: WaitForStorageDetach
       owner: my-custom-storage-detach-controller
   ...
 ----
-<1> A `preDrain` lifecycle hook stanza that contains a single lifecycle hook.
-<2> A `preTerminate` lifecycle hook stanza that contains three lifecycle hooks.
-<3> A hook-implementing controller that manages two `preTerminate` lifecycle hooks: `CloudProviderSpecialCase` and `WaitForStorageDetach`.
+where:
+
+`spec.lifecycleHooks.preDrain`:: Specifies a `preDrain` lifecycle hook stanza that contains a single lifecycle hook.
+`spec.lifecycleHooks.preTerminate`:: Specifies a `preTerminate` lifecycle hook stanza that contains three lifecycle hooks. Note that one controller can own multiple lifecycle hooks, as `my-custom-storage-detach-controller` does in the example.

modules/machine-lifecycle-hook-deletion-uses.adoc

@@ -6,8 +6,10 @@
 [id="machine-lifecycle-hook-deletion-uses_{context}"]
 = Machine deletion lifecycle hook examples for Operator developers
 
-Operators can use lifecycle hooks for the machine deletion phase to modify the machine deletion process. The following examples demonstrate possible ways that an Operator can use this functionality.
+[role="_abstract"]
+Operators can use lifecycle hooks for the machine deletion phase to modify the machine deletion process.
 
+The following examples demonstrate possible ways that an Operator can use this functionality.
 
 [id="machine-lifecycle-hook-deletion-uses-predrain_{context}"]
 == Example use cases for `preDrain` lifecycle hooks

modules/machine-lifecycle-hook-deletion.adoc

@@ -9,7 +9,10 @@
 [id="machine-lifecycle-hook-deletion_{context}"]
 = Lifecycle hooks for the machine deletion phase
 
-Machine lifecycle hooks are points in the reconciliation lifecycle of a machine where the normal lifecycle process can be interrupted. In the machine `Deleting` phase, these interruptions provide the opportunity for components to modify the machine deletion process.
+[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