`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 passthrough route.
This means that encrypted traffic is sent straight to Cloud Pak for Data without the OpenShift router providing TLS termination.
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 passthrough route to a re-encrypt route
- Replacing the default route with a custom 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 (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.

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

Syntax

cpd-cli manage setup-route \
--cpd_instance_ns=<project-name> \
[--custom_hostname=<hostname>] \
[--route_type=passthrough|reencrypt] \
[--route_name=<route-name>] \
[--cert_secret=<certificate-secret-name>] \
[--ca_cert_file=<CA-certificate-file-name>] \
[--tls_cert_file=<TLS-certificate-name>] \
[--tls_key_file=<TLS-private-key-name>]

Arguments

The setup-route command has no arguments.

Options

Option	Description
`--ca_cert_file`	The name of the CA certificate file. Status Required if you want to change the route to a re-encrypt route and you want to put the CA certificate file in the `cpd-cli-workspace/olm-utils-workspace/work` directory rather than creating a secret. Syntax `--ca_cert_file=<CA-certificate-file-name>` Default value No default. Valid value The name of the CA certificate file in the `cpd-cli-workspace/olm-utils-workspace/work` directory.
`--cert_secret`	The name of the secret that contains the files. The contents of the secret depend on whether you need to 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 `--cert_secret=<certificate-secret-name>` Default value No default. Valid value The name of the secret that contains the required files.
`--cpd_instance_ns`	The OpenShift project where the IBM Cloud Pak® for Data 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 Cloud Pak for Data 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 new 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_name`	The name of the route. Status Optional. Syntax `--route_name=<route-name>` Default value `cpd` If you omit this option, the specified changes are made to the default route (`cpd`). Valid value The name to use for the route. The name must conform to the Red Hat OpenShift Container Platform naming conventions.
`--route_type`	The type of the route. Status Optional. Syntax `--route_type=passthrough\|reencrypt` Default value passthrough If you omit this option, the default value is used. Valid value reencrypt Specify `reencrypt` to have the OpenShift router terminate encrypted traffic and re-encrypt it before sending it to Cloud Pak for Data. passthrough Specify `passthrough` to send encrypted traffic directly to Cloud Pak for Data without the OpenShift router providing TLS termination.
`--tls_cert_file`	The name of the TLS certificate. Status Required if you want to: Replace the default self-signed certificate with a custom certificate and you want to put the TLS certificate in the `cpd-cli-workspace/olm-utils-workspace/work` directory rather than creating a secret. Change the route to a re-encrypt route and you want to put the TLS certificate in the `cpd-cli-workspace/olm-utils-workspace/work` directory rather than creating a secret. Syntax `--tls_cert_file=<TLS-certificate-name>` Default value No default. Valid value The name of the TLS certificate file in the `cpd-cli-workspace/olm-utils-workspace/work` directory.
`--tls_key_file`	The name of the private TLS key. Status Required if you want to: Replace the default self-signed certificate with a custom certificate and you want to put the TLS key in the `cpd-cli-workspace/olm-utils-workspace/work` directory rather than creating a secret. Change the route to a re-encrypt route and you want to put the TLS key in the `cpd-cli-workspace/olm-utils-workspace/work` directory rather than creating a secret. Syntax `--tls_key_file=<TLS-private-key-name>` Default value No default. Valid value The name of the TLS key file in the `cpd-cli-workspace/olm-utils-workspace/work` directory.

Examples

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

Use a script to create environment variables with the correct values for your environment. For details, see Best practice: Setting up install variables.

Update the predefined cpd route to use a custom hostname and TLS certificate (from files in a secret) and to change the route to a re-encrypt route.

cpd-cli manage setup-route \
--cpd_instance_ns=${PROJECT_CPD_INSTANCE} \
--cert_secret=cpd-tls-secret \
--custom_hostname=cpd.mycompany.com \
--route_type=reencrypt

Update the predefined cpd route to use a custom hostname and TLS certificate (from files in the work directory)

cpd-cli manage setup-route \
--cpd_instance_ns=${PROJECT_CPD_INSTANCE} \
--tls_cert_file=tls.cert
--tls_key_file=tls.key
--custom_hostname=cpd.mycompany.com \
--route_type=reencrypt

Update the predefined cpd route to use a custom TLS certificate (from files in a secret)

cpd-cli manage setup-route \
--cpd_instance_ns=${PROJECT_CPD_INSTANCE} \
--cert_secret=cpd-tls-secret

Replace the predefined cpd route with a custom passthrough route

cpd-cli manage setup-route \
--cpd_instance_ns=${PROJECT_CPD_INSTANCE} \
--route_name=cpd-custom-route \
--custom_hostname=cpd.mycompany.com