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.
![IBM Cloud Pak for Business Automation deployment](../images/diag_zen_route.png)
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 theexternal-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 customca.crt
,cert.crt
, andcert.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.