OSDOCS-16862: CQA2.0 of CORE-3: Ingress Controllers and Load Balancing Overview

Author: dfitzmau

modules/configuration-externalip.adoc

@@ -6,7 +6,8 @@
 [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}. These parameters are listed as follows:
 
 * `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,7 +6,8 @@
 [id="example-policy-objects_{context}"]
 = Example policy objects
 
-The examples in this section show different `spec.externalIP.policy` configurations. 
+[role="_abstract"]
+Reference the following examples 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.
 +

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

@@ -6,33 +6,43 @@
 [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.
 
-.Prerequisites
+When defining entries for control plane load balancers in the `subnets` list, ensure that you adhere to the following 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
+# ...
+----
 
-Before you begin, ensure you have:
+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. 
 
-* An existing AWS virtual private cloud (VPC).
+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.
 
-* Pre-configured AWS subnets intended for use by the OpenShift cluster, with the following considerations:
+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.
 
-** You have a list of their subnet IDs (for example, `subnet-0123456789abcdef0`). These IDs will be used in the `install-config.yaml` file.
+.Prerequisites
 
+* An existing AWS virtual private cloud (VPC).
+* Pre-configured AWS subnets intended for use by the OpenShift 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 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]
 ----
@@ -41,84 +51,63 @@ $ 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`.
+. Open the `install-config.yaml` file located in `<your_installation_directory>` by using a text editor. 
+
+. 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>
+pullSecret: '...'
+sshKey: '...'
 ----
-<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:
+where:
 +
-[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
-# ...
-----
-+
-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).
-+
-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`:: Your base domain.
+`region`:: Your AWS region.
+`vpc`:: The vpc object under `platform.aws` contains the subnets list.
+`subnets`:: List of all subnet objects that OpenShift will use. Each object defines a subnet id and its roles.
+`id`:: Replace with your AWS Subnet ID. 
+`type.IngressControllerLB`:: 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`:: The `type: ClusterNode` role designates this subnet for control plane and compute nodes. These are typically private subnets.
+`pullSecret`:: Your pull secret.
+`sshKey`:: Your 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.
-====
+====

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

@@ -6,4 +6,5 @@
 [id="nw-allocating-load-balancers-to-subnets_{context}"]
 = Allocating API and Ingress Load Balancers to Specific Subnets on AWS
 
+[role="_abstract"]
 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.

modules/nw-externalip-about.adoc

@@ -6,6 +6,7 @@
 [id="nw-externalip-about_{context}"]
 = About ExternalIP
 
+[role="_abstract"]
 For non-cloud environments, {product-title} supports the use of the ExternalIP facility to specify external IP addresses in the `spec.externalIPs[]` parameter of the `Service` object. A service configured with an ExternalIP functions similarly to a service with `type=NodePort`, whereby you traffic directs to a local node for load balancing.
 
 [IMPORTANT]

modules/nw-externalip-configuring.adoc

@@ -6,14 +6,15 @@
 [id="nw-externalip-configuring_{context}"]
 = Configure external IP address blocks for your cluster
 
+[role="_abstract"]
 As a cluster administrator, you can configure the following ExternalIP settings:
 
 - An ExternalIP address block used by {product-title} to automatically populate the `spec.clusterIP` field for a `Service` object.
 - A policy object to restrict what IP addresses may be manually assigned to the `spec.clusterIP` array of a `Service` object.
 
 .Prerequisites
 
-* Install the OpenShift CLI (`oc`).
+* Install the {oc-first}
 * Access to the cluster as a user with the `cluster-admin` role.
 
 .Procedure
@@ -42,10 +43,10 @@ metadata:
   name: cluster
 spec:
   ...
-  externalIP: <1>
+  externalIP:
   ...
 ----
-<1> Specify the configuration for the `externalIP` stanza.
+* `externalIP`: Specify the configuration for the `externalIP` stanza.
 
 . To confirm the updated ExternalIP configuration, enter the following command:
 +

modules/nw-externalip-object.adoc

@@ -6,12 +6,12 @@
 [id="nw-externalip-object_{context}"]
 = ExternalIP address block configuration
 
+[role="_abstract"]
 The configuration for ExternalIP address blocks is defined by a Network custom resource (CR) named `cluster`. The Network CR is part of the `config.openshift.io` API group.
 
 [IMPORTANT]
 ====
-During cluster installation, the Cluster Version Operator (CVO) automatically creates a Network CR named `cluster`.
-Creating any other CR objects of this type is not supported.
+During cluster installation, the Cluster Version Operator (CVO) automatically creates a Network CR named `cluster`. Creating any other CR objects of this type is not supported.
 ====
 
 The following YAML describes the ExternalIP configuration:
@@ -25,36 +25,32 @@ metadata:
   name: cluster
 spec:
   externalIP:
-    autoAssignCIDRs: [] <1>
+    autoAssignCIDRs: []
     policy: <2>
       ...
 ----
-<1> Defines the IP address block in CIDR format that is available for automatic assignment of external IP addresses to a service.
+* `autoAssignCIDRs`: Defines the IP address block in CIDR format that is available for automatic assignment of external IP addresses to a service.
 Only a single IP address range is allowed.
-
-<2> Defines restrictions on manual assignment of an IP address to a service.
-If no restrictions are defined, specifying the `spec.externalIP` field in a `Service` object is not allowed.
-By default, no restrictions are defined.
+* `policy`: Defines restrictions on manual assignment of an IP address to a service. If no restrictions are defined, specifying the `spec.externalIP` field in a `Service` object is not allowed. By default, no restrictions are defined.
 
 The following YAML describes the fields for the `policy` stanza:
 
 .Network.config.openshift.io `policy` stanza
 [source,yaml]
 ----
 policy:
-  allowedCIDRs: [] <1>
-  rejectedCIDRs: [] <2>
+  allowedCIDRs: []
+  rejectedCIDRs: []
 ----
-<1> A list of allowed IP address ranges in CIDR format.
-<2> A list of rejected IP address ranges in CIDR format.
-
+* `allowedCIDRs`: A list of allowed IP address ranges in CIDR format.
+* `rejectedCIDRs`: A list of rejected IP address ranges in CIDR format.
 
 == Example external IP configurations
 
 Several possible configurations for external IP address pools are displayed in the following examples:
 
-- The following YAML describes a configuration that enables automatically assigned external IP addresses:
-+
+The following YAML describes a configuration that enables automatically assigned external IP addresses:
+
 .Example configuration with `spec.externalIP.autoAssignCIDRs` set
 [source,yaml]
 ----
@@ -69,8 +65,8 @@ spec:
     - 192.168.132.254/29
 ----
 
-- The following YAML configures policy rules for the allowed and rejected CIDR ranges:
-+
+The following YAML configures policy rules for the allowed and rejected CIDR ranges:
+
 .Example configuration with `spec.externalIP.policy` set
 [source,yaml]
 ----

modules/restrictions-on-ip-assignment.adoc

@@ -6,9 +6,10 @@
 [id="restrictions-on-ip-assignment_{context}"]
 = Restrictions on the assignment of an external IP address
 
+[role="_abstract"]
 As a cluster administrator, you can specify IP address blocks to allow and to reject IP addresses for a service. Restrictions apply only to users without `cluster-admin` privileges. A cluster administrator can always set the service `spec.externalIPs[]` field to any IP address.
 
-You configure an IP address policy by specifying Classless Inter-Domain Routing (CIDR) address blocks for the `spec.ExternalIP.policy` parameter in the `policy` object. 
+You configure an IP address policy by specifying Classless Inter-Domain Routing (CIDR) address blocks for the `spec.ExternalIP.policy` parameter in the `policy` object, as demonstrated in the following example:
 
 .Example in JSON form of a `policy` object and its CIDR parameters
 [source,json]
@@ -23,9 +24,9 @@ You configure an IP address policy by specifying Classless Inter-Domain Routing
 
 When configuring policy restrictions, the following rules apply:
 
-- If `policy` is set to `{}`, creating a `Service` object with `spec.ExternalIPs[]` results in a failed service. This setting is the default for {product-title}. The same behavior exists for `policy: null`.
-- If `policy` is set and either `policy.allowedCIDRs[]` or `policy.rejectedCIDRs[]` is set, the following rules apply:
+* If `policy` is set to `{}`, creating a `Service` object with `spec.ExternalIPs[]` results in a failed service. This setting is the default for {product-title}. The same behavior exists for `policy: null`.
+* If `policy` is set and either `policy.allowedCIDRs[]` or `policy.rejectedCIDRs[]` is set, the following rules apply:
+** If `allowedCIDRs[]` and `rejectedCIDRs[]` are both set, `rejectedCIDRs[]` has precedence over `allowedCIDRs[]`.
+** If `allowedCIDRs[]` is set, creating a `Service` object with `spec.ExternalIPs[]` succeeds only if the specified IP addresses are allowed.
+** If `rejectedCIDRs[]` is set, creating a `Service` object with `spec.ExternalIPs[]` succeeds only if the specified IP addresses are not rejected.
 
-* If `allowedCIDRs[]` and `rejectedCIDRs[]` are both set, `rejectedCIDRs[]` has precedence over `allowedCIDRs[]`.
-* If `allowedCIDRs[]` is set, creating a `Service` object with `spec.ExternalIPs[]` succeeds only if the specified IP addresses are allowed.
-* If `rejectedCIDRs[]` is set, creating a `Service` object with `spec.ExternalIPs[]` succeeds only if the specified IP addresses are not rejected.

networking/ingress_load_balancing/configuring_ingress_cluster_traffic/allocating-load-balancers.adoc

@@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 You can manage application traffic efficiently by allocating load balancers. Network administrators can allocate load balancers to customize deployments which can ensure optimal traffic distribution, high availability of applications, uninterrupted service, and network segmentation.
 
 // Allocating API and Ingress Load Balancers to Specific Subnets on AWS