Providing certificates for external routes

The Cloud Pak components create routes to allow clients outside the OpenShift cluster to interact with user interfaces and APIs over HTTPS. By default, these endpoints are secured with certificates that are signed by the root CA certificate of the Cloud Pak. For production environments, it is likely that you want to use your own certificates that are trusted by your clients. In this case, concatenate all certificates of the certificate chain (the custom route certificate and its signers) in a single certificate (.crt) file.

About this task

OpenShift clusters have a default router that listens on all hostnames of a network subdomain. Typically *.apps appears in the external address, for example *.apps.example.com. The Cloud Pak operator creates routes with hostnames that are in the subdomain by using the pattern <component>-<namespace>.<router-canonical-name>. The <component> name is an abbreviation of the service name, for example bas for Business Automation Studio or ums-teams for UMS Teams. For more information about OpenShift routes, see Secured routes.

Clients connecting to an endpoint need the certificate that is issued for this route, and the complete list of signer certificates that are used to sign it.

A shared suffix means that a single HTTPS wildcard certificate can be used to secure all of these routes. The subject alternative name (SAN) in the certificate must include the hostname suffix.

If you want to customize the hostname suffix, you must specify a value for the shared_configuration.sc_deployment_hostname_suffix parameter. Again, the shared suffix is used by all the routes that are created by the Cloud Pak deployment.

The value of the sc_deployment_hostname_suffix parameter must follow a precise pattern that matches {unique-identifier}.{router-canoncial-name}.

Unique-identifier: A string that is unique in the cluster and can help users recognize the system. It must not exceed 32 characters.

Router-canonical-name

The DNS suffix that resolves to your OpenShift router. You can use the following command to query the exact value:

oc get route console -n openshift-console -o yaml | grep routerCanonicalHostname

The following custom resource excerpt sets the hostname suffix for all routes as sales.apps.myocpcluster.com.

shared_configuration: 
   sc_deployment_hostname_suffix: sales.apps.myocpcluster.com

All of the resulting routes include the component name and the hostname suffix. For example, the route for Business Automation Studio would be https://bas-sales.apps.myocpcluster.com.

The SAN in the wildcard certificate for the example routes might be DNS:*.apps.myocpcluster.com.

Note: For many of the Cloud Pak components, you can overwrite the hostname and certificate configuration. For example, to fine-tune User Management Services, you can specify a shared hostname suffix and individual certificates for each of the routes that are created.

ums_configuration:
    hostname:
    ## optional: create routes for backwards compatibility
    backwards_compatibility_routes:
    ## optional for secure communication with UMS
    external_tls_secret_name:
    ## optional for secure communication with UMS and not necessary if the signer certificates are included with the route certificate
    external_tls_ca_secret_name:
    ## optional for secure communication with UMS
    external_tls_teams_secret_name:
    ## optional for secure communication with UMS
    external_tls_scim_secret_name:
    ## optional for secure communication with UMS
    external_tls_sso_secret_name:

For more information, see UMS parameters.

Procedure

Optional: Concatenate multiple certificates into the signed certificate file.

The following command puts three certificate files into a single file.

cat server.crt intermediary.crt root.crt > tls.crt

The tls.crt file contains all three signed certificates. The following example shows how the certificates are saved in the file.

-----BEGIN CERTIFICATE-----
MIIGxTCCBa2gAwIBAgIQBsfsHm+sdGCWtBjm2GJ5azANBgkqhkiG9w0BAQsFADBN
...
Hnm1QervpJroUVjgCAGnTAcRGs6XDuypQKznlnroQpbbWD0J2dz3dSMSJX2PuLMv
pC5QC+eRr9qc
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIGxTCCBa2gAwIBAgIQBsfsHm+sdGCWtBjm2GJ5azANBgkqhkiG9w0BAQsFADBN
...

ZXquzPbsVNypZlQwDEeLJO1QbZcAdwAiRUUHWVUkVpY/oS/x922G4CMmY63AS39d
xoNcbuIPAgAAAXQsQ7RuAAAEAwBIMEYCIQDLwhUk2FPJhSjFz8O/ufO46OdkKsTJ
w2UIHxBlcePdxAIhAM6/ZBftoapGV7k+bzDgBaC4Lc9mTLpoRd1TI1prlm1LAHYA
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E
aWdpQ2VydCBTSEEyIFNlY3VyZSBTZXJ2ZXIgQ0EwHhcNMjAwODI2MDAwMDAwWhcN
MjIwODMxMTIwMDAwWjCBgjELMAkGA1UEBhMCVVMxETAPBgNVBAgTCE5ldyBZb3Jr
...
pC5QC+eRr9qc
-----END CERTIFICATE-----

Create a secret that contains the certificate and private key of your wildcard certificate.
The following command creates a SSL/TLS secret that is named cp4a-wildcard from a signed certificate (tls.crt) file and a private key (tls.key) file that matches the certificate.
```
oc create secret tls cp4a-wildcard --cert tls.crt --key tls.key
```
Set the value of the shared_configuration.external_tls_certificate_secret parameter to the name of the secret that contains your wildcard certificate.
The following example shows that the external TLS certificate secret is set to the cp4a-wildcard secret.
```
shared_configuration:
   external_tls_certificate_secret: cp4a-wildcard
```

What to do next

When your certificates expire, you must take the following actions to renew the secrets:

Update or re-create the secret with the updated certificate.
Restart the corresponding pods that are associated with the secret.