Merge pull request #92898 from EricPonvelle/OSDOCS-9405_Worker-Node-Updates

OSDOCS-9405: Updated worker node docs to explain the short-lived nature in ROSA/HCP

Author: EricPonvelle

modules/rosa-hcp-upgrade-options.adoc

@@ -8,7 +8,7 @@ You can control the impact of upgrades to your workload by controlling which par
 
 Upgrade only the hosted control plane:: This initiates upgrade of the hosted control plane. It does not impact your worker nodes.
 
-Upgrade nodes in a machine pool:: This initiates a rolling replacement of nodes in the specified machine pool, and temporarily impacts the worker nodes on that machine pool. You can also upgrade multiple machine pools concurrently.
+Upgrade nodes in a machine pool:: {product-title} machine pool upgrades are designed to fully replace each node in a machine pool during the upgrade process. This provides additional security and stability benefits over performing an in-place upgrade. Upgrading the nodes in a machine pool initiates a rolling replacement of nodes in the specified machine pool, and temporarily impacts the worker nodes on that machine pool. You can also upgrade multiple machine pools concurrently.
 
 [IMPORTANT]
 ====

modules/rosa-policy-failure-points.adoc

@@ -11,6 +11,10 @@
 
 ROSA can help further protect you against many common Kubernetes issues by adding Red{nbsp}Hat site reliability engineering (SRE) support and the option to deploy a multiple availability zone cluster, but there are several ways in which a container or infrastructure can still fail. By understanding potential points of failure, you can understand risks and appropriately architect both your applications and your clusters to be as resilient as necessary at each specific level.
 
+ifdef::openshift-rosa,openshift-rosa-hcp[]
+include::snippets/rosa-node-lifecycle.adoc[]
+endif::openshift-rosa,openshift-rosa-hcp[]
+
 [NOTE]
 ====
 An outage can occur at several different levels of infrastructure and cluster components.

modules/rosa-sdpolicy-platform.adoc

@@ -68,6 +68,24 @@ ifndef::openshift-rosa-hcp[]
 endif::openshift-rosa-hcp[]
 clusters at this time. However, custom labels are supported when creating new machine pools.
 
+[id="rosa-sdpolicy-node-lifecycle_{context}"]
+== Node lifecycle
+
+Worker nodes are not guaranteed longevity, and may be replaced at any time as part of the normal operation and management of OpenShift.
+
+A worker node might be replaced in the following circumstances:
+
+* Machine health checks are deployed and configured to ensure that a worker node with a `NotReady` status is replaced to ensure smooth operation of the cluster.
+* AWS EC2 instances may be terminated when AWS detects irreparable failure of the underlying hardware that hosts the instance.
+ifdef::openshift-rosa[]
+* During upgrades, a new node is first provisioned to account for any loss of cluster resources during the upgrade process. Once this new node has been successfully integrated into the cluster via the previously described automated health checks, an older node is then removed from the cluster.
+endif::openshift-rosa[]
+ifdef::openshift-rosa-hcp[]
+* During upgrades, a new, upgraded node is first created and joined to the cluster. Once this new node has been successfully integrated into the cluster via the previously described automated health checks, an older node is then removed from the cluster.
+endif::openshift-rosa-hcp[]
+
+For all containerized workloads running on a Kubernetes based system, it is best practice to configure applications to be resilient of node replacements.
+
 [id="rosa-sdpolicy-backup-policy_{context}"]
 == Cluster backup policy
 

nodes/index.adoc

@@ -19,6 +19,19 @@ ifdef::openshift-rosa-hcp[]
 In {product-title}, the control plane nodes are hosted in a Red{nbsp}Hat-owned AWS account. Red{nbsp}Hat fully manages the control plane infrastructure for you.
 endif::openshift-rosa-hcp[]
 
+ifdef::openshift-rosa,openshift-rosa-hcp[]
+[IMPORTANT]
+====
+Worker nodes are not guaranteed longevity, and may be replaced at any time as part of the normal operation and management of OpenShift. For more details, see 
+ifdef::openshift-rosa[]
+xref:../rosa_architecture/rosa_policy_service_definition/rosa-service-definition.adoc#rosa-sdpolicy-node-lifecycle_rosa-service-definition[Node lifecycle].
+endif::openshift-rosa[]
+ifdef::openshift-rosa-hcp[]
+xref:../rosa_architecture/rosa_policy_service_definition/rosa-hcp-service-definition.adoc#rosa-sdpolicy-node-lifecycle_rosa-hcp-service-definition[Node lifecycle].
+endif::openshift-rosa-hcp[]
+====
+endif::openshift-rosa,openshift-rosa-hcp[]
+
 Having stable and healthy nodes in a cluster is fundamental to the smooth functioning of your hosted application.
 In {product-title}, you can access, manage, and monitor a node through the `Node` object representing the node.
 Using the OpenShift CLI (`oc`) or the web console, you can perform the following operations on a node.

nodes/nodes/nodes-nodes-viewing.adoc

@@ -11,6 +11,10 @@ You can list all the nodes in your cluster to obtain information such as status,
 When you perform node management operations, the CLI interacts with node objects that are representations of actual node hosts.
 The master uses the information from node objects to validate nodes with health checks.
 
+ifdef::openshift-rosa,openshift-rosa-hcp[]
+include::snippets/rosa-node-lifecycle.adoc[]
+endif::openshift-rosa,openshift-rosa-hcp[]
+
 // The following include statements pull in the module files that comprise
 // the assembly. Include any combination of concept, procedure, or reference
 // modules required to cover the user story. You can also include other
@@ -30,3 +34,11 @@ endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 include::modules/nodes-nodes-viewing-listing-pods.adoc[leveloffset=+1]
 
 include::modules/nodes-nodes-viewing-memory.adoc[leveloffset=+1]
+
+.Additional resources
+ifdef::openshift-rosa[]
+* xref:../../rosa_architecture/rosa_policy_service_definition/rosa-service-definition.adoc#rosa-sdpolicy-node-lifecycle_rosa-service-definition[Node lifecycle].
+endif::openshift-rosa[]
+ifdef::openshift-rosa-hcp[]
+* xref:../../rosa_architecture/rosa_policy_service_definition/rosa-hcp-service-definition.adoc#rosa-sdpolicy-node-lifecycle_rosa-hcp-service-definition[Node lifecycle].
+endif::openshift-rosa-hcp[]

rosa_architecture/rosa_policy_service_definition/rosa-policy-understand-availability.adoc

@@ -9,3 +9,11 @@ toc::[]
 Availability and disaster avoidance are extremely important aspects of any application platform. Although {product-title} (ROSA) provides many protections against failures at several levels, customer-deployed applications must be appropriately configured for high availability. To account for outages that might occur with cloud providers, additional options are available such as deploying a cluster across multiple availability zones and maintaining multiple clusters with failover mechanisms.
 
 include::modules/rosa-policy-failure-points.adoc[leveloffset=+1]
+
+.Additional resources
+ifdef::openshift-rosa[]
+* xref:../../rosa_architecture/rosa_policy_service_definition/rosa-service-definition.adoc#rosa-sdpolicy-node-lifecycle_rosa-service-definition[Node lifecycle].
+endif::openshift-rosa[]
+ifdef::openshift-rosa-hcp[]
+* xref:../../rosa_architecture/rosa_policy_service_definition/rosa-hcp-service-definition.adoc#rosa-sdpolicy-node-lifecycle_rosa-hcp-service-definition[Node lifecycle].
+endif::openshift-rosa-hcp[]

rosa_cluster_admin/rosa_nodes/rosa-nodes-machinepools-about.adoc

@@ -29,6 +29,9 @@ A machine pool creates compute machine sets that are all clones of the same conf
 ifdef::openshift-rosa-hcp[]
 In {product-title} clusters, the hosted control plane spans three availability zones (AZ) in the installed cloud region. Each machine pool in a {product-title} cluster deploys in a single subnet within a single AZ. Each of these AZs can have only one machine pool.
 endif::openshift-rosa-hcp[]
+ifdef::openshift-rosa,openshift-rosa-hcp[]
+include::snippets/rosa-node-lifecycle.adoc[]
+endif::openshift-rosa,openshift-rosa-hcp[]
 
 Multiple machine pools can exist on a single cluster, and each machine pool can contain a unique node type and node size configuration.
 
@@ -56,6 +59,10 @@ You cannot change the machine pool node type or size. The machine pool node type
 ====
 * You can add a label to each added machine pool.
 
+ifdef::openshift-rosa,openshift-rosa-hcp[]
+include::snippets/rosa-node-lifecycle.adoc[]
+endif::openshift-rosa,openshift-rosa-hcp[]
+
 .Procedure
 
 * *Optional:* Add a label to the default machine pool after configuration by using the default machine pool labels and running the following command:

rosa_hcp/rosa-hcp-egress-lockdown-install.adoc

@@ -51,7 +51,7 @@ While you may install and upgrade your clusters as you would a regular cluster,
 ====
 
 [id="rosa-hcp-egress-lockdown-install-creating_{context}"]
-== Creating a Virtual Private Cloud for your {hcp-title} clusters
+== Creating a Virtual Private Cloud for your {hcp-title} clusters 
 
 You must have a Virtual Private Cloud (VPC) to create a {hcp-title} cluster. Use one of the following methods to create a VPC:
 

snippets/rosa-node-lifecycle.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * nodes/index.adoc
+
+:_mod-docs-content-type: SNIPPET
+
+[IMPORTANT]
+====
+Worker node longevity is not guaranteed and may be replaced at any time as part of the normal operation and management of OpenShift. For more details about the node lifecycle, refer to _additional resources_.
+====

upgrading/rosa-hcp-upgrading.adoc

@@ -9,12 +9,16 @@ toc::[]
 include::modules/rosa-hcp-upgrade-options.adoc[leveloffset=+1]
 
 .Additional resources
-ifdef::openshift-rosa-hcp[]
-* link:https://docs.openshift.com/rosa/cli_reference/rosa_cli/rosa-manage-objects-cli.html#rosa-edit-machinepool_rosa-managing-objects-cli[ROSA CLI reference: `rosa edit machinepool`]
-endif::openshift-rosa-hcp[]
 ifndef::openshift-rosa-hcp[]
 * xref:../cli_reference/rosa_cli/rosa-manage-objects-cli.adoc#rosa-edit-machinepool_rosa-managing-objects-cli[ROSA CLI reference: `rosa edit machinepool`]
 endif::openshift-rosa-hcp[]
+ifdef::openshift-rosa[]
+* xref:../rosa_architecture/rosa_policy_service_definition/rosa-service-definition.adoc#rosa-sdpolicy-node-lifecycle_rosa-service-definition[Node lifecycle]
+endif::openshift-rosa[]
+ifdef::openshift-rosa-hcp[]
+* link:https://docs.openshift.com/rosa/cli_reference/rosa_cli/rosa-manage-objects-cli.html#rosa-edit-machinepool_rosa-managing-objects-cli[ROSA CLI reference: `rosa edit machinepool`]
+* xref:../rosa_architecture/rosa_policy_service_definition/rosa-hcp-service-definition.adoc#rosa-sdpolicy-node-lifecycle_rosa-hcp-service-definition[Node lifecycle]
+endif::openshift-rosa-hcp[]
 
 //This cannot be a module if we want to use the xrefs
 [id="rosa-lifecycle-policy_{context}"]