Customizing the Cloud Pak entry point

By default, the Cloud Pak Platform UI (Zen) 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.

Before you begin

The Cloud Pak Platform UI is created by the IBM Cloud Pak foundational services along with the Identity and Access Management (IAM) service. These services are visible to all clients that want to access them by the Zen “cpd” and IAM “cp-console” routes. The following diagram shows some of the components that are installed in a Cloud Pak for Business Automation deployment, and how they are accessed.

The “cpd” route is created by the IBM Automation Foundation Core AutomationUIConfig, and uses the naming convention cpd-{namespace}.{router-canonical-name}.

By default, the Zen Service generates a self-signed CA certificate and the leaf certificates by using the IBM Cert Manager. The certificates generated this way are automatically mounted and renewed by IBM Cert Manager without the need for any user interaction. For more information about renewing self-signed certificates, see Using generated self-signed certificates and secrets.

To change the hostname to a customer accessible URL (for which you purchased TLS certificates), you must update the "iaf-system" AutomationUIConfig custom resource. For more information about the IAM route, see Customizing the Cloud Pak identity and access (IAM) service.

If you change the hostname to a domain that is not the default OpenShift Container Platform (OCP) domain, then you must make sure that the host can resolve to the OpenShift router from inside and outside the OCP cluster. The cpd route is a pass-through route and the 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 certificate changes, you must configure the following certificates with the Platform UI route. The certificate files must be in an unencrypted PEM format.

CA certificate and Key. The ca.crt file contains the CA root certificate.
Server Certificate (Signed by CA) and Key. The cert.crt file contains the route server certificate and any intermediate CA certificates. 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.
Client Certificate (Signed by CA) and Key. The cert.key file contains the private key of the route server certificate.

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-----

About this task

To successfully customize the Platform UI hostname and the route, you must take the following steps:

Update the Platform UI route's hostname. This modification implies extra changes in the system that are also applied by the Zen Service operator.
Network traffic must be routed to the new hostname on your OCP cluster. The IAM registration is updated with the new hostname.
Update the Platform UI's TLS certificate to include the new hostname. The TLS certificate that is presented by the Platform UI's front-door must be valid for the new hostname.
As part of the TLS handshake, clients verify the server's hostname by comparing the hostname that they connect to with the list of hostnames in the server's certificate under Subject Alternative Names (SANs). The certificate that is created at installation time is issued for the default hostname and is not signed by a trusted CA. When you customize the Platform UI hostname, you probably want to use a certificate that you purchased from a public certificate authority (CA). The certificate can also be signed by your corporate CA and is already trusted by your clients.

Updating the hostname and the certificate are independent of each other. If you do not need to add a custom certificate, do not create the secret and you can skip step 2. If you want to create and update the secret, but not add a custom hostname, skip step 1. For more information, see Custom Cloud Pak Platform UI (Zen) Route and certificates.

Procedure

If you want to change the hostname, update the AutomationUIConfig.
The AutomationUIConfig creates a Zen Service and keeps updating this service to match its expected configuration.

To change the hostname to a hostname in your existing domain, edit the AutomationUIConfig custom resource to update the route_host parameter by running the following command:
```
$ oc patch AutomationUIConfig iaf-system --type='json' \
-p '[{"op": "add", "path": "/spec/zenService/zenCustomRoute", \
"value": {"route_host":"cpd.myhost.com"}}]'
```
Replace cpd.myhost.com with your chosen hostname.

The change can take 15 minutes to apply throughout all layers. You can use “watch oc get route cpd“ to see the effect. You can also follow the logs of the Zen Service operator to view the progress:
```
$ oc logs deployment/ibm-zen-operator -n ibm-common-services
```
If you want to change the route certificates, update the AutomationUIConfig with your custom certificate.
1. Update the AutomationUIConfig resource with the name of the expected secret.
```
$ oc patch AutomationUIConfig iaf-system --type='json' \
 -p '[{"op": "add", "path": "/spec/tls/certificateSecret", \
 "value": {"secretName": "external-tls-secret"}}]
```
  The external-tls-secret OCP secret is mounted into the Platform UI front-door pods.
2. Delete the default secret that is created.
```
$ oc -n ibm-common-services delete secret external-tls-secret
```
3. Create your secret with the default name (external-tls-secret) to add your custom certificates to the OCP cluster. Use the three types of files that are described in the Before you begin section when you supply the files to the secret command.
```
$ oc -n ibm-common-services 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: When you use custom certificates, you need to manage the lifecycle of the certificates in this secret.
Restart the Platform UI pods to pick up the modified contents of the secret.
Use the oc get zenservice lite-cr -n ibm-common-services -o jsonpath="{.status}" command to get the CR and view the status. When it is time to restart the nginx pods, you can use the following command:
```
$ oc delete pod -l app.kubernetes.io/component=ibm-nginx
```

Results

After you completed these steps, you see the cpd route that is updated with the new hostname. You can also see the new certificates in your browser when you access the cpd URL.

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.