Merge pull request #104156 from dfitzmau/OSDOCS-16862

OSDOCS-16862: CQA2.0 of CORE-3: Ingress Controllers and Load Balancin…

Author: dfitzmau

_topic_maps/_topic_map.yml

@@ -1692,7 +1692,7 @@ Topics:
       File: overview-traffic
     - Name: Configuring ExternalIPs for services
       File: configuring-externalip
-    - Name: Configuring ingress cluster traffic using an Ingress Controller
+    - Name: Configuring ingress cluster traffic by using an Ingress Controller
       File: configuring-ingress-cluster-traffic-ingress-controller
     - Name: Configuring the Ingress Controller endpoint publishing strategy
       File: nw-configuring-ingress-controller-endpoint-publishing-strategy

modules/configuration-externalip.adoc

@@ -6,7 +6,10 @@
 [id="configuration-externalip_{context}"]
 = Configuration for ExternalIP
 
-The following parameters in the `Network.config.openshift.io` custom resource (CR) govern the use of an external IP address in {product-title}:
+[role="_abstract"]
+You can set parameters in the `Network.config.openshift.io` custom resource (CR) to govern the use of an external IP address in {product-title}. 
+
+The following list details these parameters:
 
 * `spec.externalIP.autoAssignCIDRs` defines an IP address block used by the load balancer when choosing an external IP address for the service. {product-title} supports only a single IP address block for automatic assignment. This configuration requires less steps than manually assigning ExternalIPs to services, which requires managing the port space of a limited number of shared IP addresses. If you enable automatic assignment, the Cloud Controller Manager Operator allocates an external IP address to a `Service` object with `spec.type=LoadBalancer` defind in its configuration.
 

modules/example-policy-objects.adoc

@@ -6,10 +6,11 @@
 [id="example-policy-objects_{context}"]
 = Example policy objects
 
-The examples in this section show different `spec.externalIP.policy` configurations. 
+[role="_abstract"]
+Reference the examples in the `Example policy objects` section to understand different `spec.externalIP.policy` configurations. 
+
+In the following example, the policy prevents {product-title} from creating any service with a specified external IP address.
 
-- In the following example, the policy prevents {product-title} from creating any service with a specified external IP address.
-+
 .Example policy to reject any value specified for `Service` object `spec.externalIPs[]`
 [source,yaml]
 ----
@@ -23,8 +24,8 @@ spec:
 # ...
 ----
 
-- In the following example, both the `allowedCIDRs` and `rejectedCIDRs` fields are set.
-+
+In the following example, both the `allowedCIDRs` and `rejectedCIDRs` fields are set.
+
 .Example policy that includes both allowed and rejected CIDR blocks
 [source,yaml]
 ----
@@ -42,8 +43,8 @@ spec:
 # ...
 ----
 
-- In the following example, `policy` is set to `{}`. With this configuration, using the `oc get networks.config.openshift.io -o yaml` command to view the configuration means `policy` parameter does not show on the command output. The same behavior exists for `policy: null`.
-+
+In the following example, `policy` is set to `{}`. With this configuration, using the `oc get networks.config.openshift.io -o yaml` command to view the configuration means `policy` parameter does not show on the command output. The same behavior exists for `policy: null`.
+
 .Example policy to allow any value specified for `Service` object `spec.externalIPs[]`
 [source,yaml]
 ----

modules/nw-allocate-load-balancers-to-subnets-procedure.adoc

@@ -6,119 +6,106 @@
 [id="nw-allocating-load-balancers-to-subnets-procedure_{context}"]
 = Specifying AWS subnets for OpenShift API and ingress load balancers at installation
 
-Perform the following steps to allocate API and ingress load balancers to specific subnets.
+[role="_abstract"]
+You can allocate API and ingress load balancers to specific subnets for the purposes of aligning security and networking policies with your organization requirements.
 
-.Prerequisites
+When defining entries for control plane load balancers in the `subnets` list, ensure that you adhere to the following pattern:
 
-Before you begin, ensure you have:
+[source,yaml]
+----
+# ... (within platform.aws.vpc.subnets list)
+      - id: subnet-0fcf8e0392f0910d6 # Public Subnet for External API LB
+        roles:
+        - type: ControlPlaneExternalLB
+      - id: subnet-0fcf8e0392f0910d7 # Private Subnet for Internal API LB
+        roles:
+        - type: ControlPlaneInternalLB
+# ...
+----
 
-* An existing AWS virtual private cloud (VPC).
+For the default public Ingress Controller, any subnet assigned the `IngressControllerLB` role in your `install-config.yaml` file must be a public subnet. For example, the subnet must have a route table entry in AWS that directs outbound traffic to an internet gateway (IGW). Ensure you list all necessary subnets, public and private across the AZs, and assign them appropriate roles according to your cluster architecture. 
 
-* Pre-configured AWS subnets intended for use by the OpenShift cluster, with the following considerations:
+Subnet IDs define the subnets in an existing VPC and can optionally specify their intended roles. If no roles are specified on any subnet, the subnet roles are decided automatically. In this case, the VPC must not contain any other non-cluster subnets without the `kubernetes.io/cluster/<cluster-id>` tag.
 
-** You have a list of their subnet IDs (for example, `subnet-0123456789abcdef0`). These IDs will be used in the `install-config.yaml` file.
+If roles are specified for subnets, each subnet must have at least one assigned role, and the `ClusterNode`, `BootstrapNode`, `IngressControllerLB`, `ControlPlaneExternalLB`, and `ControlPlaneInternalLB` roles must be assigned to at least one subnet. However, if the cluster scope is internal, `ControlPlaneExternalLB` is not required.
 
-** Use subnets spanning at least two availability zones (AZs) for high availability of load balancers and other critical components, like control planes.
+.Prerequisites
 
+* An existing AWS virtual private cloud (VPC).
+* Pre-configured AWS subnets intended for use by the {product-title} cluster, with the following considerations:
+** You have a list of their subnet IDs (for example, `subnet-0123456789abcdef0`). These IDs will be used in the `install-config.yaml` file.
+** Use subnets spanning at least two availability zones (AZs) for high availability of load balancers and other critical components, like control planes.
 ** You have sufficient available IP addresses within these subnets for all assigned roles.
-
 ** The AWS configuration for these subnets, including network ACLs and security groups, must permit necessary traffic for all roles assigned to them. For subnets hosting an ingress controller, this typically includes TCP ports 80 and 443 from required sources.
-
-* You have the OpenShift installer binary for your target OpenShift version.
-
+* You have the {product-title} installation program binary for your target {product-title} version.
 * You have an `install-config.yaml` file.
 
 .Procedure
 
-. Prepare the `install-config.yaml` file:
-+
-If you haven't already, generate the installation configuration file using the OpenShift installer:
+. Generate the installation configuration file by using the {product-title} installation program by entering the following command:
 +
 [source,terminal]
 ----
 $ openshift-install create install-config --dir=<your_installation_directory>
 ----
-+
-This command creates the `install-config.yaml` file in the specified directory.
 
-. Define subnets and assign roles:
-+
-Open the `install-config.yaml` file located in `<your_installation_directory>` using a text editor. You will define your VPC subnets and their designated roles under the `platform.aws.vpc.subnets` field.
-+
-For each AWS subnet you intend the cluster to use, you will create an entry specifying its `id` and a list of `roles`. Each role is an object with a `type` key. To designate a subnet for the default Ingress Controller, assign it a role with `type: IngressControllerLB`.
+. Use a text editor to open the `install-config.yaml` file.
+
+. Define subnets and assign roles. You must define your VPC subnets and their designated roles under the `platform.aws.vpc.subnets` parameter. For each AWS subnet, create an entry by specifying an `id` and a list of `roles`. Each role is an object with a `type` key. To designate a subnet for the default Ingress Controller, assign a role with `type: IngressControllerLB` to the subnet.
 +
 [source,yaml]
 ----
 apiVersion: v1
-baseDomain: example.com <1>
+baseDomain: example.com
 metadata:
   name: my-cluster # Example cluster name
 platform:
   aws:
-    region: us-east-1 <2>
-    vpc: <3>
-      subnets: <4>
-      - id: subnet-0fcf8e0392f0910d5 # Public Subnet in AZ us-east-1a <5>
+    region: us-east-1
+    vpc:
+      subnets:
+      - id: subnet-0fcf8e0392f0910d5 # Public Subnet in AZ us-east-1a
         roles:
-        - type: IngressControllerLB <6>
+        - type: IngressControllerLB
         - type: BootstrapNode
       - id: subnet-0xxxxxxxxxxxxxxza # Public Subnet in another AZ for HA
         roles:
         - type: IngressControllerLB
       - id: subnet-0fcf8e0392f0910d4 # Private Subnet in AZ us-east-1a
         roles:
-        - type: ClusterNode <7>
+        - type: ClusterNode
       - id: subnet-0yyyyyyyyyyyyyyzb # Private Subnet in another AZ for HA
         roles:
         - type: ClusterNode
       # Add other subnet IDs and their roles as needed for your cluster architecture
-pullSecret: '...' <8>
-sshKey: '...' <9>
-----
-<1> Your base domain.
-<2> Your AWS region.
-<3> The vpc object under `platform.aws` contains the subnets list.
-<4> List of all subnet objects that OpenShift will use. Each object defines a subnet id and its roles.
-<5> Replace with your AWS Subnet ID. 
-<6> The `type: IngressControllerLB` role specifically designates this subnet for the default Ingress Controller's LoadBalancer. In private/internal cluster, the subnet with `IngressControllerLB` role must be private.
-<7> The `type: ClusterNode` role designates this subnet for control plane and compute nodes. These are typically private subnets.
-<8> Your pull secret.
-<9> Your SSH key.
-+
-Entries for control plane load balancers in the `subnets` list would follow a similar pattern:
-+
-[source,yaml]
-----
-# ... (within platform.aws.vpc.subnets list)
-      - id: subnet-0fcf8e0392f0910d6 # Public Subnet for External API LB
-        roles:
-        - type: ControlPlaneExternalLB
-      - id: subnet-0fcf8e0392f0910d7 # Private Subnet for Internal API LB
-        roles:
-        - type: ControlPlaneInternalLB
-# ...
+pullSecret: '...'
+sshKey: '...'
 ----
 +
-For the default public Ingress Controller, any subnet assigned the `IngressControllerLB` role in your `install-config.yaml` file must be a public subnet. For example, it must have a route table entry in AWS that directs outbound traffic to an internet gateway (IGW).
+where:
 +
-Ensure you list all necessary subnets, public and private across the AZs, and assign them appropriate roles according to your cluster architecture. 
-+
-Subnet IDs define the subnets in an existing VPC and can optionally specify their intended roles. If no roles are specified on any subnet, the subnet roles are decided automatically. In this case, the VPC must not contain any other non-cluster subnets without the `kubernetes.io/cluster/<cluster-id>` tag.
-+
-If roles are specified for subnets, each subnet must have at least one assigned role, and the `ClusterNode`, `BootstrapNode`, `IngressControllerLB`, `ControlPlaneExternalLB`, and `ControlPlaneInternalLB` roles must be assigned to at least one subnet. However, if the cluster scope is internal, `ControlPlaneExternalLB` is not required.
-
-. Proceed with the cluster Installation:
-+
-After saving your changes to the `install-config.yaml` file, create the cluster:
+`baseDomain`:: Specifies the base domain.
+`region`:: Specifies the AWS region.
+`vpc`:: Specifies the VPC object under `platform.aws` contains the subnets list.
+`subnets`:: Specifies a list of all subnet objects that OpenShift will use. Each object defines a subnet id and its roles.
+`id`:: Specifies the AWS Subnet ID. 
+`type.IngressControllerLB`:: Specifies the `type: IngressControllerLB` role specifically designates this subnet for the default Ingress Controller's LoadBalancer. In private/internal cluster, the subnet with `IngressControllerLB` role must be private.
+`type.ClusterNode`:: Specifies the `type: ClusterNode` role designates this subnet for control plane and compute nodes. These are typically private subnets.
+`pullSecret`:: Specifies the pull secret.
+`sshKey`:: Specifies the SSH key.
+
+. Save you changes to the `install-config.yaml` file.
+
+. Install the cluster by running the following command:
 +
 [source,terminal]
 ----
 $ openshift-install create cluster --dir=<your_installation_directory>
 ----
 +
-The installation program will now use the subnet definitions and explicit role assignments from the `platform.aws.vpc.subnets` section of your `install-config.yaml` file to provision cluster resources, including placing the Ingress Controller's LoadBalancer in the subnets you designated with the `IngressControllerLB` role.
-
+The installation program uses the subnet definitions and explicit role assignments from the `platform.aws.vpc.subnets` section of your `install-config.yaml` file to provision cluster resources. This includes placing the LoadBalancer of the Ingress Controller in the subnets you designated with the `IngressControllerLB` role.
++
 [NOTE]
 ====
-The role assignment mechanism within `platform.aws.vpc.subnets`, such as specifying types like `IngressControllerLB`, `ClusterNode`, `ControlPlaneExternalLB`, `ControlPlaneInternalLB`, `BootstrapNode` is the comprehensive way the OpenShift installer identifies suitable subnets for various cluster services and components.
-====
+The role assignment mechanism within `platform.aws.vpc.subnets`, such as specifying types like `IngressControllerLB`, `ClusterNode`, `ControlPlaneExternalLB`, `ControlPlaneInternalLB`, `BootstrapNode` is the comprehensive way the installation program identifies suitable subnets for various cluster services and components.
+====

modules/nw-allocating-load-balancers-to-subnets.adoc

@@ -6,4 +6,7 @@
 [id="nw-allocating-load-balancers-to-subnets_{context}"]
 = Allocating API and Ingress Load Balancers to Specific Subnets on AWS
 
-You can control the network placement of OpenShift Load Balancers on AWS, including those for the Ingress Controller, by explicitly defining your virtual private cloud's (VPC's) subnets and assigning them specific roles directly within the `platform.aws.vpc.subnets` section of the `install-config.yaml` file. This method provides granular control over which subnets are used for resources, such as the Ingress Controller and other cluster components.
+[role="_abstract"]
+You can control the network placement of {product-title} Load Balancers on {aws-short}, including Load Balancers for the Ingress Controller, by explicitly defining your subnets from the virtual private cloud (VPC). You can then assign the subnets specific roles directly within the `platform.aws.vpc.subnets` section of the `install-config.yaml` file. 
+
+By using this method, you have granular control of subnets that are used for resources, such as the Ingress Controller and other cluster components.

modules/nw-aws-nlb-existing-cluster.adoc

@@ -6,13 +6,16 @@
 [id="nw-aws-nlb-existing-cluster_{context}"]
 = Configuring an Ingress Controller Network Load Balancer on an existing AWS cluster
 
-You can create an Ingress Controller backed by an AWS Network Load Balancer (NLB) on an existing cluster.
+[role="_abstract"]
+To improve performance for high-traffic workloads in {product-title}, configure an Ingress Controller backed by an {aws-full} Network Load Balancer (NLB) on an existing cluster.
+
+You can create an Ingress Controller backed by an {aws-full} Network Load Balancer (NLB) on an existing cluster.
 
 .Prerequisites
 
-* You must have an installed AWS cluster.
-* `PlatformStatus` of the infrastructure resource must be AWS.
-** To verify that the `PlatformStatus` is AWS, run:
+* You installed an {aws-short} cluster.
+* `PlatformStatus` of the infrastructure resource must be {aws-short}.
+** To verify that the `PlatformStatus` is {aws-short}, run the following command:
 +
 [source,terminal]
 ----
@@ -22,8 +25,6 @@ AWS
 
 .Procedure
 
-Create an Ingress Controller backed by an AWS NLB on an existing cluster.
-
 . Create the Ingress Controller manifest:
 +
 [source,terminal]
@@ -37,26 +38,34 @@ Create an Ingress Controller backed by an AWS NLB on an existing cluster.
 apiVersion: operator.openshift.io/v1
 kind: IngressController
 metadata:
-  name: $my_ingress_controller<1>
+  name: <ingress_controller_name>
   namespace: openshift-ingress-operator
 spec:
-  domain: $my_unique_ingress_domain<2>
+  domain: <unique_ingress_domain
   endpointPublishingStrategy:
     type: LoadBalancerService
     loadBalancer:
-      scope: External<3>
+      scope: External
       providerParameters:
         type: AWS
         aws:
           type: NLB
 ----
-<1> Replace `$my_ingress_controller` with a unique name for the Ingress Controller.
-<2> Replace `$my_unique_ingress_domain` with a domain name that is unique among all Ingress Controllers in the cluster. This variable must be a subdomain of the DNS name `<clustername>.<domain>`.
-<3> You can replace `External` with `Internal` to use an internal NLB.
++
+where:
++
+`<ingress_controller_name>`:: Specifies a unique name for the Ingress Controller.
+`<unique_ingress_domain>`:: Specifies a domain name that is unique among all Ingress Controllers in the cluster. This variable must be a subdomain of the DNS name `<clustername>.<domain>`.
+`scope`:: Specifies the type of NLB, either `External` to use an external NLB or `Internal` to use an internal NLB.
 
 . Create the resource in the cluster:
 +
 [source,terminal]
 ----
 $ oc create -f ingresscontroller-aws-nlb.yaml
 ----
++
+[IMPORTANT]
+====
+Before you can configure an Ingress Controller NLB on a new AWS cluster, you must complete the creating the installation configuration file procedure. For more information, see "Creating the installation configuration file".
+====