Merge pull request #28983 from bmcelvee/OSDOCS-1778

OSDOCS-1778 Document AppsDomain API change and procedure

Author: bmcelvee

modules/nw-ingress-configuring-application-domain.adoc

@@ -0,0 +1,75 @@
+// Module included in the following assemblies:
+//
+// * ingress/configure-ingress-operator.adoc
+//
+
+[id="nw-ingress-configuring-application-domain_{context}"]
+= Configuring application domain for the Ingress Controller Operator on AWS
+
+//OpenShift Dedicated or Amazon RH OpenShift cluster administrator
+
+As a cluster administrator, you can specify an alternative default domain for user-created routes by configuring `appsDomain` field. If you specify an alternative domain, it overrides the default cluster domain for the purpose of determining the default host for a new route.
+
+For example, you can use the DNS domain for your company as the default domain for routes and ingresses for applications running on your cluster.
+
+.Prerequisites
+
+//* You deployed an {OSD} cluster.
+* You deployed an {product-title} cluster on AWS infrastructure.
+* You installed the `oc` command line interface.
+
+.Procedure
+
+. Configure the `appsDomain` field by specifying an alternative default domain for user-created routes.
++
+.. Edit the Ingress Controller Operator:
++
+[source,terminal]
+----
+$ oc edit ingresses.config/cluster -o yaml
+----
++
+.. Edit the YAML file:
++
+.Sample `appsDomain` configuration to `apps.acme.io`
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1
+kind: Ingress
+metadata:
+  name: cluster
+spec:
+  domain: apps.<domain_url>
+  appsDomain: apps.acme.io
+----
++
+. Verify that an existing route contains the new domain name by exposing the route and verifying the route domain change:
+//+
+//.. Access the Ingress Controller Operator YAML file:
+//+
+//[source,terminal]
+//----
+//$ oc get ingresses.config/cluster -o yaml
+//----
++
+[NOTE]
+====
+Wait for the `openshift-apiserver` finish rolling updates before exposing the route.
+====
++
+.. Expose the route:
++
+[source,terminal]
+----
+$ oc expose service hello-openshift
+route.route.openshift.io/hello-openshift exposed
+----
++
+.. Verify route domain change:
++
+[source,terminal]
+----
+$ oc get routes
+NAME              HOST/PORT                                   PATH   SERVICES          PORT       TERMINATION   WILDCARD
+hello-openshift   hello-openshift-my-project.apps.acme.io          hello-openshift   8080-tcp                 None
+----

modules/nw-ingress-controller-configuration-parameters.adoc

@@ -25,6 +25,9 @@ The `domain` value must be unique among all Ingress controllers and cannot be up
 
 If empty, the default value is `ingress.config.openshift.io/cluster` `.spec.domain`.
 
+|`appsDomain`
+|`appsDomain` is an optional domain for AWS infrastructure to use instead of the one specified in the `domain` field when a Route is created without specifying an explicit host. If a value is entered for `appsDomain`, this value is used to generate default host values for the Route. Unlike `domain`, `appsDomain` can be modified after installation. You can use this parameter only if you set up a new Ingress Controller that uses a wildcard certificate.
+
 |`replicas`
 |`replicas` is the desired number of Ingress controller replicas. If not set, the default value is `2`.
 

networking/ingress-operator.adoc

@@ -56,6 +56,8 @@ include::modules/nw-using-ingress-forwarded.adoc[leveloffset=+2]
 
 include::modules/nw-http2-haproxy.adoc[leveloffset=+2]
 
+include::modules/nw-ingress-configuring-application-domain.adoc[leveloffset=+2]
+
 //include::modules/nw-ingress-select-route.adoc[leveloffset=+2]
 
 == Additional resources