Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
OSDOCS-9608: updating component routes with custom domains/certificates
- Loading branch information
1 parent
dac985d
commit 566d5c5
Showing
2 changed files
with
235 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
233 changes: 233 additions & 0 deletions
233
cloud_experts_tutorials/cloud-experts-update-component-routes.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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-<component>.pem` and `cert-<component>.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. |