Merge pull request #100502 from kquinn1204/TELCODOCS-2328-gh

TELCODOCS-2328 updating RDS files for 4.20

Author: slovern

modules/telco-core-about-the-telco-core-cluster-use-model.adoc

@@ -6,20 +6,19 @@
 [id="telco-core-about-the-telco-core-cluster-use-model_{context}"]
 = About the telco core cluster use model
 
-The telco core cluster use model is designed for clusters that run on commodity hardware.
+The telco core cluster use model is designed for clusters running on commodity hardware.
 Telco core clusters support large scale telco applications including control plane functions like signaling, aggregation, session border controller (SBC), and centralized data plane functions such as 5G user plane functions (UPF).
 Telco core cluster functions require scalability, complex networking support, resilient software-defined storage, and support performance requirements that are less stringent and constrained than far-edge RAN deployments.
 
 Networking requirements for telco core functions vary widely across a range of networking features and performance points.
 IPv6 is a requirement and dual-stack is common.
 Some functions need maximum throughput and transaction rate and require support for user-plane DPDK networking.
-Other functions use more typical cloud-native patterns and can rely on OVN-Kubernetes, kernel networking, and load balancing.
+Other functions use typical cloud-native patterns and can rely on OVN-Kubernetes, kernel networking, and load balancing.
 
 Telco core clusters are configured as standard with three control plane and one or more worker nodes configured with the stock (non-RT) kernel.
 In support of workloads with varying networking and performance requirements, you can segment worker nodes by using `MachineConfigPool` custom resources (CR), for example, for non-user data plane or high-throughput use cases.
 In support of required telco operational features, core clusters have a standard set of Day 2 OLM-managed Operators installed.
 
-
 .Telco core RDS cluster service-based architecture and networking topology
 image::openshift-5g-core-cluster-architecture-networking.png[5G core cluster showing a service-based architecture with overlaid networking topology]
 

modules/telco-core-additional-storage-solutions.adoc

@@ -4,6 +4,7 @@
 
 :_mod-docs-content-type: REFERENCE
 [id="telco-core-additional-storage-solutions_{context}"]
+
 = Additional storage solutions
 You can use other storage solutions to provide persistent storage for telco core clusters.
 The configuration and integration of these solutions is outside the scope of the reference design specifications (RDS).

modules/telco-core-agent-based-installer.adoc

@@ -3,31 +3,29 @@
 // * scalability_and_performance/telco_core_ref_design_specs/telco-core-rds.adoc
 
 :_mod-docs-content-type: REFERENCE
+
 [id="telco-core-agent-based-installer_{context}"]
 = Agent-based Installer
 
 New in this release::
 * No reference design updates in this release.
 
 Description::
+The recommended method for Telco Core cluster installation is using Red Hat Advanced Cluster Management.
+The Agent Based Installer (ABI) is a separate installation flow for Openshift in environments without existing infrastructure for running cluster deployments.
+Use the ABI to install {product-title} on bare-metal servers without requiring additional servers or VMs for managing the installation, but does not provide ongoing lifecycle management, monitoring or automations.
+The ABI can be run on any system for example, from a laptop to generate an ISO installation image.
+The ISO is used as the installation media for the cluster control plane nodes.
+You can monitor the progress by using the ABI from any system with network connectivity to the control plane node's API interfaces.
 +
---
-Telco core clusters can be installed using the Agent-based Installer.
-This method allows you to install {product-title} on bare-metal servers without requiring additional servers or VMs for managing the installation.
-The Agent-based Installer can be run on any system (for example, from a laptop) to generate an ISO installation image.
-The ISO is used as the installation media for the cluster supervisor nodes.
-Progress can be monitored using the Agent-based Installer from any system with network connectivity to the supervisor node's API interfaces.
-
-Agent-based Installer supports the following:
+ABI supports the following:
 
-* Installation from declarative CRs.
-* Installation in disconnected environments.
-* Installation without the use of additional servers to support installation, for example, the bastion node.
---
+* Installation from declarative CRs
+* Installation in disconnected environments
+* No additional servers required to support installation, for example, the bastion node is no longer needed
 
 Limits and requirements::
 * Disconnected installation requires a registry with all required content mirrored and reachable from the installed host.
 
 Engineering considerations::
-* Networking configuration should be applied as NMState configuration during installation. Day 2 networking configuration using the NMState Operator is not supported.
-
+* Networking configuration should be applied as NMState configuration during installation as opposed to Day 2 configuration using the NMState Operator.

modules/telco-core-application-workloads.adoc

@@ -13,26 +13,25 @@ Typically, pods that run high performance or latency sensitive CNFs by using use
 When creating pod configurations that require exclusive CPUs, be aware of the potential implications of hyper-threaded systems.
 Pods should request multiples of 2 CPUs when the entire core (2 hyper-threads) must be allocated to the pod.
 
+
 Pods running network functions that do not require high throughput or low latency networking should be scheduled with best-effort or burstable QoS pods and do not require dedicated or isolated CPU cores.
 
 Engineering considerations::
-+
---
-Use the following information to plan telco core workloads and cluster resources:
 
-* As of {product-title} 4.19, cgroup v1 is no longer supported and has been removed. All workloads must now be compatible with cgroup v2. For more information, see link:https://www.redhat.com/en/blog/rhel-9-changes-context-red-hat-openshift-workloads[Red Hat Enterprise Linux 9 changes in the context of Red Hat OpenShift workloads].
+Plan telco core workloads and cluster resources by using the following information:
+
+* As of {product-title} 4.19, `cgroup v1` is no longer supported and has been removed.
+All workloads must now be compatible with `cgroup v2`.
+For more information, see link:https://www.redhat.com/en/blog/rhel-9-changes-context-red-hat-openshift-workloads[Red Hat Enterprise Linux 9 changes in the context of Red Hat OpenShift workloads].
 * CNF applications should conform to the latest version of https://redhat-best-practices-for-k8s.github.io/guide/[Red Hat Best Practices for Kubernetes].
 * Use a mix of best-effort and burstable QoS pods as required by your applications.
 ** Use guaranteed QoS pods with proper configuration of reserved or isolated CPUs in the `PerformanceProfile` CR that configures the node.
 ** Guaranteed QoS Pods must include annotations for fully isolating CPUs.
 ** Best effort and burstable pods are not guaranteed exclusive CPU use.
 Workloads can be preempted by other workloads, operating system daemons, or kernel tasks.
 * Use exec probes sparingly and only when no other suitable option is available.
-** Do not use exec probes if a CNF uses CPU pinning.
-Use other probe implementations, for example, `httpGet` or `tcpSocket`.
-** When you need to use exec probes, limit the exec probe frequency and quantity.
-The maximum number of exec probes must be kept below 10, and the frequency must not be set to less than 10 seconds.
-** You can use startup probes, because they do not use significant resources at steady-state operation.
-The limitation on exec probes applies primarily to liveness and readiness probes.
-Exec probes cause much higher CPU usage on management cores compared to other probe types because they require process forking.
---
+** Do not use exec probes if a CNF uses CPU pinning. Use other probe implementations, for example, `httpGet` or `tcpSocket`.
+** When you need to use exec probes, limit the exec probe frequency and quantity. The maximum number of exec probes must be kept below 10, and the frequency must not be set to less than 10 seconds.
+** You can use startup probes, because they do not use significant resources at steady-state operation. The limitation on exec probes applies primarily to liveness and readiness probes. Exec probes cause much higher CPU usage on management cores compared to other probe types because they require process forking.
+* Use pre-stop hooks to allow the application workload to perform required actions before pod disruption, such as during an upgrade or node maintenance. The hooks enable a pod to save state to persistent storage, offload traffic from a Service, or signal other Pods.
+

modules/telco-core-cluster-common-use-model-engineering-considerations.adoc

@@ -8,9 +8,10 @@
 
 * Cluster workloads are detailed in "Application workloads".
 * Worker nodes should run on either of the following CPUs:
-** Intel 3rd Generation Xeon (IceLake) CPUs or newer when supported by {product-title}, or CPUs with the silicon security bug (Spectre and similar) mitigations turned off.
-Skylake and older CPUs can experience 40% transaction performance drops when Spectre and similar mitigations are enabled. When Skylake and older CPUs change power states, this can cause latency.
-** AMD EPYC Zen 4 CPUs (Genoa, Bergamo).
+** Intel 3rd Generation Xeon (IceLake) CPUs or better when supported by {product-title}, or CPUs with the silicon security bug (Spectre and similar) mitigations turned off.
+Skylake and older CPUs can experience 40% transaction performance drops when Spectre and similar mitigations are enabled.
+** AMD EPYC Zen 4 CPUs (Genoa, Bergamo) or AMD EPYC Zen 5 CPUs (Turin) when supported by {product-title}.
+** Intel Sierra Forest CPUs when supported by the {product-title}.
 ** IRQ balancing is enabled on worker nodes.
 The `PerformanceProfile` CR sets the `globallyDisableIrqLoadBalancing` parameter to a value of `false`.
 Guaranteed QoS pods are annotated to ensure isolation as described in "CPU partitioning and performance tuning".
@@ -23,6 +24,7 @@ Guaranteed QoS pods are annotated to ensure isolation as described in "CPU parti
 
 * The balance between power management and maximum performance varies between machine config pools in the cluster.
 The following configurations should be consistent for all nodes in a machine config pools group.
+
 ** Cluster scaling.
 See "Scalability" for more information.
 ** Clusters should be able to scale to at least 120 nodes.
@@ -35,7 +37,6 @@ For a cluster configured according to the reference configuration running a simu
 ** The NICs used for non-DPDK network traffic should be configured to use at most 32 RX/TX queues.
 ** Nodes with large numbers of pods or other resources might require additional reserved CPUs.
 The remaining CPUs are available for user workloads.
-
 +
 [NOTE]
 ====

modules/telco-core-cluster-network-operator.adoc

@@ -7,18 +7,20 @@
 = Cluster Network Operator
 
 New in this release::
-* No reference design updates in this release
+
+*  No reference design updates in this release
 
 Description::
-+
---
-The Cluster Network Operator (CNO) deploys and manages the cluster network components including the default OVN-Kubernetes network plugin during cluster installation. The CNO allows for configuring primary interface MTU settings, OVN gateway configurations to use node routing tables for pod egress, and additional secondary networks such as MACVLAN.
 
+The Cluster Network Operator (CNO) deploys and manages the cluster network components including the default OVN-Kubernetes network plugin during cluster installation.
+The CNO allows configuration of primary interface MTU settings, OVN gateway modes to use node routing tables for pod egress, and additional secondary networks such as MACVLAN.
++
 In support of network traffic separation, multiple network interfaces are configured through the CNO.
-Traffic steering to these interfaces is configured through static routes applied by using the NMState Operator. To ensure that pod traffic is properly routed, OVN-K is configured with the `routingViaHost` option enabled. This setting uses the kernel routing table and the applied static routes rather than OVN for pod egress traffic.
-
+Traffic steering to these interfaces is configured through static routes applied by using the NMState Operator.
+To ensure that pod traffic is properly routed, OVN-K is configured with the `routingViaHost` option enabled.
+This setting uses the kernel routing table and the applied static routes rather than OVN for pod egress traffic.
++
 The Whereabouts CNI plugin is used to provide dynamic IPv4 and IPv6 addressing for additional pod network interfaces without the use of a DHCP server.
---
 
 Limits and requirements::
 * OVN-Kubernetes is required for IPv6 support.
@@ -29,15 +31,23 @@ MTU size up to 8900 is supported.
 This handler allows a third-party module to process incoming packets before the host processes them, and only one such handler can be registered per network interface.
 Since both MACVLAN and IPVLAN need to register their own `rx_handler` to function, they conflict and cannot coexist on the same interface.
 Review the source code for more details:
+
 ** https://elixir.bootlin.com/linux/v6.10.2/source/drivers/net/ipvlan/ipvlan_main.c#L82[linux/v6.10.2/source/drivers/net/ipvlan/ipvlan_main.c#L82]
 ** https://elixir.bootlin.com/linux/v6.10.2/source/drivers/net/macvlan.c#L1260[linux/v6.10.2/source/drivers/net/macvlan.c#L1260]
+
 * Alternative NIC configurations include splitting the shared NIC into multiple NICs or using a single dual-port NIC, though they have not been tested and validated.
 * Clusters with single-stack IP configuration are not validated.
-* The `reachabilityTotalTimeoutSeconds` parameter in the `Network` CR configures the `EgressIP` node reachability check total timeout in seconds.
-The recommended value is `1` second.
+* EgressIP
+** EgressIP failover time depends on the `reachabilityTotalTimeoutSeconds` parameter in the `Network` CR.
+This parameter determines the frequency of probes used to detect when the selected egress node is unreachable.
+The recommended value of this parameter is `1` second.
+** When EgressIP is configured with multiple egress nodes, the failover time is expected to be on the order of seconds or longer.
+** On nodes with additional network interfaces EgressIP traffic will egress through the interface on which the EgressIP address has been assigned.
+See the "Configuring an egress IP address".
 * Pod-level SR-IOV bonding mode must be set to `active-backup` and a value in `miimon` must be set (`100` is recommended).
 
 Engineering considerations::
-* Pod egress traffic is handled by kernel routing table using the `routingViaHost` option.
+
+* Pod egress traffic is managed by kernel routing table using the `routingViaHost` option.
 Appropriate static routes must be configured in the host.
 

modules/telco-core-common-baseline-model.adoc

@@ -10,20 +10,28 @@ The following configurations and use models are applicable to all telco core use
 The telco core use cases build on this common baseline of features.
 
 Cluster topology::
-Telco core clusters conform to the following requirements:
 
-* High availability control plane (three or more control plane nodes)
-* Non-schedulable control plane nodes
-* Multiple machine config pools
+The telco core reference design supports two distinct cluster configuration variants:
+
+* A non-schedulable control plane variant, where user workloads are strictly prohibited from running on master nodes.
+
+* A schedulable control plane variant, which allows for user workloads to run on master nodes to optimize resource utilization. This variant is only applicable to bare-metal control plane nodes and must be configured at installation time.
++
+All clusters, regardless of the variant, must conform to the following requirements:
+
+* A highly available control plane consisting of three or more nodes.
+
+* The use of multiple machine config pools.
 
 Storage::
-Telco core use cases require persistent storage as provided by {rh-storage}.
+Telco core use cases require highly available persistent storage as provided by an external storage solution.
+{rh-storage} might be used to manage access to the external storage.
 
 Networking::
 Telco core cluster networking conforms to the following requirements:
 
 * Dual stack IPv4/IPv6 (IPv4 primary).
-* Fully disconnected – clusters do not have access to public networking at any point in their lifecycle.
+* Fully disconnected - clusters do not have access to public networking at any point in their lifecycle.
 * Supports multiple networks.
 Segmented networking provides isolation between operations, administration and maintenance (OAM), signaling, and storage traffic.
 * Cluster network type is OVN-Kubernetes as required for IPv6 support.
@@ -43,6 +51,5 @@ User plane networking runs in cloud-native network functions (CNFs).
 
 Service Mesh::
 Telco CNFs can use Service Mesh.
-All telco core clusters require a Service Mesh implementation.
+Telco core clusters typically include a Service Mesh implementation.
 The choice of implementation and configuration is outside the scope of this specification.
-