Modifying Platform UI route with custom hostname and certificates

WebSphere Automation uses the Cloud Pak foundational services Platform UI as an underlying service for its user interface. You can modify the Platform UI route with a custom hostname and certificates by changing the WebSphereAutomation custom resource.

Before you begin

Determine your new hostname or domain
For hostname changes, obtain the new hostname you would like you use. If you modify the domain from the default Red Hat® OpenShift® Container Platform domain, ensure that the new hostname can resolve to the Red Hat OpenShift router from inside and outside the Red Hat OpenShift Container Platform cluster. The Platform UI route is a pass-through route and the Red Hat OpenShift router requires the SNI header for routes of this type. Ensure any network device that is involved in handling the new domain is using the SNI header. This requirement is specific to Red Hat OpenShift. For more information, see Dynamic-Routes-Guide External link icon and How can a user update OpenShift 4 console route External link icon.
Certificate changes
For certificate changes, obtain the necessary certificate files in the proper format. The following files are necessary for the secret that contains the certificates.
  • ca.crt: You must have your full certificate chain if the CA certificate you bring is not self-signed. The full certificate chain includes all the CA certificates that signed each intermediate CA certificate that signed your CA certificate and your root CA. The files must be PEM-encoded files.
  • cert.crt: A Server Certificate (Leaf Certificate). The files must be PEM-encoded files.
  • cert.key: The private key corresponding to the signed certificate. The files must be PEM-encoded files.

Each of the certificates and the key must be in an unencrypted Privacy-Enhanced Mail (PEM) format. The PEM encoding uses header and footer lines like these for each certificate and private key.

-----BEGIN CERTIFICATE-----
(encoded set of characters)
-----END CERTIFICATE-----

-----BEGIN PRIVATE KEY-----
(encoded set of characters)
-----END PRIVATE KEY-----

About this task

Follow these steps to change the Platform UI route's hostname and certificates.

Procedure

  1. Update the hostname.
    Use the following oc command to update the Platform UI hostname. Replace instance_namespace with the name of the WebSphere Automation instance, instance_name with the namespace of the WebSphere Automation instance, and example.com with your custom hostname:
    oc patch websphereautomation instance_name -n instance_namespace -p "{\"spec\": {\"platformUI\": {\"customRoute\": {\"routeHost\": \"example.com\"}}}}" --type=merge
  2. Update the secret with the new certificate details.
    For certificate changes, create a secret that is named wsa-external-tls-secret with your custom certificates. Use the ca.crt, cert.crt, and cert.key files when you supply files to the secret command. Replace instance_namespace with the name of the WebSphere Automation instance.
    oc create secret generic wsa-external-tls-secret --from-file=cert.crt=cert.crt --from-file=cert.key=cert.key --from-file=ca.crt=ca.crt --dry-run=client -o yaml | oc apply -n instance_namespace -f -

    When you use custom certificates, you must manage the lifecycle of the certificates in the secret. When WebSphere Automation detects changes to any of the certificates in wsa-external-tls-secret, the Platform UI is automatically restarted to reflect changes in the modified certificates.

    Note: Starting in version 1.6.3, TLS termination for the Platform UI route is in reencrypt mode instead of passthrough mode. As a result of this change, the ibm-nginx pods are no longer responsible for serving your custom certificates. Instead, the operator automatically reloads your custom certificates into the Red Hat OpenShift route named cpd. No additional configuration is needed.

Results

The Platform UI route is updated with the new hostname. You can see the new certificates in your browser when you access the Automation UI URL.

What to do next

If you have registered servers, you must update their certificates. For more information, see the following links.