diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index dc5ed4c4dede..edb607cd3cea 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 diff --git a/modules/configuration-externalip.adoc b/modules/configuration-externalip.adoc index 1e008fbf30cb..6f72349a53c4 100644 --- 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/example-policy-objects.adoc b/modules/example-policy-objects.adoc index 502f6d80ae1d..f33ba447e361 100644 --- a/modules/example-policy-objects.adoc +++ b/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] ---- diff --git a/modules/nw-allocate-load-balancers-to-subnets-procedure.adoc b/modules/nw-allocate-load-balancers-to-subnets-procedure.adoc index 23fcede0985e..86c4cd4e2cb8 100644 --- a/modules/nw-allocate-load-balancers-to-subnets-procedure.adoc +++ b/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: ++ +[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/` 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] ---- $ openshift-install create install-config --dir= ---- -+ -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 `` 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> +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/` 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= ---- + -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. -==== \ No newline at end of file +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. +==== diff --git a/modules/nw-allocating-load-balancers-to-subnets.adoc b/modules/nw-allocating-load-balancers-to-subnets.adoc index 5fbb60982c19..9c21d129563e 100644 --- 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. \ No newline at end of file diff --git a/modules/nw-aws-nlb-existing-cluster.adoc b/modules/nw-aws-nlb-existing-cluster.adoc index 89e9465ece6b..5e1d3ca2612a 100644 --- a/modules/nw-aws-nlb-existing-cluster.adoc +++ b/modules/nw-aws-nlb-existing-cluster.adoc @@ -6,13 +6,14 @@ [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"] +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 +23,6 @@ AWS .Procedure -Create an Ingress Controller backed by an AWS NLB on an existing cluster. - . Create the Ingress Controller manifest: + [source,terminal] @@ -37,22 +36,25 @@ 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: namespace: openshift-ingress-operator spec: - domain: $my_unique_ingress_domain<2> + domain: + 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 `.`. -<3> You can replace `External` with `Internal` to use an internal NLB. ++ +where: ++ +``: Replace `` with a unique name for the Ingress Controller. +``:: Replace `` with a domain name that is unique among all Ingress Controllers in the cluster. This variable must be a subdomain of the DNS name `.`. +`scope`:: You can replace `External` with `Internal` to use an internal NLB. . Create the resource in the cluster: + diff --git a/modules/nw-aws-nlb-new-cluster.adoc b/modules/nw-aws-nlb-new-cluster.adoc index 9a79b5fec4a3..413e8ebc0a8c 100644 --- a/modules/nw-aws-nlb-new-cluster.adoc +++ b/modules/nw-aws-nlb-new-cluster.adoc @@ -7,36 +7,33 @@ [id="nw-aws-nlb-new-cluster_{context}"] = Configuring an Ingress Controller Network Load Balancer on a new AWS cluster -You can create an Ingress Controller backed by an AWS Network Load Balancer (NLB) on a new cluster. +[role="_abstract"] +You can create an Ingress Controller backed by an {aws-full} Network Load Balancer (NLB) on a new cluster in situations where you need more transparent networking capabilities. .Prerequisites -* Create the `install-config.yaml` file and complete any modifications to it. +* Create and edit the `install-config.yaml` file. For instructions, see "Creating the installation configuration file" in the _Additonal resources_ section. .Procedure -Create an Ingress Controller backed by an AWS NLB on a new cluster. - . Change to the directory that contains the installation program and create the manifests: + [source,terminal] ---- -$ ./openshift-install create manifests --dir <1> +$ ./openshift-install create manifests --dir ---- -<1> For ``, specify the name of the directory that -contains the `install-config.yaml` file for your cluster. +* For ``, specify the name of the directory that contains the `install-config.yaml` file for your cluster. . Create a file that is named `cluster-ingress-default-ingresscontroller.yaml` in the `/manifests/` directory: + [source,terminal] ---- -$ touch /manifests/cluster-ingress-default-ingresscontroller.yaml <1> +$ touch /manifests/cluster-ingress-default-ingresscontroller.yaml ---- -<1> For ``, specify the directory name that contains the +``:: For ``, specify the directory name that contains the `manifests/` directory for your cluster. -+ -After creating the file, several network configuration files are in the -`manifests/` directory, as shown: + +. Check the several network configuration files that exist in the `manifests/` directory by entering the following command: + [source,terminal] ---- @@ -71,4 +68,5 @@ spec: ---- . Save the `cluster-ingress-default-ingresscontroller.yaml` file and quit the text editor. -. Optional: Back up the `manifests/cluster-ingress-default-ingresscontroller.yaml` file. The installation program deletes the `manifests/` directory when creating the cluster. + +. Optional: Back up the `manifests/cluster-ingress-default-ingresscontroller.yaml` file because the installation program deletes the `manifests/` directory during cluster creation. diff --git a/modules/nw-aws-replacing-clb-with-nlb.adoc b/modules/nw-aws-replacing-clb-with-nlb.adoc index 479cc982bcd4..09b225d563e1 100644 --- a/modules/nw-aws-replacing-clb-with-nlb.adoc +++ b/modules/nw-aws-replacing-clb-with-nlb.adoc @@ -6,7 +6,8 @@ [id="nw-aws-replacing-clb-with-nlb_{context}"] = Replacing Ingress Controller Classic Load Balancer with Network Load Balancer -You can replace an Ingress Controller that is using a Classic Load Balancer (CLB) with one that uses a Network Load Balancer (NLB) on AWS. +[role="_abstract"] +You can replace an Ingress Controller that is using a Classic Load Balancer (CLB) with one that uses a Network Load Balancer (NLB) on {aws-full}. [WARNING] ==== diff --git a/modules/nw-aws-switching-clb-with-nlb.adoc b/modules/nw-aws-switching-clb-with-nlb.adoc index e98f668a975b..37f87928c8a2 100644 --- a/modules/nw-aws-switching-clb-with-nlb.adoc +++ b/modules/nw-aws-switching-clb-with-nlb.adoc @@ -6,9 +6,10 @@ [id="nw-aws-switching-clb-with-nlb_{context}"] = Switching the Ingress Controller from using a Classic Load Balancer to a Network Load Balancer -You can switch the Ingress Controller that is using a Classic Load Balancer (CLB) to one that uses a Network Load Balancer (NLB) on AWS. +[role="_abstract"] +You can switch the Ingress Controller that is using a Classic Load Balancer (CLB) to one that uses a Network Load Balancer (NLB) on {aws-full}. -Switching between these load balancers will not delete the `IngressController` object. +Switching between these load balancers does not delete the `IngressController` object. [WARNING] ==== @@ -21,7 +22,7 @@ This procedure might cause the following issues: .Procedure -. Modify the existing Ingress Controller that you want to switch to using an NLB. This example assumes that your default Ingress Controller has an `External` scope and no other customizations: +. Modify the existing Ingress Controller that you want to switch to by using an NLB. This example assumes that your default Ingress Controller has an `External` scope and no other customizations: + .Example `ingresscontroller.yaml` file [source,yaml] diff --git a/modules/nw-aws-switching-nlb-with-clb.adoc b/modules/nw-aws-switching-nlb-with-clb.adoc index 8c8d9fe81320..f0529de5ed73 100644 --- a/modules/nw-aws-switching-nlb-with-clb.adoc +++ b/modules/nw-aws-switching-nlb-with-clb.adoc @@ -6,9 +6,8 @@ [id="nw-aws-switching-nlb-with-clb_{context}"] = Switching the Ingress Controller from using a Network Load Balancer to a Classic Load Balancer -You can switch the Ingress Controller that is using a Network Load Balancer (NLB) to one that uses a Classic Load Balancer (CLB) on AWS. - -Switching between these load balancers will not delete the `IngressController` object. +[role="_abstract"] +You can switch the Ingress Controller that is using a Network Load Balancer (NLB) to one that uses a Classic Load Balancer (CLB) on {aws-full}. Switching between these load balancers does not delete the `IngressController` object. [WARNING] ==== diff --git a/modules/nw-configuring-clb-timeouts.adoc b/modules/nw-configuring-clb-timeouts.adoc index c49de76a27a6..91cea5ed41e4 100644 --- a/modules/nw-configuring-clb-timeouts.adoc +++ b/modules/nw-configuring-clb-timeouts.adoc @@ -6,6 +6,7 @@ [id="nw-configuring-clb-timeouts_{context}"] = Configuring Classic Load Balancer timeouts +[role="_abstract"] You can configure the default timeouts for a Classic Load Balancer (CLB) to extend idle connections. .Prerequisites @@ -14,7 +15,7 @@ You can configure the default timeouts for a Classic Load Balancer (CLB) to exte .Procedure -. Set an AWS connection idle timeout of five minutes for the default `ingresscontroller` by running the following command: +. Set an {aws-full} connection idle timeout of five minutes for the default `ingresscontroller` by running the following command: + [source,terminal] ---- @@ -35,7 +36,7 @@ $ oc -n openshift-ingress-operator patch ingresscontroller/default \ {"loadBalancer":{"providerParameters":{"aws":{"classicLoadBalancer": \ {"connectionIdleTimeout":null}}}}}}}' ---- - ++ [NOTE] ==== You must specify the `scope` field when you change the connection timeout value unless the current scope is already set. When you set the `scope` field, you do not need to do so again if you restore the default timeout value. diff --git a/modules/nw-configuring-elb-timeouts-aws-classic.adoc b/modules/nw-configuring-elb-timeouts-aws-classic.adoc index fe25ffd7dfc7..2570b7aaafe8 100644 --- a/modules/nw-configuring-elb-timeouts-aws-classic.adoc +++ b/modules/nw-configuring-elb-timeouts-aws-classic.adoc @@ -6,6 +6,7 @@ [id="nw-configuring-elb-timeouts-aws-classic_{context}"] = Configuring Classic Load Balancer timeouts on AWS -{product-title} provides a method for setting a custom timeout period for a specific route or Ingress Controller. Additionally, an AWS Classic Load Balancer (CLB) has its own timeout period with a default time of 60 seconds. +[role="_abstract"] +{product-title} provides a method for setting a custom timeout period for a specific route or Ingress Controller. Additionally, an {aws-full} Classic Load Balancer (CLB) has its own timeout period with a default time of 60 seconds. If the timeout period of the CLB is shorter than the route timeout or Ingress Controller timeout, the load balancer can prematurely terminate the connection. You can prevent this problem by increasing both the timeout period of the route and CLB. diff --git a/modules/nw-configuring-ingress-cluster-traffic-aws-networking-load-balancer.adoc b/modules/nw-configuring-ingress-cluster-traffic-aws-networking-load-balancer.adoc index 6f13d20be644..f13f341542c6 100644 --- a/modules/nw-configuring-ingress-cluster-traffic-aws-networking-load-balancer.adoc +++ b/modules/nw-configuring-ingress-cluster-traffic-aws-networking-load-balancer.adoc @@ -6,4 +6,5 @@ [id="nw-configuring-ingress-cluster-traffic-aws-network-load-balancer_{context}"] = Configuring ingress cluster traffic on AWS using a Network Load Balancer +[role="_abstract"] {product-title} provides methods for communicating from outside the cluster with services that run in the cluster. One such method uses a Network Load Balancer (NLB). You can configure an NLB on a new or existing AWS cluster. diff --git a/modules/nw-configuring-route-timeouts.adoc b/modules/nw-configuring-route-timeouts.adoc index fa455d255baf..cfb714001530 100644 --- a/modules/nw-configuring-route-timeouts.adoc +++ b/modules/nw-configuring-route-timeouts.adoc @@ -7,6 +7,7 @@ [id="nw-configuring-route-timeouts_{context}"] = Configuring route timeouts +[role="_abstract"] You can configure the default timeouts for an existing route when you have services in need of a low timeout, which is required for Service Level Availability (SLA) purposes, or a high timeout, for cases with a slow back end. [IMPORTANT] @@ -16,7 +17,7 @@ If you configured a user-managed external load balancer in front of your {produc .Prerequisites -* You need a deployed Ingress Controller on a running cluster. +* You deployed an Ingress Controller on a running cluster. .Procedure @@ -25,9 +26,9 @@ If you configured a user-managed external load balancer in front of your {produc [source,terminal] ---- $ oc annotate route \ - --overwrite haproxy.router.openshift.io/timeout= <1> + --overwrite haproxy.router.openshift.io/timeout= ---- -<1> Supported time units are microseconds (us), milliseconds (ms), seconds (s), minutes (m), hours (h), or days (d). +* ``: Supported time units are microseconds (us), milliseconds (ms), seconds (s), minutes (m), hours (h), or days (d). + The following example sets a timeout of two seconds on a route named `myroute`: + diff --git a/modules/nw-creating-project-and-service.adoc b/modules/nw-creating-project-and-service.adoc index 1501c313779c..b219cd47ad15 100644 --- a/modules/nw-creating-project-and-service.adoc +++ b/modules/nw-creating-project-and-service.adoc @@ -6,6 +6,7 @@ [id="nw-creating-project-and-service_{context}"] = Creating a project and service +[role="_abstract"] If the project and service that you want to expose does not exist, create the project and then create the service. If the project and service already exists, skip to the procedure on exposing the service to create a route. diff --git a/modules/nw-externalip-about.adoc b/modules/nw-externalip-about.adoc index 9031b637d080..f6372a627742 100644 --- 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/nw-externalip-configuring.adoc b/modules/nw-externalip-configuring.adoc index aebf02434831..541bba1b7424 100644 --- a/modules/nw-externalip-configuring.adoc +++ b/modules/nw-externalip-configuring.adoc @@ -6,14 +6,17 @@ [id="nw-externalip-configuring_{context}"] = Configure external IP address blocks for your cluster -As a cluster administrator, you can configure the following ExternalIP settings: +[role="_abstract"] +As a cluster administrator, you can configure the ExternalIP settings to provide predictable entry points for external traffic to reach your cluster. + +The following list details these 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 +45,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: + diff --git a/modules/nw-externalip-object.adoc b/modules/nw-externalip-object.adoc index f7355c7e5236..2e383ac0afcd 100644 --- a/modules/nw-externalip-object.adoc +++ b/modules/nw-externalip-object.adoc @@ -6,17 +6,16 @@ [id="nw-externalip-object_{context}"] = ExternalIP address block configuration -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. +[role="_abstract"] +To better understand ExternalIP address blocks, view the example configuration for ExternalIP address blocks that 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: +The following YAML describes the ExternalIP configuration in a `Network.config.openshift.io` CR named `cluster`: -.Network.config.openshift.io CR named `cluster` [source,yaml] ---- apiVersion: config.openshift.io/v1 @@ -25,36 +24,29 @@ metadata: name: cluster spec: externalIP: - autoAssignCIDRs: [] <1> - policy: <2> + autoAssignCIDRs: [] + policy: ... ---- -<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. +* `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. -<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. - -The following YAML describes the fields for the `policy` stanza: +The following YAML describes the fields for the `policy` stanza in the `Network.config.openshift.io` CR: -.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. +The next set of example configurations show external IP address pools configurations. -== Example external IP configurations +The following YAML shows a `spec.externalIP.autoAssignCIDRs` configuration that enables automatically assigned external IP addresses: -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: -+ .Example configuration with `spec.externalIP.autoAssignCIDRs` set [source,yaml] ---- @@ -69,9 +61,8 @@ spec: - 192.168.132.254/29 ---- -- The following YAML configures policy rules for the allowed and rejected CIDR ranges: -+ -.Example configuration with `spec.externalIP.policy` set +The following YAML configuration includes a `spec.externalIP.policy` configuration that sets policy rules for the allowed and rejected CIDR ranges: + [source,yaml] ---- apiVersion: config.openshift.io/v1 diff --git a/modules/nw-ingress-aws-static-eip-nlb-configuration.adoc b/modules/nw-ingress-aws-static-eip-nlb-configuration.adoc index e68595ee3c50..c7316beb2441 100644 --- a/modules/nw-ingress-aws-static-eip-nlb-configuration.adoc +++ b/modules/nw-ingress-aws-static-eip-nlb-configuration.adoc @@ -6,51 +6,54 @@ [id="nw-ingress-aws-static-eip-nlb-configuration_{context}"] = Configuring AWS Elastic IP (EIP) addresses for a Network Load Balancer (NLB) +[role="_abstract"] You can specify static IPs, otherwise known as elastic IPs, for your network load balancer (NLB) in the Ingress Controller. This is useful in situations where you want to configure appropriate firewall rules for your cluster network. .Prerequisites -* You must have an installed AWS cluster. +* You must have an installed {aws-full} cluster. * You must know the names or IDs of the subnets to which you intend to map your `IngressController`. .Procedure -. Create a YAML file that contains the following content: +. Create a YAML file that contains the following example content: + -.`sample-ingress.yaml` [source,yaml] ---- apiVersion: operator.openshift.io/v1 kind: IngressController metadata: namespace: openshift-ingress-operator - name: <1> + name: spec: - domain: <2> + domain: endpointPublishingStrategy: loadBalancer: - scope: External <3> + scope: External type: LoadBalancerService providerParameters: type: AWS aws: type: NLB networkLoadBalancer: - subnets: <4> + subnets: ids: - names: - - - eipAllocations: <5> + eipAllocations: - - - ---- -<1> Replace the `` placeholder with a name for the Ingress Controller. -<2> Replace the `` placeholder with the DNS name serviced by the Ingress Controller. -<3> The scope must be set to the value `External` and be Internet-facing in order to allocate EIPs. -<4> Specify the IDs and names for your subnets. The total number of IDs and names must be equal to your allocated EIPs. -<5> Specify the EIP addresses. ++ +where: ++ +``:: Replace the `` placeholder with a name for the Ingress Controller. +``:: Replace the `` placeholder with the DNS name serviced by the Ingress Controller. +`scope`:: The scope must be set to the value `External` and be Internet-facing in order to allocate EIPs. +`subnets:: Specify the IDs and names for your subnets. The total number of IDs and names must be equal to your allocated EIPs. +`eipAllocations`:: Specify the EIP addresses. + [IMPORTANT] ==== diff --git a/modules/nw-ingress-setting-select-subnet-loadbalancerservice.adoc b/modules/nw-ingress-setting-select-subnet-loadbalancerservice.adoc index c79eac88f36c..19a7774fd060 100644 --- a/modules/nw-ingress-setting-select-subnet-loadbalancerservice.adoc +++ b/modules/nw-ingress-setting-select-subnet-loadbalancerservice.adoc @@ -6,17 +6,16 @@ [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. +[role="_abstract"] +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-full}, but specifying them in the Ingress Controller overrides this, allowing for manual control. .Prerequisites -* You must have an installed AWS cluster. +* You must have an installed {aws-short} 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: +. Create a custom resource (CR) YAML file, such as `sample-ingress.yaml`, and specifying the following content for the file: + [source,yaml] ---- @@ -32,22 +31,20 @@ spec: loadBalancer: scope: External dnsManagementPolicy: Managed +# ... ---- -. Create a custom resource (CR) file. -+ -Add subnets to your YAML file: +. Add subnets to the CR file: + --- [source,yaml] ---- apiVersion: operator.openshift.io/v1 kind: IngressController metadata: - name: <1> + name: namespace: openshift-ingress-operator spec: - domain: <2> + domain: endpointPublishingStrategy: type: LoadBalancerService loadBalancer: @@ -56,37 +53,38 @@ spec: type: AWS aws: type: Classic - classicLoadBalancer: <3> + classicLoadBalancer: subnets: - ids: <4> - - <5> + ids: + - - - dnsManagementPolicy: Managed ---- -<1> Replace `` with a name for the `IngressController`. -<2> Replace `` 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`). ++ +where: ++ +`name`:: Replace `` with a name for the `IngressController`. +`domain`:: Replace `` with the DNS name serviced by the `IngressController`. +`classicLoadBalancer`:: You can also use the `networkLoadBalancer` field if using an NLB. +`ids`:: You can optionally specify a subnet by name using the `names` field instead of specifying the subnet by ID. +``:: 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}. +. Save and apply the CR file by using the {oc-first}: + [source,terminal] ---- $ oc apply -f sample-ingress.yaml ---- -.. Confirm the load balancer was provisioned successfully by checking the `IngressController` conditions. + +. Confirm the load balancer was provisioned successfully by checking the `IngressController` conditions. + [source,terminal] ---- $ oc get ingresscontroller -n openshift-ingress-operator -o jsonpath="{.status.conditions}" | yq -PC ----- \ No newline at end of file +---- diff --git a/modules/nw-ingress-setting-update-subnet-loadbalancerservice.adoc b/modules/nw-ingress-setting-update-subnet-loadbalancerservice.adoc index 1b30053caf95..36c38f1d960d 100644 --- a/modules/nw-ingress-setting-update-subnet-loadbalancerservice.adoc +++ b/modules/nw-ingress-setting-update-subnet-loadbalancerservice.adoc @@ -6,7 +6,8 @@ [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. +[role="_abstract"] +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 example in the procedure shows you how to select and apply new subnets, verify the configuration changes, and confirm successful load balancer provisioning. [WARNING] ==== @@ -14,19 +15,18 @@ This procedure may cause an outage that can last several minutes due to new DNS ==== .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. +. Modify the existing IngressController by specifying the new subnets: + [source,yaml] ---- apiVersion: operator.openshift.io/v1 kind: IngressController metadata: - name: <1> + name: namespace: openshift-ingress-operator spec: - domain: <2> + domain: endpointPublishingStrategy: type: LoadBalancerService loadBalancer: @@ -34,20 +34,24 @@ spec: providerParameters: type: AWS aws: - type: Classic <3> - classicLoadBalancer: <4> + type: Classic + classicLoadBalancer: subnets: - ids: <5> - - <6> + ids: - - + - +# ... ---- -<1> Replace `` with a name for the `IngressController`. -<2> Replace `` 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`). ++ +where: ++ +``:: Replace `` with a name for the `IngressController`. +``:: Replace `` with the DNS name serviced by the `IngressController`. +`type`:: Specify updated subnet IDs (or names if you using `names`). +`classicLoadBalancer`:: You can also use the `networkLoadBalancer` field if using an NLB. +`ids`:: You can optionally specify a subnet by name using the `names` field instead of specifying the subnet by ID. +``:: Update subnet IDs (or names if you are using `names`). + [IMPORTANT] ==== diff --git a/modules/nw-ingress-sharding-concept.adoc b/modules/nw-ingress-sharding-concept.adoc index 17df61b3d682..ea2fd582442a 100644 --- a/modules/nw-ingress-sharding-concept.adoc +++ b/modules/nw-ingress-sharding-concept.adoc @@ -6,6 +6,7 @@ [id="nw-ingress-sharding-concept_{context}"] = Ingress sharding in {product-title} +[role="_abstract"] In {product-title}, an Ingress Controller can serve all routes, or it can serve a subset of routes. By default, the Ingress Controller serves any route created in any namespace in the cluster. You can add additional Ingress Controllers to your cluster to optimize routing by creating _shards_, which are subsets of routes based on selected characteristics. To mark a route as a member of a shard, use labels in the route or namespace `metadata` field. The Ingress Controller uses _selectors_, also known as a _selection expression_, to select a subset of routes from the entire pool of routes to serve. Ingress sharding is useful in cases where you want to load balance incoming traffic across multiple Ingress Controllers, when you want to isolate traffic to be routed to a specific Ingress Controller, or for a variety of other reasons described in the next section. diff --git a/modules/nw-ingress-sharding-default.adoc b/modules/nw-ingress-sharding-default.adoc index 2bf180f202c8..32a669ac9262 100644 --- a/modules/nw-ingress-sharding-default.adoc +++ b/modules/nw-ingress-sharding-default.adoc @@ -7,9 +7,12 @@ [id="nw-ingress-sharding-default_{context}"] = Sharding the default Ingress Controller +[role="_abstract"] +You can restrict an Ingress Controller from servicing routes with specific labels by using either namespace selectors or route selectors. + After creating a new Ingress shard, there might be routes that are admitted to your new Ingress shard that are also admitted by the default Ingress Controller. This is because the default Ingress Controller has no selectors and admits all routes by default. -You can restrict an Ingress Controller from servicing routes with specific labels using either namespace selectors or route selectors. The following procedure restricts the default Ingress Controller from servicing your newly sharded `finance`, `ops`, and `dev`, routes using a namespace selector. This adds further isolation to Ingress shards. +The following procedure restricts the default Ingress Controller from servicing your newly sharded `finance`, `ops`, and `dev`, routes by using a namespace selector. This adds further isolation to Ingress shards. [IMPORTANT] ==== @@ -18,7 +21,7 @@ You must keep all of {product-title}'s administration routes on the same Ingress .Prerequisites -* You installed the OpenShift CLI (`oc`). +* You installed the {oc-first}. * You are logged in as a project administrator. .Procedure @@ -49,5 +52,5 @@ spec: - ops - dev ---- - -The default Ingress Controller will no longer serve the namespaces labeled `name:finance`, `name:ops`, and `name:dev`. ++ +The default Ingress Controller no longer serves the namespaces labeled with `name:finance`, `name:ops`, and `name:dev`. diff --git a/modules/nw-ingress-sharding-dns.adoc b/modules/nw-ingress-sharding-dns.adoc index 70e5e307d49b..12976f55c603 100644 --- a/modules/nw-ingress-sharding-dns.adoc +++ b/modules/nw-ingress-sharding-dns.adoc @@ -6,7 +6,8 @@ [id="nw-ingress-sharding-dns_{context}"] = Ingress sharding and DNS -The cluster administrator is responsible for making a separate DNS entry for each router in a project. A router will not forward unknown routes to another router. +[role="_abstract"] +The cluster administrator is responsible for making a separate DNS entry for each router in a project. A router does not forward unknown routes to another router. Consider the following example: diff --git a/modules/nw-ingress-sharding-namespace-labels.adoc b/modules/nw-ingress-sharding-namespace-labels.adoc index 2e1ee01eb52f..50ecc16fcb88 100644 --- a/modules/nw-ingress-sharding-namespace-labels.adoc +++ b/modules/nw-ingress-sharding-namespace-labels.adoc @@ -7,11 +7,10 @@ [id="nw-ingress-sharding-namespace-labels_{context}"] = Configuring Ingress Controller sharding by using namespace labels -Ingress Controller sharding by using namespace labels means that the Ingress -Controller serves any route in any namespace that is selected by the namespace -selector. +[role="_abstract"] +You can namespace labels to configure Ingress Controller sharding so that the Ingress Controller serves any route in any namespace that is selected by the namespace selector. -.Ingress sharding using namespace labels +.Ingress sharding by using namespace labels image::nw-sharding-namespace-labels.png[A diagram showing multiple Ingress Controllers with different namespace selectors serving routes that belong to the namespace containing a label that matches a given namespace selector] Ingress Controller sharding is useful when balancing incoming traffic load among @@ -37,7 +36,7 @@ metadata: name: sharded namespace: openshift-ingress-operator spec: - domain: <1> + domain: nodePlacement: nodeSelector: matchLabels: @@ -46,7 +45,7 @@ spec: matchLabels: type: sharded ---- -<1> Specify a domain to be used by the Ingress Controller. This domain must be different from the default Ingress Controller domain. +* ``: Specify a domain to be used by the Ingress Controller. This domain must be different from the default Ingress Controller domain. . Apply the Ingress Controller `router-internal.yaml` file: + @@ -58,7 +57,7 @@ $ oc apply -f router-internal.yaml The Ingress Controller selects routes in any namespace that is selected by the namespace selector that have the label `type: sharded`. -. Create a new route using the domain configured in the `router-internal.yaml`: +. Create a new route by using the domain configured in the `router-internal.yaml`: + [source,terminal] ---- diff --git a/modules/nw-ingress-sharding-route-configuration.adoc b/modules/nw-ingress-sharding-route-configuration.adoc index 32c41bbe4cf1..2d41c33a3483 100644 --- a/modules/nw-ingress-sharding-route-configuration.adoc +++ b/modules/nw-ingress-sharding-route-configuration.adoc @@ -7,13 +7,14 @@ [id="nw-ingress-sharding-route-configuration_{context}"] = Creating a route for Ingress Controller sharding -A route allows you to host your application at a URL. Ingress Controller sharding helps balance incoming traffic load among a set of Ingress Controllers. It can also isolate traffic to a specific Ingress Controller. For example, company A goes to one Ingress Controller and company B to another. +[role="_abstract"] +By specifying a route, you can host your application at a URL. Ingress Controller sharding helps balance incoming traffic load among a set of Ingress Controllers. Ingress Controller sharding can also isolate traffic to a specific Ingress Controller. For example, company A goes to one Ingress Controller and company B to another. The following procedure describes how to create a route for Ingress Controller sharding, using the `hello-openshift` application as an example. .Prerequisites -* You installed the OpenShift CLI (`oc`). +* You installed the {oc-first}. * You are logged in as a project administrator. * You have a web application that exposes a port and an HTTP or TLS endpoint listening for traffic on the port. * You have configured the Ingress Controller for sharding. @@ -50,19 +51,22 @@ apiVersion: route.openshift.io/v1 kind: Route metadata: labels: - type: sharded <1> + type: sharded name: hello-openshift-edge namespace: hello-openshift spec: - subdomain: hello-openshift <2> + subdomain: hello-openshift tls: termination: edge to: kind: Service name: hello-openshift ---- -<1> Both the label key and its corresponding label value must match the ones specified in the Ingress Controller. In this example, the Ingress Controller has the label key and value `type: sharded`. -<2> The route will be exposed using the value of the `subdomain` field. When you specify the `subdomain` field, you must leave the hostname unset. If you specify both the `host` and `subdomain` fields, then the route will use the value of the `host` field, and ignore the `subdomain` field. ++ +where: ++ +`type`:: Both the label key and its corresponding label value must match the ones specified in the Ingress Controller. In this example, the Ingress Controller has the label key and value `type: sharded`. +`subdomain`:: The route gets exposed by using the value of the `subdomain` field. When you specify the `subdomain` field, you must leave the hostname unset. If you specify both the `host` and `subdomain` fields, then the route uses the value of the `host` field, and ignore the `subdomain` field. . Use `hello-openshift-route.yaml` to create a route to the `hello-openshift` application by running the following command: + @@ -72,6 +76,7 @@ $ oc -n hello-openshift create -f hello-openshift-route.yaml ---- .Verification + * Get the status of the route with the following command: + [source,terminal] @@ -100,10 +105,13 @@ spec: name: hello-openshift status: ingress: - - host: hello-openshift. <1> - routerCanonicalHostname: router-sharded. <2> - routerName: sharded <3> + - host: hello-openshift. + routerCanonicalHostname: router-sharded. + routerName: sharded ---- -<1> The hostname the Ingress Controller, or router, uses to expose the route. The value of the `host` field is automatically determined by the Ingress Controller, and uses its domain. In this example, the domain of the Ingress Controller is ``. -<2> The hostname of the Ingress Controller. If the hostname is not set, the route can use a subdomain instead. When you specify a subdomain, you automatically use the domain of the Ingress Controller that exposes the route. When a route is exposed by multiple Ingress Controllers, the route is hosted at multiple URLs. -<3> The name of the Ingress Controller. In this example, the Ingress Controller has the name `sharded`. ++ +where: ++ +`host`:: The hostname the Ingress Controller, or router, uses to expose the route. The value of the `host` field is automatically determined by the Ingress Controller, and uses its domain. In this example, the domain of the Ingress Controller is ``. +``:: The hostname of the Ingress Controller. If the hostname is not set, the route can use a subdomain instead. When you specify a subdomain, you automatically use the domain of the Ingress Controller that exposes the route. When a route is exposed by multiple Ingress Controllers, the route is hosted at multiple URLs. +`routerName`:: The name of the Ingress Controller. In this example, the Ingress Controller has the name `sharded`. diff --git a/modules/nw-ingress-sharding-route-labels.adoc b/modules/nw-ingress-sharding-route-labels.adoc index 8d101f1fbf7e..74f1eab2553f 100644 --- a/modules/nw-ingress-sharding-route-labels.adoc +++ b/modules/nw-ingress-sharding-route-labels.adoc @@ -7,11 +7,10 @@ [id="nw-ingress-sharding-route-labels_{context}"] = Configuring Ingress Controller sharding by using route labels -Ingress Controller sharding by using route labels means that the Ingress -Controller serves any route in any namespace that is selected by the route -selector. +[role="_abstract"] +You can route labels to configure Ingress Controller sharding so that the Ingress Controller serves any route in any namespace that is selected by the route selector. -.Ingress sharding using route labels +.Ingress sharding by using route labels image::nw-sharding-route-labels.png[A diagram showing multiple Ingress Controllers with different route selectors serving any route containing a label that matches a given route selector regardless of the namespace a route belongs to] Ingress Controller sharding is useful when balancing incoming traffic load among a set of Ingress Controllers and when isolating traffic to a specific Ingress Controller. For example, company A goes to one Ingress Controller and company B to another. @@ -28,7 +27,7 @@ metadata: name: sharded namespace: openshift-ingress-operator spec: - domain: <1> + domain: nodePlacement: nodeSelector: matchLabels: @@ -37,7 +36,7 @@ spec: matchLabels: type: sharded ---- -<1> Specify a domain to be used by the Ingress Controller. This domain must be different from the default Ingress Controller domain. +* ``: Specify a domain to be used by the Ingress Controller. This domain must be different from the default Ingress Controller domain. . Apply the Ingress Controller `router-internal.yaml` file: + @@ -49,7 +48,7 @@ spec: The Ingress Controller selects routes in any namespace that have the label `type: sharded`. -. Create a new route using the domain configured in the `router-internal.yaml`: +. Create a new route by using the domain configured in the `router-internal.yaml`: + [source,terminal] ---- diff --git a/modules/nw-ingress-sharding.adoc b/modules/nw-ingress-sharding.adoc index 7308eb2017e5..a6585502131e 100644 --- a/modules/nw-ingress-sharding.adoc +++ b/modules/nw-ingress-sharding.adoc @@ -6,9 +6,10 @@ [id="nw-ingress-sharding_{context}"] = Ingress Controller sharding -You can use Ingress sharding, also known as router sharding, to distribute a set of routes across multiple routers by adding labels to routes, namespaces, or both. The Ingress Controller uses a corresponding set of selectors to admit only the routes that have a specified label. Each Ingress shard comprises the routes that are filtered by using a given selection expression. +[role="_abstract"] +You can use Ingress sharding, also known as _router sharding_, to distribute a set of routes across multiple routers by adding labels to routes, namespaces, or both. The Ingress Controller uses a corresponding set of selectors to admit only the routes that have a specified label. Each Ingress shard comprises the routes that are filtered by using a given selection expression. -As the primary mechanism for traffic to enter the cluster, the demands on the Ingress Controller can be significant. As a cluster administrator, you can shard the routes to: +As the primary mechanism for traffic to enter the cluster, the demands on the Ingress Controller can be significant. As a cluster administrator, you can shard the routes to the following components: * Balance Ingress Controllers, or routers, with several routes to accelerate responses to changes. * Assign certain routes to have different reliability guarantees than other routes. diff --git a/modules/nw-patch-fields-example.adoc b/modules/nw-patch-fields-example.adoc index 86dc28de5ef4..ecdc3bf3294b 100644 --- a/modules/nw-patch-fields-example.adoc +++ b/modules/nw-patch-fields-example.adoc @@ -6,13 +6,17 @@ [id="nw-patch-fields-example_{context}"] = Patching Ingress objects to resolve an ingressWithoutClassName alert -The `ingressClassName` field specifies the name of the `IngressClass` object. You must define the `ingressClassName` field for each `Ingress` object. +[role="_abstract"] +To prevent certain routing issues, you must define define the `ingressClassName` field for each `Ingress` object. -If you have not defined the `ingressClassName` field for an `Ingress` object, you could experience routing issues. After 24 hours, you will receive an `ingressWithoutClassName` alert to remind you to set the `ingressClassName` field. +[NOTE] +==== +Approximately 24 hours after you create an `Ingress` object, the Ingress Controller sends you an `ingressWithoutClassName` alert to remind you to set the `ingressClassName` field. +==== -.Procedure +THe procedure demonstrates patching the `Ingress` objects with a completed `ingressClassName` field to ensure proper routing and functionality. -Patch the `Ingress` objects with a completed `ingressClassName` field to ensure proper routing and functionality. +.Procedure . List all `IngressClass` objects: + @@ -28,11 +32,10 @@ $ oc get ingressclass $ oc get ingress -A ---- -. Patch the `Ingress` object: +. Patch the `Ingress` object by running the following command. This command patches the `Ingress` object to include the desired ingress class name. + [source,terminal] ---- $ oc patch ingress/ --type=merge --patch '{"spec":{"ingressClassName":"openshift-default"}}' ---- -+ -Replace `` with the name of the `Ingress` object. This command patches the `Ingress` object to include the desired ingress class name. \ No newline at end of file +* ``: Replace `` with the name of the `Ingress` object. diff --git a/modules/nw-traditional-sharding.adoc b/modules/nw-traditional-sharding.adoc index 3b4a95f22dc3..9fdab4f042db 100644 --- a/modules/nw-traditional-sharding.adoc +++ b/modules/nw-traditional-sharding.adoc @@ -6,7 +6,8 @@ [id="nw-traditional-sharding_{context}"] = Traditional sharding example -An example of a configured Ingress Controller `finops-router` that has the label selector `spec.namespaceSelector.matchExpressions` with key values set to `finance` and `ops`: +[role="_abstract"] +To understand traditional sharding, you can review the example of a configured Ingress Controller `finops-router` that has the label selector `spec.namespaceSelector.matchExpressions` with key values set to `finance` and `ops`. .Example YAML definition for `finops-router` [source,yaml] diff --git a/modules/nw-using-ingress-and-routes.adoc b/modules/nw-using-ingress-and-routes.adoc index 274eb05b965e..4757cdc76efb 100644 --- a/modules/nw-using-ingress-and-routes.adoc +++ b/modules/nw-using-ingress-and-routes.adoc @@ -6,27 +6,16 @@ [id="nw-using-ingress-and-routes_{context}"] = Using Ingress Controllers and routes -The Ingress Operator manages Ingress Controllers and wildcard DNS. +[role="_abstract"] +You can use the Ingress Controller to allow external access to an {product-title} cluster. The Ingress Operator manages Ingress Controllers and wildcard DNS. -Using an Ingress Controller is the most common way to allow external access to -an {product-title} cluster. +An Ingress Controller is configured to accept external requests and proxy them based on the configured routes. This is limited to HTTP, HTTPS using SNI, and TLS using SNI, which is sufficient for web applications and services that work over TLS with SNI. -An Ingress Controller is configured to accept external requests and proxy them -based on the configured routes. This is limited to HTTP, HTTPS using SNI, and -TLS using SNI, which is sufficient for web applications and services that work -over TLS with SNI. +Work with your administrator to configure an Ingress Controller to accept external requests and proxy them based on the configured routes. -Work with your administrator to configure an Ingress Controller -to accept external requests and proxy them based on the -configured routes. +The administrator can create a wildcard DNS entry and then set up an Ingress Controller. Then, you can work with the edge Ingress Controller without having to contact the administrators. -The administrator can create a wildcard DNS entry and then set up an Ingress -Controller. Then, you can work with the edge Ingress Controller without -having to contact the administrators. +By default, every Ingress Controller in the cluster can admit any route created in any project in the cluster. The Ingress Controller has the following characteristics: -By default, every Ingress Controller in the cluster can admit any route created in any project in the cluster. - -The Ingress Controller: - -* Has two replicas by default, which means it should be running on two worker nodes. +* Has two replicas by default, which means it should be running on two compute nodes. * Can be scaled up to have more replicas on more nodes. diff --git a/modules/restrictions-on-ip-assignment.adoc b/modules/restrictions-on-ip-assignment.adoc index d663dac185b5..f01c5b79b39f 100644 --- a/modules/restrictions-on-ip-assignment.adoc +++ b/modules/restrictions-on-ip-assignment.adoc @@ -2,14 +2,25 @@ // // * networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc -:_mod-docs-content-type: CONCEPT +:_mod-docs-content-type: PROCEDURE [id="restrictions-on-ip-assignment_{context}"] -= Restrictions on the assignment of an external IP address += Applying 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. +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 `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. +.Procedure + +* Configure an IP address policy by specifying Classless Inter-Domain Routing (CIDR) address blocks for the `spec.ExternalIP.policy` parameter in the `policy` object: ++ .Example in JSON form of a `policy` object and its CIDR parameters [source,json] ---- @@ -20,12 +31,3 @@ 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 `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 index 57ec02db3637..6db090206574 100644 --- 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 index 60b2ea8af7cf..1dfa3ba23456 100644 --- 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] @@ -20,7 +20,7 @@ include::modules/nw-externalip-about.adoc[leveloffset=+1] // Configuration for ExternalIP include::modules/configuration-externalip.adoc[leveloffset=+1] -// Restrictions on the assignment of an external IP address +// Applying restrictions on the assignment of an external IP address include::modules/restrictions-on-ip-assignment.adoc[leveloffset=+1] // Example policy objects diff --git a/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-patch-fields.adoc b/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-patch-fields.adoc index 85ee796c608c..eb8bf48c96d5 100644 --- a/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-patch-fields.adoc +++ b/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-patch-fields.adoc @@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[] toc::[] -You can update or modify the following fields of existing `Ingress` objects without recreating the objects or disrupting services to them: +[role="_abstract"] +You can update or modify the following fields of existing `Ingress` objects without recreating the objects or disrupting services to these objects: * Specifications * Host diff --git a/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws.adoc b/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws.adoc index 25fdd801e863..e36f69cf7339 100644 --- a/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws.adoc +++ b/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws.adoc @@ -6,16 +6,17 @@ include::_attributes/common-attributes.adoc[] toc::[] -{product-title} provides methods for communicating from outside the cluster with services running in the cluster. This method uses load balancers on AWS, specifically a Network Load Balancer (NLB) or a Classic Load Balancer (CLB). Both types of load balancers can forward the client's IP address to the node, but a CLB requires proxy protocol support, which {product-title} automatically enables. +[role="_abstract"] +{product-title} provides methods for communicating from outside the cluster with services running in the cluster. This method uses load balancers on {aws-first}, specifically a Network Load Balancer (NLB) or a Classic Load Balancer (CLB). Both types of load balancers can forward the IP address of the client to the node, but a CLB requires proxy protocol support, which {product-title} automatically enables. There are two ways to configure an Ingress Controller to use an NLB: -. By force replacing the Ingress Controller that is currently using a CLB. This deletes the `IngressController` object and an outage will occur while the new DNS records propagate and the NLB is being provisioned. -. By editing an existing Ingress Controller that uses a CLB to use an NLB. This changes the load balancer without having to delete and recreate the `IngressController` object. +. By force replacing the Ingress Controller that is currently using a CLB. This deletes the `IngressController` object and an outage occurs while the new DNS records propagate and the NLB is being provisioned. +. By editing an existing Ingress Controller that uses a CLB to then use an NLB. This changes the load balancer without having to delete and recreate the `IngressController` object. Both methods can be used to switch from an NLB to a CLB. -You can configure these load balancers on a new or existing AWS cluster. +You can configure these load balancers on a new or existing {aws-short} cluster. include::modules/nw-configuring-elb-timeouts-aws-classic.adoc[leveloffset=+1] @@ -33,10 +34,10 @@ include::modules/nw-aws-replacing-clb-with-nlb.adoc[leveloffset=+2] include::modules/nw-aws-nlb-existing-cluster.adoc[leveloffset=+2] -[IMPORTANT] -==== -Before you can configure an Ingress Controller NLB on a new AWS cluster, you must complete the xref:../../../installing/installing_aws/ipi/installing-aws-customizations.adoc#installation-initializing_installing-aws-customizations[Creating the installation configuration file] procedure. -==== +[role="_additional-resources"] +== Additional resources + +* xref:../../../installing/installing_aws/ipi/installing-aws-customizations.adoc#installation-initializing_installing-aws-customizations[Creating the installation configuration file] include::modules/nw-aws-nlb-new-cluster.adoc[leveloffset=+2] @@ -51,5 +52,5 @@ include::modules/nw-ingress-aws-static-eip-nlb-configuration.adoc[leveloffset=+2 == Additional resources * xref:../../../installing/installing_aws/ipi/installing-aws-customizations.adoc#installing-aws-customizations[Installing a cluster on AWS with network customizations]. -* For more information on support for NLBs, see link:https://kubernetes.io/docs/concepts/services-networking/service/#aws-nlb-support[Network Load Balancer support on AWS]. -* For more information on proxy protocol support for CLBs, see link:https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/enable-proxy-protocol.html[Configure proxy protocol support for your Classic Load Balancer] +* link:https://kubernetes.io/docs/concepts/services-networking/service/#aws-nlb-support[Network Load Balancer support on AWS] +* link:https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/enable-proxy-protocol.html[Configure proxy protocol support for your Classic Load Balancer] diff --git a/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc b/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc index 7296ea66695b..7994e3e1fac5 100644 --- a/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc +++ b/networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc @@ -1,26 +1,16 @@ :_mod-docs-content-type: ASSEMBLY [id="configuring-ingress-cluster-traffic-ingress-controller"] -= Configuring ingress cluster traffic using an Ingress Controller += Configuring ingress cluster traffic by using an Ingress Controller include::_attributes/common-attributes.adoc[] :context: configuring-ingress-cluster-traffic-ingress-controller toc::[] -{product-title} provides methods for communicating from outside the cluster with -services running in the cluster. This method uses an Ingress Controller. +[role="_abstract"] +You can use the Ingress Controller to control how external users communicate with services that run inside the cluster. ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/nw-using-ingress-and-routes.adoc[leveloffset=+1] - -[NOTE] -==== -The procedures in this section require prerequisites performed by the cluster -administrator. -==== - -== Prerequisites - -Before starting the following procedures, the administrator must: +Before you begin any of the procedures that are listed in the Configuring ingress cluster traffic by using an Ingress Controller document, ensure that you meet the following prerequisites. A cluster administrator performs these prerequisites: * Set up the external port to the cluster networking environment so that requests can reach the cluster. @@ -28,15 +18,14 @@ can reach the cluster. * Make sure there is at least one user with cluster admin role. To add this role to a user, run the following command: + +[source,terminal] ---- $ oc adm policy add-cluster-role-to-user cluster-admin username ---- -* You have an {product-title} cluster with at least one master and at least one node -and a system outside the cluster that has network access to the cluster. This -procedure assumes that the external system is on the same subnet as the cluster. -The additional networking required for external systems on a different subnet is -out-of-scope for this topic. +* You have an {product-title} cluster with at least one master and at least one node and a system outside the cluster that has network access to the cluster. This procedure assumes that the external system is on the same subnet as the cluster. The additional networking required for external systems on a different subnet is out-of-scope for this topic. + +include::modules/nw-using-ingress-and-routes.adoc[leveloffset=+1] endif::[] // Creating a project and service @@ -73,7 +62,6 @@ include::modules/nw-ingress-sharding-namespace-labels.adoc[leveloffset=+2] // Creating a route for Ingress Controller sharding include::modules/nw-ingress-sharding-route-configuration.adoc[leveloffset=+2] - [id="additional-resources_ingress-sharding"] === Additional resources