Skip to content

Commit a97af8d

Browse files
bmcelveebmcelvee
authored
Merge pull request #69363 from laubai/osdocs-hkemp-changing-default-domains
OSDOCS#9085: Custom domain docs for managed openshift console oauth and downloads
2 parents 5275330 + d745338 commit a97af8d

File tree

2 files changed

+188
-0
lines changed

2 files changed

+188
-0
lines changed

‎_topic_maps/_topic_map_rosa.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,8 @@ Topics:
116116
File: cloud-experts-external-dns
117117
- Name: Dynamically issuing certificates using the cert-manager Operator on ROSA
118118
File: cloud-experts-dynamic-certificate-custom-domain
119+
- Name: Changing the Console, OAuth, and Downloads domains and TLS certificate
120+
File: cloud-experts-rosa-osd-change-default-domain
119121
- Name: Assigning consistent egress IP for external traffic
120122
File: cloud-experts-consistent-egress-ip
121123
- Name: Getting started with ROSA

‎cloud_experts_tutorials/cloud-experts-rosa-osd-change-default-domain.adoc

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="cloud-experts-changing-domains-and-certificates-on-rosa-and-osd"]
3+
= Tutorial: Changing the Console, OAuth, and Downloads domains and TLS certificate on ROSA and OSD
4+
5+
//Content metadata
6+
//Brought into ROSA product docs 2023-12-14
7+
//---
8+
//date: '2022-12-07'
9+
//title: Changing the Console, OAuth, and Downloads Domain and TLS Certificate on ROSA and OSD
10+
//weight: 1
11+
//tags: ["AWS", "ROSA", "OSD"]
12+
//authors:
13+
// Hector Kemp
14+
//---
15+
16+
//Footnote definitions
17+
:fn-supported-cli: footnote:[The example commands in this guide use the ROSA CLI, but similar commands with the same function are available in the OCM CLI version 0.1.68 and higher for OpenShift Dedicated clusters that run on Google Cloud Platform.]
18+
:fn-supported-versions: footnote:[Modifying these routes on ROSA and OSD 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.]
19+
:fn-term-component-routes: footnote:[We use the term `component routes` to refer to the `OAuth`, `Console`, and `Downloads` routes that are provided when ROSA and OSD are first installed. The ROSA CLI also uses the term `cluster routes` to refer to these resources.]
20+
21+
//Article text
22+
This guide demonstrates how to modify the Console, Downloads, OAuth domain, and TLS certificate keypair on Red Hat Openshift on AWS (ROSA) and Red Hat Openshift Dedicated (OSD) versions 4.14 and above.{fn-supported-versions}
23+
24+
The changes that we make to the component routes{fn-term-component-routes} in this guide are described in greater detail in the following documentation:
25+
26+
* link:https://docs.openshift.com/container-platform/latest/authentication/configuring-internal-oauth.html#customizing-the-oauth-server-url_configuring-internal-oauth[Customizing the internal OAuth server URL]
27+
* link:https://docs.openshift.com/container-platform/latest/web_console/customizing-the-web-console.html#customizing-the-console-route_customizing-web-console[Customizing the console route]
28+
* link:https://docs.openshift.com/container-platform/latest/web_console/customizing-the-web-console.html#customizing-the-download-route_customizing-web-console[Customizing the download route]
29+
30+
== Prerequisites
31+
32+
* ROSA CLI (`rosa`) version 1.2.27 or higher{fn-supported-cli}
33+
* AWS CLI (`aws`)
34+
* OpenShift CLI (`oc`)
35+
* A ROSA or OSD cluster (STS, non-STS, or PrivateLink)
36+
* OpenSSL (for generating the demonstration SSL certificate), which can be downloaded and installed from link:https://www.openssl.org/source/[OpenSSL.org]
37+
* Access to the cluster as a user with the `cluster-admin` role.
38+
39+
== Find the current routes
40+
41+
Before we make any configuration changes, we need to know the current routes in the cluster.
42+
43+
* Verify that you can reach the component routes on their default hostnames.
44+
+
45+
You can find the hostnames by querying the lists of routes in `openshift-console` and `openshift-authentication`.
46+
+
47+
[source,bash]
48+
----
49+
$ oc get routes -n openshift-console
50+
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
51+
console console-openshift-console.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com ... 1 more console https reencrypt/Redirect None
52+
downloads downloads-openshift-console.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com ... 1 more downloads http edge/Redirect None
53+
----
54+
+
55+
[source,bash]
56+
----
57+
$ oc get routes -n openshift-authentication
58+
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
59+
oauth-openshift oauth-openshift.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com ... 1 more oauth-openshift 6443 passthrough/Redirect None
60+
----
61+
+
62+
From these commands you can see that our base hostname is `z9a9.p1.openshiftapps.com`.
63+
64+
* Verify that the default ingress exists, and ensure that the base hostname matches that of the component routes.
65+
+
66+
[source,bash]
67+
----
68+
$ rosa list ingress -c <my-example-cluster-aws>
69+
ID API ENDPOINT PRIVATE
70+
r3l6 https://apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com external true
71+
----
72+
+
73+
Our ingress route shares the base hostname of `z9a9.p1.openshiftapps.com`.
74+
+
75+
Note the ID of the default ingress: `r316`. We will need this to set up new DNS records later.
76+
77+
By running these commands you can see that the default component routes for our cluster are:
78+
79+
* `console-openshift-console.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com` for Console
80+
* `downloads-openshift-console.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com` for Downloads
81+
* `oauth-openshift.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com` for OAuth
82+
83+
We can use the `rosa edit ingress` command to change this base hostname 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 `rosa edit ingress` command:
84+
85+
[source,bash]
86+
----
87+
$ rosa edit ingress -h
88+
Edit a cluster ingress for a cluster. Usage:
89+
rosa edit ingress ID [flags]
90+
[...]
91+
--cluster-routes-hostname string Components route hostname for oauth, console, download.
92+
--cluster-routes-tls-secret-ref string Components route TLS secret reference for oauth, console, download.
93+
----
94+
95+
Note that when we use this command to change the component routes, it will change the base domain for all three routes at the same time.
96+
97+
If we choose a new base domain of `my-new-domain.dev`, our new component routes for our cluster will be:
98+
99+
* `console-openshift-console.my-new-domain.dev` for Console
100+
* `downloads-openshift-console.my-new-domain.dev` for Downloads
101+
* `oauth-openshift.my-new-domain.dev` for OAuth
102+
103+
== Creating a valid TLS certificate for each component route
104+
105+
In this section, we create a self-signed certificate key pair and then trust it to verify that we can access our new component routes using a real web browser. 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 a certificate with similar attributes for your production workloads.
106+
107+
To work correctly, the certificate we create needs the following:
108+
109+
* a Common Name (CN) that matches the **wildcard** DNS of the `--cluster-routes-hostname` parameter
110+
* a Subject Alternative Name (SAN) for each component route that **matches** the routes generated by our new hostname
111+
112+
For a base domain of `my-new-domain.dev`, our certificate's subject (`-subj`) looks like this:
113+
114+
----
115+
/CN=*.my-new-domain.dev
116+
----
117+
118+
We also need a SAN for each of our component routes:
119+
120+
----
121+
subjectAltName = DNS:console-openshift-console.my-new-domain.dev
122+
subjectAltName = DNS:downloads-openshift-console.my-new-domain.dev
123+
subjectAltName = DNS:oauth-openshift.my-new-domain.dev
124+
----
125+
126+
We can generate our certificate by running the following `openssl` command:
127+
128+
[source,bash]
129+
----
130+
$ openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 -keyout key-my-new-domain.pem -out cert-my-new-domain.pem -subj "/CN=*.my-new-domain.dev" -addext "subjectAltName = DNS:console-openshift-console.my-new-domain.dev, DNS:oauth-openshift.my-new-domain.dev, DNS:downloads-openshift-console.my-new-domain.dev"
131+
----
132+
133+
This generates two `.pem` files, `key-my-new-domain.pem` and `cert-my-new-domain.pem`.
134+
135+
== Adding the certificate to the cluster as a secret
136+
137+
. Log in to the cluster as a user with the `cluster-admin` role.
138+
139+
. Generate a TLS secret in the `openshift-config` namespace.
140+
+
141+
This becomes your secret reference when you update the component routes later in this guide.
142+
+
143+
[source,bash]
144+
----
145+
$ oc create secret tls component-tls --cert=cert-my-new-domain.pem --key=key-my-new-domain.pem -n openshift-config
146+
----
147+
148+
== Find the hostname of the load balancer in your cluster
149+
150+
When you create a cluster, ROSA and OSD create a load balancer and generate a hostname for that load balancer. We need to know the load balancer hostname in order to create DNS records for our cluster.
151+
152+
You can find the hostname by running the `oc get svc` command against the `openshift-ingress` namespace. The hostname of the load balancer is the `EXTERNAL-IP` associated with the `router-default` service in the `openshift-ingress` namespace.
153+
154+
[source,bash]
155+
----
156+
$ oc get svc -n openshift-ingress
157+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
158+
router-default LoadBalancer 172.30.237.88 a234gsr3242rsfsfs-1342r624.us-east-1.elb.amazonaws.com 80:31175/TCP,443:31554/TCP 76d
159+
----
160+
161+
In our case, the hostname is `a234gsr3242rsfsfs-1342r624.us-east-1.elb.amazonaws.com`.
162+
163+
Save this value for later, as we will need it to configure DNS records for our new component route hostnames.
164+
165+
== Add component route DNS records to your hosting provider
166+
167+
In your hosting provider, add DNS records that map the `CNAME` of your new component route hostnames to the load balancer hostname we found in the previous step.
168+
169+
//.Need an image for this
170+
//image::[Picture goes here]
171+
172+
== Update the component routes and TLS secret using the ROSA CLI
173+
174+
When your DNS records have been updated, you can use the ROSA CLI to change the component routes.
175+
176+
Use the `rosa edit ingress` command to update your default ingress route with the new base domain and the secret reference associated with it.
177+
178+
[source,bash]
179+
----
180+
$ rosa edit ingress -c <my-example-cluster-aws> r3l6 --cluster-routes-hostname="my-new-domain.dev" --cluster-routes-tls-secret-ref="component-tls"
181+
182+
ID APPLICATION ROUTER PRIVATE DEFAULT [...] LB-TYPE [...] WILDCARD POLICY NAMESPACE OWNERSHIP HOSTNAME TLS SECRET REF
183+
r3l6 https://apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com yes yes [...] nlb [...] WildcardsDisallowed Strict my-new-domain.dev component-tls
184+
----
185+
186+
Add your certificate to the trust store on your local system, then confirm that you can access your components at their new routes using your local web browser.

0 commit comments

Comments
 (0)