Merge pull request #105357 from openshift-cherrypick-robot/cherry-pick-105260-to-enterprise-4.21

[enterprise-4.21] OSDOCS-16861 Additional ADV updates to core net docs

modules/adding-a-custom-CA-during-cluster-installation.adoc

@@ -6,9 +6,10 @@
 [id="adding-a-custom-CA-during-cluster-installation_{context}"]
 = Adding a custom CA during cluster installation 
 
-You can add a custom CA to the cluster-wide truststore during installation by providing the certificate in your `install-config.yaml` file.
+[role="_abstract"]
+To add a custom Certificate Authority (CA) to your {product-title} cluster during initial cluster installation, you can add the CA certificate to your `install-config.yaml` file. Adding the CA certificate during installation ensures that your cluster trusts the CA after installation.
 
-This procedure uses the `additionalTrustBundle` parameter. If you are also configuring an egress proxy, you can add this parameter to your `install-config.yaml` file along with your proxy configuration. For more information on the available proxy settings, see the "Configuring the cluster-wide proxy" chapter.
+The following procedure uses the `additionalTrustBundle` parameter. If you are also configuring an egress proxy, you can add this parameter to your `install-config.yaml` file along with your proxy configuration. For more information on the available proxy settings, see the "Configuring the cluster-wide proxy" chapter.
 
 .Prerequisites 
 
@@ -28,14 +29,14 @@ apiVersion: v1
 baseDomain: my.domain.com
 metadata:
   name: my-cluster
-additionalTrustBundle: | <1>
+additionalTrustBundle: |
   -----BEGIN CERTIFICATE-----
   <MY_PEM_ENCODED_CA_CERT>
   -----END CERTIFICATE-----
 ----
 +
-<1> The `additionalTrustBundle` parameter contains the custom CA certificate that you want the cluster to trust. The installation program uses the certificate to generate a `user-ca-bundle` `ConfigMap` object in the `openshift-config` namespace.
+where:
++
+`additionalTrustBundle`:: Specifies the custom CA certificate that you want the cluster to trust. The installation program uses the certificate to generate a `user-ca-bundle` `ConfigMap` object in the `openshift-config` namespace.
 
-. Save the `install-config.yaml` file and continue with your cluster installation.
-
-During installation, the Cluster Network Operator (CNO) merges the certificate you provided with the system's default trust bundle. This process makes your custom CA trusted across the entire cluster.
+. Save the `install-config.yaml` file and continue with your cluster installation.

modules/adding-a-custom-CA-to-a-running-cluster.adoc

@@ -6,7 +6,8 @@
 [id="adding-a-custom-CA-to-a-running-cluster_{context}"]
 = Adding a custom CA to a running cluster
 
-For a running cluster, you can add a custom CA by creating a `ConfigMap` object that contains your certificate and then referencing that `ConfigMap` object in the cluster `Proxy` object.
+[role="_abstract"]
+To add a custom CA certificate to your running {product-title} cluster, you can create a `ConfigMap` object with your certificate and reference it in the cluster `Proxy` object.
 
 [NOTE]
 ====
@@ -25,8 +26,6 @@ This procedure uses the `trustedCA` field in the `Proxy` object. If you also nee
 
 .Procedure
 
-The procedure involves two stages: creating a `ConfigMap` object with your certificate and then updating the cluster to trust it.
-
 . Create a `ConfigMap` object with your CA certificate.
 
 .. Create a YAML file named `custom-ca.yaml` to define the `ConfigMap` object.
@@ -38,20 +37,24 @@ The procedure involves two stages: creating a `ConfigMap` object with your certi
 apiVersion: v1
 kind: ConfigMap
 metadata:
-  name: custom-ca-bundle      <1>
-  namespace: openshift-config  <2>
+  name: custom-ca-bundle
+  namespace: openshift-config
 data:
-  ca-bundle.crt: |         <3>
+  ca-bundle.crt: |
     -----BEGIN CERTIFICATE-----
     <MY_PEM_ENCODED_CA_CERT>
     -----END CERTIFICATE-----
 ----
 +
-<1> The name of the `ConfigMap` object that you will reference from the `Proxy` object.
-<2> The `ConfigMap` object must be created in the `openshift-config` namespace.
-<3> The data key for the certificate bundle must be `ca-bundle.crt`.
+where:
++
+--
+`metadata.name`:: Specifies the name of the `ConfigMap` object that you will reference from the `Proxy` object.
+`metadata.namespace`:: Specifies the namespace of the `ConfigMap` object.
+`data.ca-bundle.crt`:: Specifies the data key for the certificate bundle.
+--
 
-. Apply the manifest to create the `ConfigMap` object in the cluster:
+. Apply the manifest to create the `ConfigMap` object in the cluster by running the following command:
 +
 [source,terminal]
 ----
@@ -60,11 +63,11 @@ $ oc apply -f custom-ca.yaml
 
 . Reference the `ConfigMap` object in the cluster `Proxy` object.
 
-.. Run the following `oc patch` command to update the cluster `Proxy` object to reference the `ConfigMap` object you just created.
+.. Update the cluster `Proxy` object to reference the `ConfigMap` object you just created by running the following command:
 +
 [source,terminal]
 ----
 $ oc patch proxy/cluster --type=merge --patch='{"spec":{"trustedCA":{"name":"custom-ca-bundle"}}}'
 ----
-
-After you run this command, the Machine Config Operator (MCO) detects the change and begins distributing the new trusted CA to all nodes in the cluster.
++
+After you run this command, the Machine Config Operator (MCO) detects the change and begins distributing the new trusted CA to all nodes in the cluster.

modules/certificate-injection-using-operators.adoc

@@ -6,10 +6,8 @@
 [id="certificate-injection-using-operators_{context}"]
 = Certificate injection using Operators
 
-Once your custom CA certificate is added to the cluster via ConfigMap, the
-Cluster Network Operator merges the user-provided and system CA certificates
-into a single bundle and injects the merged bundle into the Operator requesting
-the trust bundle injection.
+[role="_abstract"]
+In {product-title}, certificate injection using Operators merges your custom Certificate Authorities (CAs) with system certificates and injects the merged bundle into Operators that request it. You can use this feature so your Operators trust custom certificates without requiring manual certificate bundle management.
 
 [IMPORTANT]
 ====
@@ -34,10 +32,13 @@ kind: ConfigMap
 metadata:
   labels:
     config.openshift.io/inject-trusted-cabundle: "true"
-  name: ca-inject <1>
+  name: ca-inject
   namespace: apache
 ----
-<1> Specifies the empty ConfigMap name.
+where:
+--
+`metadata.name`:: Specifies the empty ConfigMap name.
+--
 
 The Operator mounts this ConfigMap into the container's local trust store.
 
@@ -76,8 +77,12 @@ spec:
         configMap:
           name: ca-inject
           items:
-            - key: ca-bundle.crt <1>
-              path: tls-ca-bundle.pem <2>
+            - key: ca-bundle.crt
+              path: tls-ca-bundle.pem
 ----
-<1> `ca-bundle.crt` is required as the ConfigMap key.
-<2> `tls-ca-bundle.pem` is required as the ConfigMap path.
+
+where:
+--
+`volumes.items.key`:: Specifies the ConfigMap key.
+`volumes.items.path`:: Specifies the ConfigMap path.
+--

modules/nw-cluster-network-range-edit.adoc

@@ -6,13 +6,19 @@
 [id="nw-cluster-network-range-edit_{context}"]
 = Expanding the cluster network IP address range
 
-You can expand the IP address range for the cluster network. Because this change requires rolling out a new Operator configuration across the cluster, it can take up to 30 minutes to take effect.
+[role="_abstract"]
+To expand the cluster network IP address range in {product-title} to support more nodes, you can modify the cluster network CIDR mask using the `oc patch` command.
+
+[NOTE]
+====
+This change requires rolling out a new Operator configuration across the cluster, and can take up to 30 minutes to take effect.
+====
 
 .Prerequisites
 
-* Install the OpenShift CLI (`oc`).
-* Log in to the cluster with a user with `cluster-admin` privileges.
-* Ensure that the cluster uses the OVN-Kubernetes network plugin.
+* You have installed the OpenShift CLI (`oc`).
+* You have logged in to the cluster with a user with `cluster-admin` privileges.
+* You have ensured that the cluster uses the OVN-Kubernetes network plugin.
 
 .Procedure
 

modules/verifying-the-custom-ca-configuration.adoc

@@ -6,7 +6,8 @@
 [id="verifying-the-custom-ca-configuration_{context}"]
 = Verifying the custom CA configuration
 
-After you add your custom CA certificate, you can verify that it has been successfully added to the cluster-wide trust bundle.
+[role="_abstract"]
+To verify that your custom CA certificate has been successfully added to the {product-title} cluster-wide trust bundle, you can view the contents of the trusted-ca-bundle `ConfigMap` object and check that your certificate is included.
 
 .Prerequisites
 
@@ -45,4 +46,5 @@ data:
     <YOUR_CUSTOM_CA_CERTIFICATE_SHOULD_BE_HERE>
     -----END CERTIFICATE-----
 ----
++
 If your certificate is present in the output, the cluster now trusts your custom PKI.

networking/configuring_network_settings/configuring-a-custom-pki.adoc

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-To ensure secure communication between internal components, your {product-title} cluster uses a shared set of trusted Certificate Authorities (CAs). If your organization uses its own private certificates (a custom PKI), you must add your CA to the cluster so that all components trust it.
+[role="_abstract"]
+To ensure secure communication between internal components in your {product-title} cluster, you can add your organization's custom Certificate Authority (CA) certificates to the cluster-wide truststore.
 
 You can add your custom CA certificates to the cluster-wide truststore in one of two ways:
 

networking/configuring_network_settings/configuring-cluster-network-range.adoc

@@ -6,12 +6,11 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-As a cluster administrator, you can expand the cluster network range after cluster installation. You might want to expand the cluster network range if you need more IP addresses for additional nodes.
+[role="_abstract"]
+To expand the cluster network range in {product-title} to support more nodes and IP addresses, you can modify the cluster network CIDR mask after cluster installation. This procedure requires the OVN-Kubernetes network plugin and provides more IP space for additional nodes.
 
 For example, if you deployed a cluster and specified `10.128.0.0/19` as the cluster network range and a host prefix of `23`, you are limited to 16 nodes. You can expand that to 510 nodes by changing the CIDR mask on a cluster to `/14`.
 
-When expanding the cluster network address range, your cluster must use the xref:../../networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc#about-ovn-kubernetes[OVN-Kubernetes network plugin]. Other network plugins are not supported.
-
 The following limitations apply when modifying the cluster network IP address range:
 
 - The CIDR mask size specified must always be smaller than the currently configured CIDR mask size, because you can only increase IP space by adding more nodes to an installed cluster
@@ -21,8 +20,9 @@ The following limitations apply when modifying the cluster network IP address ra
 include::modules/nw-cluster-network-range-edit.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
-[id="configuring-cluster-network-range-additional-resources"]
+[id="additional-resources_{context}"]
 == Additional resources
 
+* xref:../../networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc#about-ovn-kubernetes[OVN-Kubernetes network plugin]
 * link:https://access.redhat.com/labs/ocpnc/[Red Hat OpenShift Network Calculator]
 * xref:../../networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc#about-ovn-kubernetes[About the OVN-Kubernetes network plugin]