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 (default) Supported.

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 PEM-encoded files.

 Not used.
Re-encrypt Not supported. Required.

The files must be PEM-encoded files.

 Required.

The file must be a PEM-encoded file.
You can provide the files in one of two ways:
  • You can place the files in the cpd-cli-workspace/olm-utils-workspace/work directory on the client workstation and specify the names when you run the cpd-cli manage setup-route command.
  • You can create a secret that you provide to the cpd-cli.
    To create a secret, run the appropriate command for your environment:
    Command to create a secret with a TLS certificate and TLS key

    The following example creates a secret called cpd-tsl-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 \
--n ${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-tsl-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 \
--n ${PROJECT_CPD_INSTANCE} \
--from-file=ca.cert=./<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 how you provide the files and whether you are using a passthrough route or a re-encrypt route:

    Passthrough route using files in the work directory

    The following example assumes that you are using the default cpd route.

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

    <TLS-certificate-name>
    The name of the TLS certificate.
    <TLS-private-key-name>
    The name of the private TLS key.
    cpd-cli manage setup-route \
--cpd_instance_ns=${PROJECT_CPD_INSTANCE} \
--route_name=cpd \
--route_type=passthrough \
--tls_cert_file=<TLS-certificate-name> \
--tls_key_file=<TLS-private-key-name>
    Passthrough route using a secret

    The following example assumes that you are using the default cpd 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_name=cpd \
--route_type=passthrough \
--cert_secret=<certificate-secret-name>
    Re-encrypt route using files in the work directory

    The following example assumes that you are using the default cpd route.

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

    <CA-certificate-file-name>
    The name of the CA certificate file.
    <TLS-certificate-name>
    The name of the TLS certificate.
    <TLS-private-key-name>
    The name of the private TLS key.
    cpd-cli manage setup-route \
--cpd_instance_ns=${PROJECT_CPD_INSTANCE} \
--route_name=cpd \
--route_type=reencrypt \
--ca_cert_file=<CA-certificate-file-name> \
--tls_cert_file=<TLS-certificate-name> \
--tls_key_file=<TLS-private-key-name>
    Re-encrypt route using a secret

    The following example assumes that you are using the default cpd 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_name=cpd \
--route_type=reencrypt \
--cert_secret=<certificate-secret-name>