manage setup-route

Replace the default self-signed TLS certificate with a custom TLS certificate or customize the route to the platform.

Extended description

Cloud Pak for Data exposes one HTTPS port as the primary access point for the web client and API requests. On Red Hat® OpenShift® Container Platform, the port is exposed as an OpenShift route.

The default route, named cpd, has the following characteristics:
  • The default route is a re-encrypt route.

    This means that encrypted traffic is re-encrypted by OpenShift before it is sent to Cloud Pak for Data.

  • The default route uses a self-signed TLS certificate to enable HTTPS connections.

    This certificate is untrusted by all HTTPS clients. It is strongly recommended that you replace the self-signed certificate with your own certificate.

    Important: If you do not replace the self-signed certificate with your own certificate, the user's browser does not cache the user interface, which can adversely impact performance.
You can use the cpd-cli manage setup-route command to:
  • Replace the default self-signed certificates with a custom TLS certificate
  • Customize the route by:
    • Changing the hostname of the default route
    • Changing the default route from a re-encrypt route to a passthrough route

Cloud Pak for Data supports several types of routes. The type of route that you use determines the requirements for the route:

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 in 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, create a secret that you provide to the cpd-cli manage setup-route command.
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_INST_OPERANDS} \
--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_INST_OPERANDS} \
--from-file=ca.crt=./<ca-certificate-file-name> \
--from-file=tls.crt=./<tls-certificate-file-name> \
--from-file=tls.key=./<tls-key-file-name>

Syntax

cpd-cli manage setup-route \
--cpd_instance_ns=<project-name> \
[--custom_hostname=<hostname>] \
[--route_type=passthrough|reencrypt] \
[--route_secret=<certificate-secret-name>]

Arguments

The setup-route command has no arguments.

Options

Table 1: Command options
Option Description
--route_secret The name of the secret that contains the files. The contents of the secret depend on whether You must specify a CA certificate in addition to the TLS certificate and the TLS private key.
Status
Required if you want to provide a custom TLS certificate and you want to use a secret to provide the required files.
Syntax
--route_secret=<certificate-secret-name>
Default value
No default.
Valid value
The name of the secret that contains the required files.
--cpd_instance_ns The project where the IBM Software Hub control plane and services are installed.
Status
Required.
Syntax
--cpd_instance_ns=<project-name>
Default value
No default. User-defined.
Valid value
The name of a project (namespace) where the IBM® Software Hub control plane is installed.
--custom_hostname The hostname to use in the route.
Status
Optional.
Syntax
--custom_hostname=<hostname>
Default value
By default, the route to the platform has the following structure:
https://cpd-namespace.apps.OCP-default-domain
If you omit this option, the default hostname is used when you:
  • Edit the default route (cpd)
  • Create a route

The default hostname is determined by Red Hat OpenShift Container Platform.

Valid value
The fully qualified domain name (FQDN) that you want to assign to the route, for example mycompany.com.
--route_type The type of the route.
Status
Optional.
Syntax
--route_type=passthrough|reencrypt
Default value
reencrypt

If you omit this option, the default value is used.

Valid value
passthrough
Specify passthrough to have the OpenShift router terminate encrypted traffic and re-encrypt it before sending it to Cloud Pak for Data.
reencrypt
Specify reencrypt to send encrypted traffic directly to Cloud Pak for Data without the OpenShift router providing TLS termination.

Examples

Note: The following example uses the recommended installation environment variables.

It is strongly recommended that you use a script to create environment variables with the correct values for your environment. For details, see Setting up installation environment variables.

Update the predefined cpd route to use a custom hostname and TLS certificate and to change the route to a passthrough route.
cpd-cli manage setup-route \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--route_secret=cpd-tls-secret \
--custom_hostname=cpd.mycompany.com \
--route_type=passthrough
Update the predefined cpd route to use a custom TLS certificate
cpd-cli manage setup-route \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--route_secret=cpd-tls-secret