OSDOCS-5074: Choosing subnets when creating a LoadBalancerService ingress Controller

modules/nw-ingress-setting-select-subnet-loadbalancerservice.adoc

@@ -0,0 +1,92 @@
+// Modules included in the following assemblies:
+//
+// * ingress/configure-ingress-operator.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-ingress-setting-select-subnet-Loadbalancerservice_{context}"]
+= Choosing subnets while creating a LoadBalancerService Ingress Controller
+
+You can manually specify load balancer subnets for Ingress Controllers in an existing cluster. By default, the load balancer subnets are automatically discovered by AWS, but specifying them in the Ingress Controller overrides this, allowing for manual control.
+
+.Prerequisites
+* You must have an installed AWS cluster.
+* You must know the names or IDs of the subnets to which you intend to map your `IngressController`.
+
+.Procedure
+
+. Create a custom resource (CR) file.
++
+Create a YAML file (e.g., `sample-ingress.yaml`) with the following content:
++
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  namespace: openshift-ingress-operator
+  name: <name>
+spec:
+  domain: <domain>
+  endpointPublishingStrategy:
+    type: LoadBalancerService
+    loadBalancer:
+      scope: External
+  dnsManagementPolicy: Managed
+----
+
+. Create a custom resource (CR) file.
++
+Add subnets to your YAML file:
++
+--
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  name:  <name> <1>
+  namespace: openshift-ingress-operator
+spec:
+  domain: <domain> <2>
+  endpointPublishingStrategy:
+    type: LoadBalancerService
+    loadBalancer:
+      scope: External
+      providerParameters:
+        type: AWS
+        aws:
+          type: Classic
+          classicLoadBalancer: <3>
+            subnets:
+              ids: <4>
+              - <subnet> <5>
+              - <subnet>
+              - <subnet>
+dnsManagementPolicy: Managed
+----
+<1> Replace `<name>` with a name for the `IngressController`.
+<2> Replace `<domain>` with the DNS name serviced by the `IngressController`.
+<3> You can also use the `networkLoadBalancer` field if using an NLB.
+<4> You can optionally specify a subnet by name using the `names` field instead of specifying the subnet by ID.
+<5> Specify subnet IDs (or names if you using `names`).
++
+[IMPORTANT]
+====
+You can specify a maximum of one subnet per availability zone. Only provide public subnets for external Ingress Controllers and private subnets for internal Ingress Controllers.
+====
+--
++
+. Apply the CR file.
+
+.. Save the file and apply it using the {oc-first}.
++
+[source,terminal]
+----
+$  oc apply -f sample-ingress.yaml
+----
+.. Confirm the load balancer was provisioned successfully by checking the `IngressController` conditions. 
++
+[source,terminal]
+----
+$ oc get ingresscontroller -n openshift-ingress-operator <name> -o jsonpath="{.status.conditions}" | yq -PC
+----

modules/nw-ingress-setting-update-subnet-loadbalancerservice.adoc

@@ -0,0 +1,88 @@
+// Modules included in the following assemblies:
+//
+// * ingress/configure-ingress-operator.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-ingress-setting-update-subnet-Loadbalancerservice_{context}"]
+= Updating the subnets on an existing Ingress Controller
+
+You can update an `IngressController` with manually specified load balancer subnets in {product-title} to avoid any disruptions, to maintain the stability of your services, and to ensure that your network configuration aligns with your specific requirements. The following procedures show you how to select and apply new subnets, verify the configuration changes, and confirm successful load balancer provisioning. 
+
+[WARNING]
+====
+This procedure may cause an outage that can last several minutes due to new DNS records propagation, new load balancers provisioning, and other factors. IP addresses and canonical names of the Ingress Controller load balancer might change after applying this procedure.
+====
+
+.Procedure
+To update an `IngressController` with manually specified load balancer subnets, you can follow these steps:
+
+.  Modify the existing IngressController to update to the new subnets.
++
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  name:  <name> <1>
+  namespace: openshift-ingress-operator
+spec:
+  domain: <domain> <2>
+  endpointPublishingStrategy:
+    type: LoadBalancerService
+    loadBalancer:
+      scope: External
+      providerParameters:
+        type: AWS
+        aws:
+          type: Classic <3>
+          classicLoadBalancer: <4>
+            subnets:
+              ids: <5>
+              - <updated_subnet> <6>
+              - <updated_subnet>
+              - <updated_subnet>
+----
+<1> Replace `<name>` with a name for the `IngressController`.
+<2> Replace `<domain>` with the DNS name serviced by the `IngressController`.
+<3> Specify updated subnet IDs (or names if you using `names`).
+<4> You can also use the `networkLoadBalancer` field if using an NLB.
+<5> You can optionally specify a subnet by name using the `names` field instead of specifying the subnet by ID.
+<6> Update subnet IDs (or names if you are using `names`).
++
+[IMPORTANT]
+====
+You can specify a maximum of one subnet per availability zone. Only provide public subnets for external Ingress Controllers and private subnets for internal Ingress Controllers.
+====
+
+. Examine the `Progressing` condition on the `IngressController` for instructions on how to apply the subnet updates by running the following command:
++
+[source,terminal]
+----
+$ oc get ingresscontroller -n openshift-ingress-operator subnets -o jsonpath="{.status.conditions[?(@.type==\"Progressing\")]}" | yq -PC
+----
++
+.Example output
+[source,terminal]
+----
+lastTransitionTime: "2024-11-25T20:19:31Z"
+message: 'One or more status conditions indicate progressing: LoadBalancerProgressing=True (OperandsProgressing: One or more managed resources are progressing: The IngressController subnets were changed from [...] to [...].  To effectuate this change, you must delete the service: `oc -n openshift-ingress delete svc/router-<name>`; the service load-balancer will then be deprovisioned and a new one created. This will most likely cause the new load-balancer to have a different host name and IP address and cause disruption. To return to the previous state, you can revert the change to the IngressController: [...]'
+reason: IngressControllerProgressing
+status: "True"
+type: Progressing
+----
+
+. To apply the update, delete the service associated with the Ingress controller by running the following command:
+
+[source,terminal]
+----
+$ oc -n openshift-ingress delete svc/router-<name>
+----
+
+.Verification
+
+* To confirm that the load balancer was provisioned successfully, check the `IngressController` conditions by running the following command:
++
+[source,terminal]
+----  
+$ oc get ingresscontroller -n openshift-ingress-operator <name> -o jsonpath="{.status.conditions}" | yq -PC
+----

networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws.adoc

@@ -40,6 +40,10 @@ Before you can configure an Ingress Controller NLB on a new AWS cluster, you mus
 
 include::modules/nw-aws-nlb-new-cluster.adoc[leveloffset=+2]
 
+include::modules/nw-ingress-setting-select-subnet-loadbalancerservice.adoc[leveloffset=+2]
+
+include::modules/nw-ingress-setting-update-subnet-loadbalancerservice.adoc[leveloffset=+2]
+
 [role="_additional-resources"]
 [id="additional-resources_configuring-ingress-cluster-traffic-aws"]
 == Additional resources