Customizing the Platform UI (Zen) Route

Overview

The ZenService CR spec contains a few parameters that control the Zen route. This document describes what those parameters are and how to set them. At any time before or after installation, you can modify the ZenService CR to trigger a Zen operator reconcile, so that the route can be changed even after installation.

Reencrypt

When the Zen route is set to reencrypt, a TLS connection that is established from a client terminates at the Red Hat® OpenShift® Container Platform router. A second TLS connection is established from the router to the ibm-nginx pods. It is this second hop that requires packets to be “reencrypted”, which is where this routing type gets its name.

The following parameters show what must be set in the ZenService custom resource (CR) to configure a reencrypt route. After changing the values in the ZenService CR, in order for them to take effect, a full Zen operator reconcile will take place. To know whether the reconcile is complete, check the Status → Progress field in the ZenService CR object. The Status → Progress value will show as 100% after reconcile is complete.

zenDefaultIngressReencrypt: true
zenCustomRoute:
  route_host: <hostname> # OPTIONAL
  route_reencrypt: true
  route_secret: anything-but-external-tls-secret

The ZenService CR parameters relevant to a reencrypt connection are defined as follows:

  • zenDefaultIngressReencrypt: If present, this value must be set to true.
  • route_host: This value must reflect the external domain that a user uses to interact with the cluster. The domain specified here must match the domain that is presented by the Certificate in the tls.crt value of route_secret.
  • route_reencrypt: Set to true for reencrypt.
  • route_secret : This new value of route_secret, should indicate the name of a Kubernetes Secret that will hold the tls.crt, tls.key, and ca.crt values necessary for customizing the certificate that is provided by a reencrypt route. route_secret is ONLY valid for a reencrypt route type.

Important: Key names for route_secret must use tls.crt, tls.key, and ca.crt. If any other names are used (for example, cert.crt, cert.key), the route does not apply the values. If any of the three values of tls.crt, tls.key or ca.crt are missing, the ibm-zen-operator ignores the secret, use the default ingress-controller certificate, and issue a WARNING.

Example create secret command:

oc create secret generic cpd-tls-secret --n <aiops_project>
--from-file=ca.crt=./<ca-certificate-file-name>
--from-file=tls.crt=./<tls-certificate-file-name>
--from-file=tls.key=./<tls-key-file-name>

Rotating the Reencrypt Certificate

To rotate the certificate that is used in a reencrypt route, the easiest way to force a reconcile of the Zen operator to accept the new Certificate is to create a new route_secret and update that in the ZenService CR. The updated ZenService CR triggers a Zen operator reconcile, which updates the route.

If the same secret is reused after the data values have been updated, there would be no noticeable change to the ZenService CR spec, which means that the Zen operator will not know to reconcile. If the same secret is being used, the Zen operator can still be triggered to reconcile by making changes to the ZenService CR for reconciliation.

Example YAML:

1. Create a reecrypt route with a custom hostname

spec:
zenCustomRoute:
  route_host: cloudpak.mycompany.com
  route_reencrypt: true
  route_secret: cpd-tls-secret

2. Create a reencrypt route with a custom hostname but accept the default Ingress Controller certificate

Create a reencrypt route with a custom hostname, but accepting the default Ingress Controller certificate (that is, no custom route Certificate provided). This will only work if the Ingress Controller certificate has already been setup to protect the “cloudpak.mycompany.com” domain.

spec:
zenCustomRoute:
  route_host: cloudpak.mycompany.com
  route_reencrypt: true