Chapter 16. Tutorial: Updating component routes with custom domains and TLS certificates This guide demonstrates how to modify the hostname and TLS certificate of the Web console, OAuth server, and Downloads component routes in Red Hat OpenShift Service on AWS (ROSA) version 4.14 and above. [1] The changes that we make to the component routes [2] in this guide are described in greater detail in the customizing the internal OAuth server URL , console route , and download route OpenShift Container Platform documentation. 16.1. Prerequisites ROSA CLI ( rosa ) version 1.2.37 or higher AWS CLI ( aws ) A ROSA Classic cluster version 4.14 or higher Note ROSA with HCP is not supported at this time. OpenShift CLI ( oc ) jq CLI Access to the cluster as a user with the cluster-admin role. OpenSSL (for generating the demonstration SSL/TLS certificates) 16.2. Setting up your environment Log in to your cluster using an account with cluster-admin privileges. Configure an environment variable for your cluster name: USD export CLUSTER_NAME=USD(oc get infrastructure cluster -o=jsonpath="{.status.infrastructureName}" | sed 's/-[a-z0-9]\{5\}USD//') Ensure all fields output correctly before moving to the section: USD echo "Cluster: USD{CLUSTER_NAME}" Example output Cluster: my-rosa-cluster 16.3. Find the current routes Verify that you can reach the component routes on their default hostnames. You can find the hostnames by querying the lists of routes in the openshift-console and openshift-authentication projects. USD oc get routes -n openshift-console USD oc get routes -n openshift-authentication Example output 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 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 this output you can see that our base hostname is z9a9.p1.openshiftapps.com . Get the ID of the default ingress by running the following command: USD export INGRESS_ID=USD(rosa list ingress -c USD{CLUSTER_NAME} -o json | jq -r '.[] | select(.default == true) | .id') Ensure all fields output correctly before moving to the section: USD echo "Ingress ID: USD{INGRESS_ID}" Example output Ingress ID: r3l6 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 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 rosa edit ingress command: USD rosa edit ingress -h Edit a cluster ingress for a cluster. Usage: rosa edit ingress ID [flags] [...] --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:...' For this example, we'll use the following custom component routes: console.my-new-domain.dev for Console downloads.my-new-domain.dev for Downloads oauth.my-new-domain.dev for OAuth 16.4. Create a valid TLS certificate for each component route 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. Warning 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. Important 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. 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: Example USD 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" USD 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" USD 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" This generates three pairs of .pem files, key-<component>.pem and cert-<component>.pem . 16.5. Add the certificates to the cluster as secrets Create three TLS secrets in the openshift-config namespace. These become your secret reference when you update the component routes later in this guide. USD oc create secret tls console-tls --cert=cert-console.pem --key=key-console.pem -n openshift-config USD oc create secret tls downloads-tls --cert=cert-downloads.pem --key=key-downloads.pem -n openshift-config USD oc create secret tls oauth-tls --cert=cert-oauth.pem --key=key-oauth.pem -n openshift-config 16.6. Find the hostname of the load balancer in your cluster When you create a cluster, the service creates a load balancer and generates 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. USD 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. 16.7. 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 step. 16.8. 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, taking care to update the hostnames for each component route. USD rosa edit ingress -c USD{CLUSTER_NAME} USD{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' Note 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: USD rosa edit ingress -c USD{CLUSTER_NAME} USD{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' Run the rosa list ingress command to verify that your changes were successfully made: USD rosa list ingress -c USD{CLUSTER_NAME} -ojson | jq ".[] | select(.id == \"USD{INGRESS_ID}\") | .component_routes" Example output { "console": { "kind": "ComponentRoute", "hostname": "console.my-new-domain.dev", "tls_secret_ref": "console-tls" }, "downloads": { "kind": "ComponentRoute", "hostname": "downloads.my-new-domain.dev", "tls_secret_ref": "downloads-tls" }, "oauth": { "kind": "ComponentRoute", "hostname": "oauth.my-new-domain.dev", "tls_secret_ref": "oauth-tls" } } 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. 16.9. Reset the component routes to the default using the ROSA CLI If you want to reset the component routes to the default configuration, run the following rosa edit ingress command: USD rosa edit ingress -c USD{CLUSTER_NAME} USD{INGRESS_ID} --component-routes 'console: hostname="";tlsSecretRef="",downloads: hostname="";tlsSecretRef="", oauth: hostname="";tlsSecretRef=""' [1] Modifying these routes on Red Hat OpenShift Service on AWS ROSA 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 opening a support case . [2] We use the term "component routes" to refer to the OAuth, Console, and Downloads routes that are provided when ROSA are first installed.

Commands:
export CLUSTER_NAME=USD(oc get infrastructure cluster -o=jsonpath="{.status.infrastructureName}" | sed 's/-[a-z0-9]\{5\}USD//')
echo "Cluster: USD{CLUSTER_NAME}"
Cluster: my-rosa-cluster
oc get routes -n openshift-console oc get routes -n openshift-authentication
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 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
export INGRESS_ID=USD(rosa list ingress -c USD{CLUSTER_NAME} -o json | jq -r '.[] | select(.default == true) | .id')
echo "Ingress ID: USD{INGRESS_ID}"
Ingress ID: r3l6
rosa edit ingress -h Edit a cluster ingress for a cluster. Usage: rosa edit ingress ID [flags] [...] --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:...'
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" 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" 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"
oc create secret tls console-tls --cert=cert-console.pem --key=key-console.pem -n openshift-config oc create secret tls downloads-tls --cert=cert-downloads.pem --key=key-downloads.pem -n openshift-config oc create secret tls oauth-tls --cert=cert-oauth.pem --key=key-oauth.pem -n openshift-config
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
rosa edit ingress -c USD{CLUSTER_NAME} USD{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'
rosa edit ingress -c USD{CLUSTER_NAME} USD{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'
rosa list ingress -c USD{CLUSTER_NAME} -ojson | jq ".[] | select(.id == \"USD{INGRESS_ID}\") | .component_routes"
{ "console": { "kind": "ComponentRoute", "hostname": "console.my-new-domain.dev", "tls_secret_ref": "console-tls" }, "downloads": { "kind": "ComponentRoute", "hostname": "downloads.my-new-domain.dev", "tls_secret_ref": "downloads-tls" }, "oauth": { "kind": "ComponentRoute", "hostname": "oauth.my-new-domain.dev", "tls_secret_ref": "oauth-tls" } }
rosa edit ingress -c USD{CLUSTER_NAME} USD{INGRESS_ID} --component-routes 'console: hostname="";tlsSecretRef="",downloads: hostname="";tlsSecretRef="", oauth: hostname="";tlsSecretRef=""'