Customizing the Cloud Pak entry point

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

About this task

The Zen service is installed by the Cloud Pak foundational services along with the Identity Management (IM) service. These services are visible to all clients that want to access them by the Zen “cpd” route.

Note: If the CP4BA deployment uses All Namespaces, both the cpd route and the cp-console route are enabled. To customize the IM (cp-console) route, see Customizing the Cloud Pak Identity Management (IM) service.

The following diagram shows some of the components that are installed in a Cloud Pak for Business Automation deployment like Workflow Authoring, Decision Designer, and Document Processing Designer. A user that wants to open an application must go through the Zen cpd route, which checks the user credentials for the application. By default in a namespace-scoped CP4BA deployment, the IM cp-console route is disabled as shown in the following diagram.

The “cpd” route is created with the naming convention cpd-{namespace}.{router-canonical-name}. By default, the Zen Service generates a self-signed CA certificate.

You can change the default hostname and the certificate for the "cpd" route. Changing certificates is often done to use a certificate that you purchased from a public certificate authority (CA) or signed by your corporate CA.

To change the Platform UI (Zen) hostname and route, use the following steps:

1. Update the hostname of the Platform UI route.
2. Network traffic must be routed to the new hostname on your OCP cluster.
3. Update the TLS certificate of the Platform UI with the new signed certificate.

Updating the hostname and the certificate are independent of each other, and you can skip the steps that are related to the parameters that you do not want to change.

1. If you want to change the hostname, edit the Zen Service custom resource to update the spec.zenCustomRoute.route_host parameter.

   spec:
     zenCustomRoute:
       route_host: <your-custom-route-name>.<apps.domain-name-of-cluster>

   Replace <your-custom-route-name>.<apps.domain-name-of-cluster> with your chosen hostname.

   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.

   Optional: You can also update the hostname in the Zen Service custom resource by running the following command:

   oc patch ZenService iaf-zen-cpdservice --type='json' -p='[{"op": "add", "path": "/spec/zenCustomRoute","value":{"route_host":"<your-custom-host-name>"}}]' -n ${CP4BA_AUTO_NAMESPACE}

   Replace <your-custom-host-name> with your chosen hostname and CP4BA_AUTO_NAMESPACE is the project namespace.

2. To update the certificates, edit the spec.zenCustomRoute.route_secret parameter in the Zen Service custom resource with the name of your secret.

   1. Obtain the necessary certificate files in the proper format and create these files to be used in the secret.

      ca.crt

      The ca.crt contains the intermediate CA signer certificates and the CA root signer certificate. The file must start with the intermediate CA certificates and placed in the order that leads to the root CA.

      tls.crt

      The tls.crt contains the route server certificate.

      tls.key

      The tls.key contains the private key of the route server certificate.

      Each of the certificates and the key must be in an unencrypted PEM format for the file. 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-----

      Hostname verification is checked in many places as part of the TLS handshake. Help ensure that the certificate can pass the verification by having the hostname match a value from the subject CN or Subject Alternative Names (SANs) values.

   2. Create your secret (for example cpd-route-tls-secret) to add your custom certificates to the OCP cluster.

      export NAMESPACE=<cp4ba-project>
      oc -n ${NAMESPACE} create secret generic cpd-route-tls-secret \
      --from-file=tls.crt=tls.crt \
      --from-file=tls.key=tls.key \
      --from-file=ca.crt=ca.crt \
      --dry-run=client -o yaml | oc apply -f -

      Where <cp4ba-project> is the namespace of your foundational services instance, which is usually the same namespace as your CP4BA deployment.

      Note: The key names in the route_secret must use tls.crt, tls.key, and ca.crt. If other names are used, the route values are not applied. Do not name the secret external-tls-secret or custom-tls-secret. When you use custom certificates, you need to manage the lifecycle of the certificates in this secret.
   3. Edit the Zen Service custom resource to update the route_secret parameter with the name of your secret.

      spec
        zenCustomRoute:
          route_reencrypt: true
          route_secret: "cpd-route-tls-secret"

      Optional: You can also update the Zen Service custom resource with the new secret by running the following command:

      oc patch ZenService iaf-zen-cpdservice --type='json' -p='[{"op": "add", "path": "/spec/zenCustomRoute","value":{"route_secret":"cpd-route-tls-secret","route_reencrypt":true}}]' -n ${NAMESPACE}

   If you need to update the certificates after you initially customized the route, create a new route secret with a different name and update the Zen Service custom resource to use this secret. After the update is made, you can delete the old secret.

oc logs deployment/ibm-zen-operator -n namespace