Changing the Console, OAuth, and Downloads domains and TLS certificate on ROSA and OSD

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.¹

The changes that we make to the component routes² in this guide are described in greater detail in the following documentation:

• Customizing the internal OAuth server URL
• Customizing the console route
• Customizing the download route

Prerequisites

• ROSA CLI (rosa) version 1.2.27 or higher³
• AWS CLI (aws)
• OpenShift CLI (oc)
• A ROSA or OSD cluster (STS, non-STS, or PrivateLink)
• OpenSSL (for generating the demonstration SSL certificate), which can be downloaded and installed from OpenSSL.org
• Access to the cluster as a user with the cluster-admin role.

Find the current routes

Before we make any configuration changes, we need to know the current routes in the cluster.

• Verify that you can reach the component routes on their default hostnames.

  You can find the hostnames by querying the lists of routes in openshift-console and openshift-authentication.

  $ oc get routes -n openshift-console
  NAME        HOST/PORT                                                                          PATH       SERVICES    PORT    TERMINATION          WILDCARD
  console     console-openshift-console.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com    ... 1 more  console    https   reencrypt/Redirect   None
  downloads   downloads-openshift-console.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com  ... 1 more  downloads  http    edge/Redirect        None
  

  $ oc get routes -n openshift-authentication
  NAME              HOST/PORT                                                             PATH        SERVICES          PORT   TERMINATION            WILDCARD
  oauth-openshift   oauth-openshift.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com ... 1 more  oauth-openshift   6443   passthrough/Redirect   None
  

  From these commands you can see that our base hostname is z9a9.p1.openshiftapps.com.

• Verify that the default ingress exists, and ensure that the base hostname matches that of the component routes.

  $ rosa list ingress -c <my-example-cluster-aws>
  ID    API ENDPOINT                                                   PRIVATE
  r3l6  https://apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com  external  true
  

  Our ingress route shares the base hostname of z9a9.p1.openshiftapps.com.

  Note the ID of the default ingress: r316. We will need this to set up new DNS records later.

By running these commands you can see that the default component routes for our cluster are:

• console-openshift-console.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com for Console
• downloads-openshift-console.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com for Downloads
• oauth-openshift.apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com for OAuth

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:

$ rosa edit ingress -h
Edit a cluster ingress for a cluster. Usage:
  rosa edit ingress ID [flags]
  [...]
  --cluster-routes-hostname string         Components route hostname for oauth, console, download.
  --cluster-routes-tls-secret-ref string   Components route TLS secret reference for oauth, console, download.

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.

If we choose a new base domain of my-new-domain.dev, our new component routes for our cluster will be:

• console-openshift-console.my-new-domain.dev for Console
• downloads-openshift-console.my-new-domain.dev for Downloads
• oauth-openshift.my-new-domain.dev for OAuth

Create a valid TLS certificate for each component route

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.

To work correctly, the certificate we create needs the following:

• a Common Name (CN) that matches the wildcard DNS of the --cluster-routes-hostname parameter
• a Subject Alternative Name (SAN) for each component route that matches the routes generated by our new hostname

For a base domain of my-new-domain.dev, our certificate's subject (-subj) looks like this:

/CN=*.my-new-domain.dev

We also need a SAN for each of our component routes:

subjectAltName = DNS:console-openshift-console.my-new-domain.dev
subjectAltName = DNS:downloads-openshift-console.my-new-domain.dev
subjectAltName = DNS:oauth-openshift.my-new-domain.dev

We can generate our certificate by running the following openssl command:

$ 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"

This generates two .pem files, key-my-new-domain.pem and cert-my-new-domain.pem.

Add the certificate to the cluster as a secret

1. Log in to the cluster as a user with the cluster-admin role.

2. Generate a TLS secret in the openshift-config namespace.

   This becomes your secret reference when you update the component routes later in this guide.

   $ oc create secret tls component-tls --cert=cert-my-new-domain.pem --key=key-my-new-domain.pem -n openshift-config
   

Find the hostname of the load balancer in your cluster

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.

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.

$ oc get svc -n openshift-ingress
NAME            TYPE          CLUSTER-IP     EXTERNAL-IP                                             PORT(S)                     AGE
router-default  LoadBalancer  172.30.237.88  a234gsr3242rsfsfs-1342r624.us-east-1.elb.amazonaws.com  80:31175/TCP,443:31554/TCP  76d

In our case, the hostname is a234gsr3242rsfsfs-1342r624.us-east-1.elb.amazonaws.com.

Save this value for later, as we will need it to configure DNS records for our new component route hostnames.

Add component route DNS records to your hosting provider

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.

== Update the component routes and TLS secret using the ROSA CLI

When your DNS records have been updated, you can use the ROSA CLI to change the component routes.

Use the rosa edit ingress command to update your default ingress route with the new base domain and the secret reference associated with it.

$ rosa edit ingress -c <my-example-cluster-aws> r3l6 --cluster-routes-hostname="my-new-domain.dev" --cluster-routes-tls-secret-ref="component-tls"

ID    APPLICATION ROUTER                                             PRIVATE  DEFAULT  [...]  LB-TYPE  [...]  WILDCARD POLICY      NAMESPACE OWNERSHIP  HOSTNAME           TLS SECRET REF
r3l6  https://apps.my-example-cluster-aws.z9a9.p1.openshiftapps.com  yes      yes      [...]  nlb      [...]  WildcardsDisallowed  Strict               my-new-domain.dev  component-tls

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.