From 476a6633a06e9ba262d8ff3c1b046bd58645539b Mon Sep 17 00:00:00 2001 From: bmcelvee Date: Wed, 1 Dec 2021 14:04:13 -0500 Subject: [PATCH] OSDOCS-1768: document mutating .spec.endpointPublishingStrategy --- _topic_maps/_topic_map.yml | 3 ++ ...s-controller-configuration-parameters.adoc | 13 +++-- ...roller-endpoint-publishing-strategies.adoc | 2 +- modules/nw-ingress-default-internal.adoc | 2 +- modules/nw-ingress-setting-internal-lb.adoc | 2 +- .../nw-ingresscontroller-change-external.adoc | 48 +++++++++++++++++++ .../nw-ingresscontroller-change-internal.adoc | 39 +++++++++++++++ networking/ingress-operator.adoc | 2 - ...roller-endpoint-publishing-strategies.adoc | 18 +++++++ 9 files changed, 120 insertions(+), 9 deletions(-) create mode 100644 modules/nw-ingresscontroller-change-external.adoc create mode 100644 modules/nw-ingresscontroller-change-internal.adoc create mode 100644 networking/nw-ingress-controller-endpoint-publishing-strategies.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index b8f280f757..2564d42f70 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -896,6 +896,9 @@ Topics: - Name: Understanding the Ingress Operator File: ingress-operator Distros: openshift-enterprise,openshift-origin +- Name: Configuring the Ingress Controller endpoint publishing strategy + File: nw-ingress-controller-endpoint-publishing-strategies + Distros: openshift-enterprise,openshift-origin - Name: Verifying connectivity to an endpoint File: verifying-connectivity-endpoint - Name: Configuring the node port service range diff --git a/modules/nw-ingress-controller-configuration-parameters.adoc b/modules/nw-ingress-controller-configuration-parameters.adoc index 9973340223..90d7ee03f9 100644 --- a/modules/nw-ingress-controller-configuration-parameters.adoc +++ b/modules/nw-ingress-controller-configuration-parameters.adoc @@ -36,13 +36,18 @@ If empty, the default value is `ingress.config.openshift.io/cluster` `.spec.doma If not set, the default value is based on `infrastructure.config.openshift.io/cluster` `.status.platform`: -* AWS: `LoadBalancerService` (with external scope) -* Azure: `LoadBalancerService` (with external scope) -* GCP: `LoadBalancerService` (with external scope) +* AWS: `LoadBalancerService` (with External scope) +* Azure: `LoadBalancerService` (with External scope) +* GCP: `LoadBalancerService` (with External scope) * Bare metal: `NodePortService` * Other: `HostNetwork` -For most platforms, the `endpointPublishingStrategy` value cannot be updated. However, on GCP, you can configure the `loadbalancer.providerParameters.gcp.clientAccess` subfield. +For most platforms, the `endpointPublishingStrategy` value can be updated. On GCP, you can configure the the following `endpointPublishingStrategy` fields: + +* `loadBalancer.scope` +* `loadbalancer.providerParameters.gcp.clientAccess` +* `hostNetwork.protocol` +* `nodePort.protocol` |`defaultCertificate` |The `defaultCertificate` value is a reference to a secret that contains the default certificate that is served by the Ingress Controller. When Routes do not specify their own certificate, `defaultCertificate` is used. diff --git a/modules/nw-ingress-controller-endpoint-publishing-strategies.adoc b/modules/nw-ingress-controller-endpoint-publishing-strategies.adoc index 31dc3b3363..5beba88b23 100644 --- a/modules/nw-ingress-controller-endpoint-publishing-strategies.adoc +++ b/modules/nw-ingress-controller-endpoint-publishing-strategies.adoc @@ -3,7 +3,7 @@ // * ingress/configure-ingress-operator.adoc [id="nw-ingress-controller-endpoint-publishing-strategies_{context}"] -= Ingress controller endpoint publishing strategy += Ingress Controller endpoint publishing strategy *`NodePortService` endpoint publishing strategy* diff --git a/modules/nw-ingress-default-internal.adoc b/modules/nw-ingress-default-internal.adoc index 9472591d6a..63e8c4e844 100644 --- a/modules/nw-ingress-default-internal.adoc +++ b/modules/nw-ingress-default-internal.adoc @@ -16,7 +16,7 @@ If you do not, all of your nodes will lose egress connectivity to the internet. [IMPORTANT] ==== -If you want to change the `scope` for an `IngressController` object, you must delete and then recreate that `IngressController` object. You cannot change the `.spec.endpointPublishingStrategy.loadBalancer.scope` parameter after the custom resource (CR) is created. +If you want to change the `scope` for an `IngressController`, you can change the `.spec.endpointPublishingStrategy.loadBalancer.scope` parameter after the custom resource (CR) is created. ==== .Prerequisites diff --git a/modules/nw-ingress-setting-internal-lb.adoc b/modules/nw-ingress-setting-internal-lb.adoc index 6d7563f737..ff7ae5e19b 100644 --- a/modules/nw-ingress-setting-internal-lb.adoc +++ b/modules/nw-ingress-setting-internal-lb.adoc @@ -17,7 +17,7 @@ If you do not, all of your nodes will lose egress connectivity to the internet. [IMPORTANT] ==== -If you want to change the `scope` for an `IngressController` object, you must delete and then recreate that `IngressController` object. You cannot change the `.spec.endpointPublishingStrategy.loadBalancer.scope` parameter after the custom resource (CR) is created. +If you want to change the `scope` for an `IngressController`, you can change the `.spec.endpointPublishingStrategy.loadBalancer.scope` parameter after the custom resource (CR) is created. ==== .Diagram of LoadBalancer diff --git a/modules/nw-ingresscontroller-change-external.adoc b/modules/nw-ingresscontroller-change-external.adoc new file mode 100644 index 0000000000..04cd2752b7 --- /dev/null +++ b/modules/nw-ingresscontroller-change-external.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * networking/ingress-operator.adoc + +[id="nw-ingresscontroller-change-external_{context}"] += Configuring the Ingress Controller endpoint publishing scope to External + +When a cluster administrator installs a new cluster without specifying that the cluster is private, the default Ingress Controller is created with a `scope` set to `External`. + +The Ingress Controller's scope can be configured to be `Internal` during installation or after, and cluster administrators can change an `Internal` Ingress Controller to `External`. + +[IMPORTANT] +==== +On some platforms, it is necessary to delete and recreate the service. + +Changing the scope can cause disruption to Ingress traffic, potentially for several minutes. This applies to platforms where it is necessary to delete and recreate the service, because the procedure can cause {product-title} to deprovision the existing service load balancer, provision a new one, and update DNS. +==== + +.Prerequisites + +* You installed the `oc` CLI. + +.Procedure + +* To change an `Internal` scoped Ingress Controller to `External`, enter the following command: ++ +[source,terminal] +---- +$ oc -n openshift-ingress-operator patch ingresscontrollers/private --type=merge --patch='{"spec":{"endpointPublishingStrategy":{"type":"LoadBalancerService","loadBalancer":{"scope":"External"}}}}' +---- ++ +.Verification ++ +* To check the status of the Ingress Controller, enter the following command: ++ +[source,terminal] +---- +$ oc -n openshift-ingress-operator get ingresscontrollers/default -o yaml +---- ++ +** The `Progressing` status condition indicates whether you must take further action. For example, the status condition can indicate that you need to delete the service by entering the following command: ++ +[source,terminal] +---- +$ oc -n openshift-ingress delete services/router-default +---- ++ +If you delete the service, the Ingress Operator recreates it as `External`. diff --git a/modules/nw-ingresscontroller-change-internal.adoc b/modules/nw-ingresscontroller-change-internal.adoc new file mode 100644 index 0000000000..6f1e97c956 --- /dev/null +++ b/modules/nw-ingresscontroller-change-internal.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * networking/ingress-operator.adoc + +[id="nw-ingresscontroller-change-internal_{context}"] += Configuring the Ingress Controller endpoint publishing scope to Internal + +When a cluster administrator installs a new cluster without specifying that the cluster is private, the default Ingress Controller is created with a `scope` set to `External`. Cluster administrators can change an `External` scoped Ingress Controller to `Internal`. + +.Prerequisites + +* You installed the `oc` CLI. + +.Procedure + +* To change an `External` scoped Ingress Controller to `Internal`, enter the following command: ++ +[source,terminal] +---- +$ oc -n openshift-ingress-operator patch ingresscontrollers/default --type=merge --patch='{"spec":{"endpointPublishingStrategy":{"type":"LoadBalancerService","loadBalancer":{"scope":"Internal"}}}}' +---- ++ +.Verification ++ +* To check the status of the Ingress Controller, enter the following command: ++ +[source,terminal] +---- +$ oc -n openshift-ingress-operator get ingresscontrollers/default -o yaml +---- ++ +** The `Progressing` status condition indicates whether you must take further action. For example, the status condition can indicate that you need to delete the service by entering the following command: ++ +[source,terminal] +---- +$ oc -n openshift-ingress delete services/router-default +---- ++ +If you delete the service, the Ingress Operator recreates it as `Internal`. diff --git a/networking/ingress-operator.adoc b/networking/ingress-operator.adoc index c069ecd926..7a3c9a0b20 100644 --- a/networking/ingress-operator.adoc +++ b/networking/ingress-operator.adoc @@ -24,8 +24,6 @@ include::modules/tls-profiles-ingress-configuring.adoc[leveloffset=+3] include::modules/nw-mutual-tls-auth.adoc[leveloffset=+3] -include::modules/nw-ingress-controller-endpoint-publishing-strategies.adoc[leveloffset=+2] - include::modules/nw-ingress-view.adoc[leveloffset=+1] include::modules/nw-ingress-operator-status.adoc[leveloffset=+1] diff --git a/networking/nw-ingress-controller-endpoint-publishing-strategies.adoc b/networking/nw-ingress-controller-endpoint-publishing-strategies.adoc new file mode 100644 index 0000000000..7ca732fd3d --- /dev/null +++ b/networking/nw-ingress-controller-endpoint-publishing-strategies.adoc @@ -0,0 +1,18 @@ +[id="nw-ingress-controller-endpoint-publishing-strategies"] += Configuring the Ingress Controller endpoint publishing strategy +include::modules/common-attributes.adoc[] +:context: nw-ingress-controller-endpoint-publishing-strategies + +toc::[] + +include::modules/nw-ingress-controller-endpoint-publishing-strategies.adoc[leveloffset=+1] + +include::modules/nw-ingresscontroller-change-internal.adoc[leveloffset=+2] + +include::modules/nw-ingresscontroller-change-external.adoc[leveloffset=+2] + + +[id="additional-resources_nw-ingress-controller-endpoint-publishing-strategies"] +== Additional resources + +* For more information, see xref:../networking/ingress-operator.adoc#nw-ingress-controller-configuration-parameters_configuring-ingress[Ingress Controller configuration parameters].