Custom Cloud Pak Platform UI (Zen) Route and certificates

You can change the Cloud Pak Platform UI (Zen) cpd route hostname and certificates by updating the AutomationUIConfig custom resource.

By default, the Cloud Pak Platform UI is the main entrance to all the Cloud Pak services and capabilities. All the application URLs are hidden behind the Zen front door, which exposes a single hostname.

Note: These instructions are applicable to IBM Cloud Pak foundational services versions 3.23.x and prior. For IBM Cloud Pak foundational services version 4.0.x and later, see your IBM Cloud Pak documentation for instructions on how to add custom routes and certificates.

Before you begin

The IBM Cloud Pak foundational services deploys the Cloud Pak Platform UI and the Identity and Access Management (IAM) service. You can access these services by using the Zen cpd and IAM cp-console routes. For example, see the following IBM Cloud Pak for Business Automation deployment diagram that shows how some installed components are accessed by using the two routes.

Figure 1. IBM Cloud Pak for Business Automation deployment

The IBM Automation Foundation Core AutomationUIConfig creates the Zen cpd route and uses the cpd-{namespace}.{router-canonical-name} naming convention for the route.

By default, the Zen service generates a self-signed CA certificate and leaf certificates by using the IBM Cert Manager service, which automatically mounts and renews these certificates.

For more information about generating a certificate for IAM (cp-console), see Refreshing foundational services internal certificates.
For more information about renewing self-signed certificates for Zen used for IBM Automation Foundation, see Using generated self-signed certificates and secrets.

Hostname changes

If you want to change the hostname, you can update the AutomationUIConfig custom resource (CR).

If you change the hostname to a domain that is not the default Red Hat OpenShift Container Platform domain, then you must make sure that the host can resolve to the Red Hat OpenShift router from inside and outside the OpenShift Container Platform cluster. The cpd route is a pass-through route and the Red Hat OpenShift router needs the Server Name Indication (SNI) header for this type of route. All network devices that are involved in handling the new domain must use the SNI header in the TLS handshake. For more information, see Dynamic-Routes-Guide and solutions.

Certificate changes

For certificate changes, you must configure the following certificates with the Platform UI route.

CA certificate: The ca.crt file contains the root certificate.
Router server and intermediate certificates: The cert.crt file contains the route server certificate and any intermediate CA certificate. The file must start with the route server certificate and have the intermediate CA certificates in the order that leads to the root CA. To return a proper certificate hierarchy during the TLS handshake, make sure to concatenate the server certificate and all its signers in one file. The CN must be equal to the new hostname.
Key: The cert.key file contains the private key of the route server certificate.

The certificate files must be in an unencrypted PEM format. The PEM encoding uses header and footer lines for each certificate and private key.

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

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

Procedure

Follow these steps to use the custom route hostname and certificates.

1. Update the hostname

Before you begin, obtain the new hostname that you would like you use.

To change the hostname, update the route_host parameter in the AutomationUIConfig CR. Replace myhostname.com with your chosen hostname.

oc patch AutomationUIConfig iaf-system --type='json' \
-p '[{"op": "add", "path": "/spec/zenService/zenCustomRoute", \
"value": {"route_host":"myhostname.com"}}]'

The update takes about 15 minutes to complete. You can use watch oc get route cpd to see the status.

2. Update the certificate

Tp update the certificate, re-create the external-tls-secret secret with the default name but with your custom certificates.

Update the AutomationUIConfig CR to specify the path where you want the new secret to be placed. The path is used to mount the secret on to the Platform UI pods. Do not change the external-tls-secret name as your custom certificate also needs to have the same name.
```
 oc patch AutomationUIConfig iaf-system --type='json' -p '[{"op": "add", "path": "/spec/tls/certificateSecret", "value": {"secretName": "external-tls-secret"}}]'
```

Delete the default external-tls-secret secret.

 oc -n <your-foundational-services-namespace> delete secret external-tls-secret

Re-create the default external-tls-secret secret by using your custom ca.crt, cert.crt, and cert.key files that you created earlier.
```
 oc create secret generic 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 -f -
```
Note: You must manage the lifecycle of the custom certificates that you used in the external-tls-secret secret.

3. Restart the Platform UI pods

When you update the AutomationUIConfig CR, the ZenService CR is also updated. The Zen operator then reconciles the ZenService CR.

Check the status of the ZenService CR to verify whether the reconciliation is complete.

oc get zenservice lite-cr -n <your-foundational-services-namespace> -o jsonpath="{.status}"

After the reconciliation is complete, restart the nginx pods.

oc delete pod -l app.kubernetes.io/component=ibm-nginx

4. Verify the updates

Verify whether the cpd route has the new hostname.

oc get route -n <your-foundational-services-namespace> cpd -o jsonpath='{.spec.host}' && echo

Verify that you see the new certificates in your browser when you access the cpd URL.