Using a custom TLS certificate for HTTPS connections to the platform

IBM Cloud Pak® for Data includes a self-signed TLS certificate that is used to enable HTTPS connections. However, this certificate is untrusted by all HTTPS clients. It is strongly recommended that you replace the self-signed certificate with your own certificate.

What permissions do you need to complete this task?
To complete this task, you must have one of the following roles:
  • Red Hat® OpenShift® Container Platform cluster administrator
  • Red Hat OpenShift Container Platform project administrator on the project where Cloud Pak for Data is installed
When do you need to complete this task.
This task is optional, but strongly recommended. You should complete this task before you give users access to the Cloud Pak for Data platform.

If you installed multiple instances of Cloud Pak for Data on your cluster, complete this task for each instance.

Before you begin

The workstation from which you will run the commands must be set up as a client workstation with the following command-line interfaces:
  • Cloud Pak for Data CLI: cpd-cli
  • OpenShift CLI: oc

For details, see: Setting up a client workstation.

About this task

The files that you must provide depend on the type of route that you want to use for Cloud Pak for Data:

Route type Default certificate Custom TLS certificate and key CA certificate
Passthrough By default, the route uses an IBM self-signed certificate.

However, it is recommended that you replace this certificate with a custom certificate.

 Supported.

If you use a passthrough route, this option is strongly recommended.

The files must be in an unencrypted PEM format.

 Not used.
Re-encrypt (default) By default, the route uses the default certificate that is provided by the Red Hat OpenShift Container Platform ingress controller.
However, it is recommended that you replace this certificate with a custom certificate. For details, see Replacing the default ingress certificate the Red Hat OpenShift Container Platform documentation:
Uses the ingress controller settings by default.
If you want to use custom certificates, you must specify:
  • TLS certificate
  • TLS key
  • CA certificate

The files must be in an unencrypted PEM format.

 Uses the ingress controller settings by default.
If you want to use custom certificates, you must specify:
  • TLS certificate
  • TLS key
  • CA certificate

The files must be in an unencrypted PEM format.
To provide the files to the cpd-cli, you can create a secret that you provide to the cpd-cli
Command to create a secret with a TLS certificate and TLS key

The following example creates a secret called cpd-tls-secret.

You must replace the following variables before you can run the command:

<tls-certificate-file-name>
The name of the TLS certificate file. The example assumes that you are running the command from the directory where the file is located.
<tls-key-file-name>
The name of the TLS key file. The example assumes that you are running the command from the directory where the file is located.
oc create secret generic cpd-tls-secret \
--namespace ${PROJECT_CPD_INSTANCE} \
--from-file=tls.crt=./<tls-certificate-file-name> \
--from-file=tls.key=./<tls-key-file-name>
Command to create a secret with a CA certificate, TLS certificate, and TLS key

The following example creates a secret called cpd-tls-secret.

You must replace the following variables before you can run the command:

<ca-certificate-file-name>
The name of the CA certificate file. The example assumes that you are running the command from the directory where the file is located.
<tls-certificate-file-name>
The name of the TLS certificate file. The example assumes that you are running the command from the directory where the file is located.
<tls-key-file-name>
The name of the TLS key file. The example assumes that you are running the command from the directory where the file is located.
oc create secret generic cpd-tls-secret \
--namespace ${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>

Procedure

  1. Run the cpd-cli manage login-to-ocp command to log in to the cluster as a user with sufficient permissions to complete this task. For example: 
    cpd-cli manage login-to-ocp \
--username=${OCP_USERNAME} \
--password=${OCP_PASSWORD} \
--server=${OCP_URL}
    Tip: The login-to-ocp command takes the same input as the oc login command. Run oc login --help for details.
  2. Run the cpd-cli manage setup-route command.

    The command that you run depends on whether you are using a passthrough route or a re-encrypt route:

    Passthrough route

    You must replace the following variables before you can run the command:

    <certificate-secret-name>
    The name of the secret that contains the TLS certificate and the TLS key.
    cpd-cli manage setup-route \
--cpd_instance_ns=${PROJECT_CPD_INSTANCE} \
--route_type=passthrough \
--route_secret=<certificate-secret-name>
    Re-encrypt route

    You must replace the following variables before you can run the command:

    <certificate-secret-name>
    The name of the secret that contains the CA certificate, the TLS certificate, and the TLS key.
    cpd-cli manage setup-route \
--cpd_instance_ns=${PROJECT_CPD_INSTANCE} \
--route_secret=<certificate-secret-name>
    Tip: If you are unsure whether the route is a passthrough route or a re-encrypt route, run:
    oc get route cpd -n=${PROJECT_CPD_INSTANCE} -o "jsonpath={.spec.tls.termination}"

    The command returns either passthrough or reencrypt.