Using custom hostnames and certificates for the Platform UI

If you want to use custom certificates for the Platform UI, complete the following steps to refresh the certificates by using the Platform UI custom resource.

A cluster administrator must refresh the certificates. For more information, see Roles and permissions.

Expired certificates can be diagnosed in either of the following ways:

  • When you open the Platform UI, use your browser tools to inspect the certificate expiration date.

  • Network Authentication Required is present in the widgets on the Platform UI home page.

Custom certificates

  1. To use custom certificates or refresh those certificates, create a secret in the namespace where the Platform UI is installed. A cluster administrator needs to create the secret. The secret must contain:

  • The server certificate

  • The CA certificate

  • The server private key

    The keys within the secret are tls.crt, ca.crt, and tls.key. You can customize the secret by specifying the keys in the next step.

  1. After the secret is created, add the following YAML to the Platform UI custom resource. For secretName, enter the name of the secret. If you don't want to use the default keys from the previous step, create custom keys by specifying them here.

spec:
  tls:
    secretName: ""
    serverCertificate: "" # optional - defaults to tls.crt
    caCertificate: "" # optional -  defaults to ca.crt
    key: "" # optional - defaults to tls.key

  1. Save the Platform UI custom resource and wait until the Platform UI status changes to Ready. Refresh the Platform UI home page and confirm that the certificates are updated.

  2. To configure the Cloud Pak foundational services certificates, follow the steps for "Update the hostname and certificates for IBM Cloud Pak® foundational services" in Using custom hostnames and certificates.

Custom hostname

To use a custom hostname, an administrator needs to add the following YAML to the Platform UI custom resource. For uiHostname, enter a hostname.
Note: You can begin the hostname with https://.
spec:
  uiHostname: ""

After the spec.uiHostname value is applied, save the Platform UI custom resource and wait until the Platform UI returns a status of Ready. You can now access the Platform UI on the new hostname.

Reverting custom certificates for the Platform UI

Attention: When you use this procedure, the Platform UI is unavailable until the procedure is completed. This should be a short period of time.
export PLATFORM_UI_NAMESPACE=<namespace-where-platform-ui-is-installed>
export PLATFORM_UI_NAME=<name-of-platform-ui-instance>

  1. Delete spec.tls from the Platform UI custom resource. Wait until the Platform UI returns a status of Ready, then proceed with the next step.

    oc patch platformnavigator ${PLATFORM_UI_NAME} -n ${PLATFORM_UI_NAMESPACE} --type='json' --patch '[{ "op": "remove", "path": "/spec/tls" }]'

  2. Delete the external-tls-secret secret.

      oc delete secret external-tls-secret -n ${PLATFORM_UI_NAMESPACE}

  3. Restart the ibm-nginx pods:

    oc delete pod -l component=ibm-nginx -n ${PLATFORM_UI_NAMESPACE}

Reverting the custom hostname for the Platform UI

Attention: When you use this procedure, the Platform UI becomes unavailable until the procedure is completed. This should be a short period of time.
export PLATFORM_UI_NAMESPACE=<namespace-where-platform-ui-instance-is-installed>
export PLATFORM_UI_NAME=<name-of-platform-ui-instance>

  1. Delete spec.uiHostname from the Platform UI custom resource. Wait until the Platform UI returns a status of Ready.

    oc patch platformnavigator ${PLATFORM_UI_NAME} -n ${PLATFORM_UI_NAMESPACE} --type='json' --patch '[{ "op": "remove", "path": "/spec/uiHostname" }]'

  2. Delete the Zen client:

    oc delete client zenclient-${PLATFORM_UI_NAME} -n ${PLATFORM_UI_NAMESPACE}

  3. Delete the job iam-config-job:

    oc delete job iam-config-job -n ${PLATFORM_UI_NAMESPACE}

  4. Delete the pod that was created from iam-config-job, if it still exists:

     oc delete -l component=iam-config-job -n ${PLATFORM_UI_NAMESPACE}

  5. Trigger a reconcile of the ZenService resource by patching it:

      oc patch iaf-zen-cpdservice -n ${PLATFORM_UI_NAMESPACE} --type=merge --patch='{"spec": {"refreshflag": "abc"}}'

    The Platform UI instance status changes to Pending.

When the status of the Platform UI instance changes to Ready, the previous URL (before you configured a custom hostname) should be usable again.