Customizing the Platform UI (Zen) route

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.

The Zen route can be configured to be either reencrypt or passthrough. Customization depends heavily on which route type is chosen. See the customization instructions in the following sections based on the route type.

Reencrypt

When the Zen route is set to reencrypt, a TLS connection that is established from a client terminates at the OpenShift 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 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. The following diagram depicts the incoming traffic flow when route_secret is set properly with all necessary values present.

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 ${PROJECT_CPD_INSTANCE}
--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.

For examples:

Create a reencrypt route with a custom hostname.

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

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

Passthrough

The following parameters show what must be set in the ZenService CR to configure a passthrough 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.

spec:
  zenDefaultIngressReencrypt: false
  zenCustomRoute:
     route_host: <hostname> # OPTIONAL
     route_reencrypt: false

When the Zen route is set to passthrough, the Certificate presented to clients come from a secret named external-tls-secret, which is a hardcoded secret name that is known to the ibm-nginx pods.

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

zenDefaultIngressReencrypt: If present, this value must be set to false.
route_host: This value must reflect the external domain that a user uses to interact with the cluster. The domain that is specified here must match the domain that is presented by the Certificate in the cert.crt value of external-tls-secret.
route_reencrypt: Set to false for passthrough.

external-tls-secret

cert.crt: The value of the Certificate, including the cert chain to the root CA.

Note: if the product-configmap contains a URL_PREFIX key, the value must match the domain that is protected by this Certificate.
cert.key: The key that signed the Certificate.

Example create external-tls-secret command:

oc create secret generic external-tls-secret --n ${PROJECT_CPD_INSTANCE}
--from-file=cert.crt=./<ca-certificate-file-name>
--from-file=cert.key=./<tls-certificate-file-name>

Rotating the passthrough Certificate

To rotate the Certificate used in a passthrough route, you must manually update the external-tls-secret. Then restart the ibm-nginx pods by running the following command:

oc delete pods -l=component=ibm-nginx

For examples:

Create a passthrough route with the custom hostname cloudpak.mycompany.com (where cloudpak.mycompany.com should be the domain that is protected by the cert.crt inside external-tls-secret).

Note: When configuring for a passthrough route you must also set another spec value that is named, zenDefaultIngressReencrypt to false.

spec:
  zenDefaultIngressReencrypt: false
  zenCustomRoute:
     route_host: cloudpak.mycompany.com
     route_reencrypt: false