From c7996d84cb208fa88d6601a3ee8812b6d645d79f Mon Sep 17 00:00:00 2001 From: michaelryanmcneill Date: Fri, 26 Apr 2024 18:16:50 -0400 Subject: [PATCH] OSDOCS-9608: updating component routes with custom domains/certificates --- _topic_maps/_topic_map_rosa.yml | 2 + ...cloud-experts-update-component-routes.adoc | 233 ++++++++++++++++++ 2 files changed, 235 insertions(+) create mode 100644 cloud_experts_tutorials/cloud-experts-update-component-routes.adoc diff --git a/_topic_maps/_topic_map_rosa.yml b/_topic_maps/_topic_map_rosa.yml index ba1a18a22d69..a005f329f618 100644 --- a/_topic_maps/_topic_map_rosa.yml +++ b/_topic_maps/_topic_map_rosa.yml @@ -133,6 +133,8 @@ Topics: File: cloud-experts-dynamic-certificate-custom-domain - Name: Assigning consistent egress IP for external traffic File: cloud-experts-consistent-egress-ip +- Name: Updating component routes with custom domains and TLS certificates + File: cloud-experts-update-component-routes - Name: Getting started with ROSA Dir: cloud-experts-getting-started Distros: openshift-rosa diff --git a/cloud_experts_tutorials/cloud-experts-update-component-routes.adoc b/cloud_experts_tutorials/cloud-experts-update-component-routes.adoc new file mode 100644 index 000000000000..1355c779796f --- /dev/null +++ b/cloud_experts_tutorials/cloud-experts-update-component-routes.adoc @@ -0,0 +1,233 @@ +:_mod-docs-content-type: ASSEMBLY +[id="cloud-experts-update-component-routes"] += Tutorial: Updating component routes with custom domains and TLS certificates +include::_attributes/attributes-openshift-dedicated.adoc[] +:context: cloud-experts-update-component-routes + +toc::[] + +:fn-supported-versions: footnote:[Modifying these routes on {product-title} 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 link:https://access.redhat.com/support/cases/new[opening a support case].] +: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 are first installed.] + +//Article text +This guide demonstrates how to modify the hostname and TLS certificate of the Web console, OAuth server, and Downloads component routes in {product-title} (ROSA) version 4.14 and above.{fn-supported-versions} + +The changes that we make to the component routes{fn-term-component-routes} in this guide are described in greater detail in the customizing the link:https://docs.openshift.com/container-platform/latest/authentication/configuring-internal-oauth.html#customizing-the-oauth-server-url_configuring-internal-oauth[internal OAuth server URL], link:https://docs.openshift.com/container-platform/latest/web_console/customizing-the-web-console.html#customizing-the-console-route_customizing-web-console[console route], and link:https://docs.openshift.com/container-platform/latest/web_console/customizing-the-web-console.html#customizing-the-download-route_customizing-web-console[download route] OpenShift Container Platform documentation. + +[id="prerequisites_{context}"] +== Prerequisites +* ROSA CLI (`rosa`) version 1.2.37 or higher +* AWS CLI (`aws`) +* A ROSA cluster +* 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) + +[id="environment-setup_{context}"] +== Setting up your environment + +. Configure an environment variable for your cluster name: ++ +[NOTE] +==== +You must be logged in as an administrator. +==== ++ +[source,terminal] +---- +$ export CLUSTER_NAME=$(oc get infrastructure cluster -o=jsonpath="{.status.infrastructureName}" | sed 's/-[a-z0-9]\{5\}$//') +---- + +. Ensure all fields output correctly before moving to the next section: ++ +[source,terminal] +---- +$ echo "Cluster: ${CLUSTER_NAME}" +---- ++ +.Example output ++ +[source,text] +---- +Cluster: my-rosa-cluster +---- + +[id="find-current-routes_{context}"] +== 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 `openshift-console` and `openshift-authentication`. ++ +[source,bash] +---- +$ oc get routes -n openshift-console +$ oc get routes -n openshift-authentication +---- ++ +.Example output ++ +[source,text] +---- +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 these commands you can see that our base hostname is `z9a9.p1.openshiftapps.com`. ++ +. Get the ID of the default ingress by running the following command ++ +[source,bash] +---- +$ export INGRESS_ID=$(rosa list ingress -c ${CLUSTER_NAME} -o json | jq -r '.[] | select(.default == true) | .id') +---- ++ +. Ensure all fields output correctly before moving to the next section: ++ +[source,terminal] +---- +$ echo "Ingress ID: ${INGRESS_ID}" +---- ++ +.Example output ++ +[source,text] +---- +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: ++ +[source,bash] +---- +$ 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:...' +---- ++ +Note that when we use this command to change the component routes, we will need to change the component route of all three services. + +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 + +[id="create-tls-certificate-for-routes_{context}"] +== 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. 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 ++ +[source,bash] +---- +$ 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" +---- ++ +This generates three pairs of `.pem` files, `key-.pem` and `cert-.pem`. + +[id="add-certificate-as-cluster-secret_{context}"] +== Add the certificates to the cluster as a secret + +. Create three TLS secrets in the `openshift-config` namespace. ++ +These become your secret reference when you update the component routes later in this guide. ++ +[source,bash] +---- +$ 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 +---- + +[id="find-lb-hostname_{context}"] +== 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. + +[source,bash] +---- +$ 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. + +[id="add-routes-to-dns_{context}"] +== 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. + +//.Need an image for this +//image::[Picture goes here] + +[id="update-routes-tls-using-rosa-cli_{context}"] +== 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. ++ +[source,bash] +---- +$ rosa 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' +---- ++ +. Run the `rosa list ingress` command to verify that your changes were successfully made: ++ +[source,bash] +---- +$ rosa list ingress -c ${CLUSTER_NAME} -ojson | jq ".[] | select(.id == \"${INGRESS_ID}\") | .component_routes" +---- ++ +.Example output ++ +[source,text] +---- +{ + "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. \ No newline at end of file