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

dfitzmau · dfitzmau · commit 794762cc23a4 · 2025-12-18T16:12:35.000Z
diff --git a/modules/configuration-externalip.adoc b/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.
 
diff --git a/modules/nw-allocate-load-balancers-to-subnets-procedure.adoc b/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.
-====
+====
diff --git a/modules/nw-allocating-load-balancers-to-subnets.adoc b/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.
diff --git a/modules/nw-externalip-about.adoc b/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]
diff --git a/modules/restrictions-on-ip-assignment.adoc b/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.
diff --git a/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/allocating-load-balancers.adoc b/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
diff --git a/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-externalip.adoc b/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-externalip.adoc
@@ -6,13 +6,13 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-As a cluster administrator, you can select an IP address block that is external to the cluster that can send traffic to services in the cluster.
+[role="_abstract"]
+As a cluster administrator, you can select an IP address block that is external to the cluster that can send traffic to services in the cluster. This functionality is generally most useful for clusters installed on bare-metal hardware.
 
-This functionality is generally most useful for clusters installed on bare-metal hardware.
-
-== Prerequisites
-
-* Your network infrastructure must route traffic for the external IP addresses to your cluster.
+[IMPORTANT]
+====
+Before you configure ExternalIPs for services, your network infrastructure must route traffic for the external IP addresses to your cluster.
+====
 
 // About ExternalIP
 include::modules/nw-externalip-about.adoc[leveloffset=+1]
