Skip to content

Commit 6a4638f

Browse files
bmcelveebmcelvee
authored
Merge pull request #93363 from mletalie/OSDOCS-12969
[Osdocs 12969]Document steps for configuring default ingress-controller in OSD-GCP to reach an openshift-console exposed on a custom domain
2 parents 850cb4a + 98548c3 commit 6a4638f

File tree

7 files changed

+283
-5
lines changed

7 files changed

+283
-5
lines changed

‎_topic_maps/_topic_map_osd.yml

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -85,11 +85,15 @@ Topics:
8585
- Name: Admission plugins
8686
File: admission-plug-ins
8787
---
88-
#Name: Tutorials
89-
#Dir: cloud_experts_tutorials
90-
#Distros: openshift-dedicated
91-
#Topics:
92-
#---
88+
Name: Tutorials
89+
Dir: cloud_experts_osd_tutorials
90+
Distros: openshift-dedicated
91+
Topics:
92+
- Name: Tutorials overview
93+
File: osd_index
94+
- Name: Updating component routes with custom domains and TLS certificates
95+
File: cloud-experts-osd-update-component-routes
96+
---
9397
Name: Red Hat OpenShift Cluster Manager
9498
Dir: ocm
9599
Distros: openshift-dedicated

‎cloud_experts_osd_tutorials/_attributes

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../_attributes/

‎cloud_experts_osd_tutorials/cloud-experts-osd-update-component-routes.adoc

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="cloud-experts-osd-update-component-routes"]
3+
= Tutorial: Updating component routes with custom domains and TLS certificates
4+
include::_attributes/attributes-openshift-dedicated.adoc[]
5+
:context: cloud-experts-osd-update-component-routes
6+
7+
toc::[]
8+
9+
:fn-supported-versions: footnote:[Modifying these routes on {product-title} OCM versions prior to 4.14 is not typically supported. However, if you have a cluster using version 4.13, you can request for Red Hat Support to enable support for this feature on your version 4.13 cluster by link:https://access.redhat.com/support/cases/new[opening a support case].]
10+
:fn-term-component-routes: footnote:[We use the term "component routes" to refer to the OAuth, Console, and Downloads routes that are provided when OCM are first installed.]
11+
12+
//Article text
13+
This guide demonstrates how to modify the hostname and TLS certificate of the Web console, OAuth server, and Downloads component routes in {product-title} on {GCP} version 4.14 and above.{fn-supported-versions}
14+
15+
The changes that we make to the component routes{fn-term-component-routes} in this guide are described in greater detail in the link:https://docs.openshift.com/container-platform/latest/authentication/configuring-internal-oauth.html#customizing-the-oauth-server-url_configuring-internal-oauth[Customing the internal OAuth server URL], link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/web_console/customizing-web-console#customizing-the-console-route_customizing-web-console[Customing the console route], and link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/web_console/customizing-web-console#customizing-the-download-route_customizing-web-console[Customing the download route] OpenShift Container Platform documentation.
16+
17+
[id="prerequisites_{context}"]
18+
== Prerequisites
19+
* OCM CLI (`ocm`) version 1.0.5 or higher
20+
* gcloud CLI (`gcloud`)
21+
* An {product-title} on {GCP} cluster version 4.14 or higher
22+
// +
23+
// [NOTE]
24+
// ====
25+
// ROSA with HCP is not supported at this time.
26+
// ====
27+
// +
28+
* OpenShift CLI (`oc`)
29+
* `jq` CLI
30+
* Access to the cluster as a user with the `cluster-admin` role.
31+
* OpenSSL (for generating the demonstration SSL/TLS certificates)
32+
33+
[id="environment-setup_{context}"]
34+
== Setting up your environment
35+
36+
. Log in to your cluster using an account with `cluster-admin` privileges.
37+
+
38+
. Configure an environment variable for your cluster name:
39+
+
40+
[source,terminal]
41+
----
42+
$ export CLUSTER_NAME=$(oc get infrastructure cluster -o=jsonpath="{.status.infrastructureName}" | sed 's/-[a-z0-9]\{5\}$//')
43+
----
44+
45+
. Ensure all fields output correctly before moving to the next section:
46+
+
47+
[source,terminal]
48+
----
49+
$ echo "Cluster: ${CLUSTER_NAME}"
50+
----
51+
+
52+
.Example output
53+
+
54+
[source,text]
55+
----
56+
Cluster: my-osd-cluster
57+
----
58+
59+
[id="find-current-component-routes_{context}"]
60+
== Find the current routes
61+
62+
. Verify that you can reach the component routes on their default hostnames.
63+
+
64+
You can find the hostnames by querying the lists of routes in the `openshift-console` and `openshift-authentication` projects.
65+
+
66+
[source,bash]
67+
----
68+
$ oc get routes -n openshift-console
69+
$ oc get routes -n openshift-authentication
70+
----
71+
+
72+
.Example output
73+
+
74+
[source,text]
75+
----
76+
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
77+
console console-openshift-console.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com ... 1 more console https reencrypt/Redirect None
78+
downloads downloads-openshift-console.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com ... 1 more downloads http edge/Redirect None
79+
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
80+
oauth-openshift oauth-openshift.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com ... 1 more oauth-openshift 6443 passthrough/Redirect None
81+
----
82+
+
83+
From this output you can see that our base hostname is `z9a9.p2.openshiftapps.com`.
84+
+
85+
. Get the ID of the default ingress by running the following command:
86+
+
87+
[source,bash]
88+
----
89+
$ export INGRESS_ID=$(ocm list ingress -c ${CLUSTER_NAME} -o json | jq -r '.[] | select(.default == true) | .id')
90+
----
91+
+
92+
. Ensure all fields output correctly before moving to the next section:
93+
+
94+
[source,terminal]
95+
----
96+
$ echo "Ingress ID: ${INGRESS_ID}"
97+
----
98+
+
99+
.Example output
100+
+
101+
[source,text]
102+
----
103+
Ingress ID: r3l6
104+
----
105+
+
106+
By running these commands you can see that the default component routes for our cluster are:
107+
108+
* `console-openshift-console.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com` for Console
109+
* `downloads-openshift-console.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com` for Downloads
110+
* `oauth-openshift.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com` for OAuth
111+
112+
We can use the `ocm edit ingress` command to change the hostname of each service and add a TLS certificate for all of our component routes. The relevant parameters are shown in this excerpt of the command-line help for the `ocm edit ingress` command:
113+
114+
[source,bash]
115+
----
116+
$ ocm edit ingress -h
117+
Edit a cluster ingress for a cluster. Usage:
118+
ocm edit ingress ID [flags]
119+
[...]
120+
--component-routes string Component routes settings. Available keys [oauth, console, downloads]. For each key a pair of hostname and tlsSecretRef is expected to be supplied. Format should be a comma separate list 'oauth: hostname=example-hostname;tlsSecretRef=example-secret-ref,downloads:...'
121+
----
122+
123+
For this example, we'll use the following custom component routes:
124+
125+
* `console.my-new-domain.dev` for Console
126+
* `downloads.my-new-domain.dev` for Downloads
127+
* `oauth.my-new-domain.dev` for OAuth
128+
129+
[id="create-tls-certificates_{context}"]
130+
== Creating a valid TLS certificate for each component route
131+
132+
In this section, we create three separate self-signed certificate key pairs and then trust them to verify that we can access our new component routes using a real web browser.
133+
134+
[WARNING]
135+
====
136+
This is for demonstration purposes only, and is not recommended as a solution for production workloads. Consult your certificate authority to understand how to create certificates with similar attributes for your production workloads.
137+
====
138+
139+
[IMPORTANT]
140+
====
141+
To prevent issues with HTTP/2 connection coalescing, you must use a separate individual certificate for each endpoint. Using a wildcard or SAN certificate is not supported.
142+
====
143+
144+
* Generate a certificate for each component route, taking care to set our certificate's subject (`-subj`) to the custom domain of the component route we want to use:
145+
+
146+
.Example
147+
+
148+
[source,bash]
149+
----
150+
$ openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 -keyout key-console.pem -out cert-console.pem -subj "/CN=console.my-new-domain.dev"
151+
$ openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 -keyout key-downloads.pem -out cert-downloads.pem -subj "/CN=downloads.my-new-domain.dev"
152+
$ openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 -keyout key-oauth.pem -out cert-oauth.pem -subj "/CN=oauth.my-new-domain.dev"
153+
----
154+
+
155+
This generates three pairs of `.pem` files, `key-<component>.pem` and `cert-<component>.pem`.
156+
157+
[id="add-certificates-as-secrets_{context}"]
158+
== Adding the certificates to the cluster as secrets
159+
160+
* Create three TLS secrets in the `openshift-config` namespace.
161+
+
162+
These become your secret reference when you update the component routes later in this guide.
163+
+
164+
[source,bash]
165+
----
166+
$ oc create secret tls console-tls --cert=cert-console.pem --key=key-console.pem -n openshift-config
167+
$ oc create secret tls downloads-tls --cert=cert-downloads.pem --key=key-downloads.pem -n openshift-config
168+
$ oc create secret tls oauth-tls --cert=cert-oauth.pem --key=key-oauth.pem -n openshift-config
169+
----
170+
171+
[id="find-lb-hostname_{context}"]
172+
== Finding the load balancer IP of the load balancer in your cluster
173+
174+
When you create a cluster, the service creates a load balancer and generates a load balancer IP for that load balancer. We need to know the load balancer IP in order to create DNS records for our cluster.
175+
176+
You can find the load balancer IP by running the `oc get svc` command against the `openshift-ingress` namespace. The load balancer IP of the load balancer is the `EXTERNAL-IP` associated with the `router-default` service in the `openshift-ingress` namespace.
177+
178+
[source,bash]
179+
----
180+
$ oc get svc -n openshift-ingress
181+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
182+
router-default LoadBalancer 172.30.237.88 34.85.169.230 80:31175/TCP,443:31554/TCP 76d
183+
----
184+
185+
In our case, the load balancer IP is `34.85.169.230`.
186+
187+
Save this value for later, as we will need it to configure DNS records for our new component route hostnames.
188+
189+
[id="add-component-routes-to-dns_{context}"]
190+
== Adding component route DNS records to your hosting provider
191+
192+
Create an A record in your DNS settings, pointing the domain to the IP address of the router-default’s load balancer.
193+
194+
//.Need an image for this
195+
//image::[Picture goes here]
196+
197+
[id="update-component-routes-tls-using-ocm-cli_{context}"]
198+
== Updating the component routes and TLS secret using the OCM CLI
199+
200+
When your DNS records have been updated, you can use the OCM CLI to change the component routes.
201+
202+
. Use the `ocm edit ingress` command to update your default ingress route with the new base domain and the secret reference associated with it, taking care to update the hostnames for each component route.
203+
+
204+
[source,bash]
205+
----
206+
$ ocm edit ingress -c ${CLUSTER_NAME} ${INGRESS_ID} --component-routes 'console: hostname=console.my-new-domain.dev;tlsSecretRef=console-tls,downloads: hostname=downloads.my-new-domain.dev;tlsSecretRef=downloads-tls,oauth: hostname=oauth.my-new-domain.dev;tlsSecretRef=oauth-tls'
207+
----
208+
+
209+
[NOTE]
210+
====
211+
You can also edit only a subset of the component routes by leaving the component routes you do not want to change set to an empty string. For example, if you only want to change the Console and OAuth server hostnames and TLS certificates, you would run the following command:
212+
[source,bash]
213+
----
214+
$ ocm edit ingress -c ${CLUSTER_NAME} ${INGRESS_ID} --component-routes 'console: hostname=console.my-new-domain.dev;tlsSecretRef=console-tls,downloads: hostname="";tlsSecretRef="", oauth: hostname=oauth.my-new-domain.dev;tlsSecretRef=oauth-tls'
215+
----
216+
====
217+
+
218+
. Run the `ocm list ingress` command to verify that your changes were successfully made:
219+
+
220+
[source,bash]
221+
----
222+
$ ocm list ingress -c ${CLUSTER_NAME} -ojson | jq ".[] | select(.id == \"${INGRESS_ID}\") | .component_routes"
223+
----
224+
+
225+
.Example output
226+
+
227+
[source,text]
228+
----
229+
{
230+
"console": {
231+
"kind": "ComponentRoute",
232+
"hostname": "console.my-new-domain.dev",
233+
"tls_secret_ref": "console-tls"
234+
},
235+
"downloads": {
236+
"kind": "ComponentRoute",
237+
"hostname": "downloads.my-new-domain.dev",
238+
"tls_secret_ref": "downloads-tls"
239+
},
240+
"oauth": {
241+
"kind": "ComponentRoute",
242+
"hostname": "oauth.my-new-domain.dev",
243+
"tls_secret_ref": "oauth-tls"
244+
}
245+
}
246+
----
247+
+
248+
. Add your certificate to the truststore on your local system, then confirm that you can access your components at their new routes using your local web browser.
249+
250+
[id="reset-component-routes-to-default_{context}"]
251+
== Resetting the component routes to the default using the OCM CLI
252+
253+
If you want to reset the component routes to the default configuration, run the following `ocm edit ingress` command:
254+
255+
[source,bash]
256+
----
257+
$ ocm edit ingress -c ${CLUSTER_NAME} ${INGRESS_ID} --component-routes 'console: hostname="";tlsSecretRef="",downloads: hostname="";tlsSecretRef="", oauth: hostname="";tlsSecretRef=""'
258+
----

‎cloud_experts_osd_tutorials/images

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../images/

‎cloud_experts_osd_tutorials/modules

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../modules

‎cloud_experts_osd_tutorials/osd_index.adoc

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="osd-tutorials-overview"]
3+
= Tutorials overview
4+
include::_attributes/attributes-openshift-dedicated.adoc[]
5+
:context: tutorials-overview
6+
7+
Use the step-by-step tutorials from Red{nbsp}Hat experts to get the most out of your Managed OpenShift cluster.
8+
9+
[IMPORTANT]
10+
====
11+
This content is authored by Red Hat experts but has not yet been tested on every supported configuration.
12+
====

‎cloud_experts_osd_tutorials/snippets

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../snippets/

0 commit comments

Comments
 (0)