Creating secure endpoints for external services

The Cloud Pak components create routes to allow clients outside the cluster to interact with user interfaces and APIs over HTTPS. By default, these endpoints are secured with certificates that are signed by the root CA certificate of the Cloud Pak. For production environments, it is likely that you want to use your own certificates that are trusted by your clients. In this case, concatenate all certificates of the certificate chain (the custom route certificate and its signers) in a single certificate (.crt) file.

About this task

OpenShift clusters have a default router that listens on all hostnames of a network subdomain. Typically *.apps appears in the external address, for example *.apps.example.com. The Cloud Pak operator creates routes with hostnames that are in the subdomain by using the pattern <component>-<namespace>.<router-canonical-name>. The <component> name is an abbreviation of the service name, for example cpe for Content Platform Engine. For more information about OpenShift routes, see Secured routes.

Clients connecting to an endpoint need the certificate that is issued for this route, and the complete list of signer certificates that are used to sign it. Routes use certificates, which must be signed. A shared suffix means that a single HTTPS wildcard certificate can be used to secure all of the routes of a deployment. The subject alternative name (SAN) in the certificate must include the hostname suffix.

If you want to customize the hostname suffix, you must specify a value for the shared_configuration.sc_deployment_hostname_suffix parameter. Again, the shared suffix is used by all the routes that the Cloud Pak deployment created.

The value of the sc_deployment_hostname_suffix parameter must follow a precise pattern that matches {unique-identifier}.{router-canoncial-name}.

Unique-identifier: A string that is unique in the cluster and can help users recognize the system. It must not exceed 32 characters.

Router-canonical-name

The DNS suffix that resolves to your OpenShift router. You can use the following command to query the exact value:

oc get route console -n openshift-console -o yaml | grep routerCanonicalHostname

The following custom resource excerpt sets the hostname suffix for all routes as sales.apps.myocpcluster.com.

shared_configuration: 
   sc_deployment_hostname_suffix: sales.apps.myocpcluster.com

All the resulting routes include the component name and the hostname suffix. For example, the route for Content Platform Engine is https://cpe-sales.apps.myocpcluster.com.

The SAN in the wildcard certificate for the example routes might be DNS:*.apps.myocpcluster.com.

Note: For many of the Cloud Pak components, you can overwrite the hostname and certificate configuration. For example, you can specify a shared hostname suffix and individual certificates for each of the routes that are created.

Procedure

Optional: Concatenate multiple certificates into the signed certificate file.

The following command puts three certificate files into a single file.

cat server.crt intermediary.crt root.crt > tls.crt

The tls.crt file contains all three signed certificates. The following example shows how the certificates are saved in the file.

-----BEGIN CERTIFICATE-----
MIIGxTCCBa2gAwIBAgIQBsfsHm+sdGCWtBjm2GJ5azANBgkqhkiG9w0BAQsFADBN
...
Hnm1QervpJroUVjgCAGnTAcRGs6XDuypQKznlnroQpbbWD0J2dz3dSMSJX2PuLMv
pC5QC+eRr9qc
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIGxTCCBa2gAwIBAgIQBsfsHm+sdGCWtBjm2GJ5azANBgkqhkiG9w0BAQsFADBN
...

ZXquzPbsVNypZlQwDEeLJO1QbZcAdwAiRUUHWVUkVpY/oS/x922G4CMmY63AS39d
xoNcbuIPAgAAAXQsQ7RuAAAEAwBIMEYCIQDLwhUk2FPJhSjFz8O/ufO46OdkKsTJ
w2UIHxBlcePdxAIhAM6/ZBftoapGV7k+bzDgBaC4Lc9mTLpoRd1TI1prlm1LAHYA
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E
aWdpQ2VydCBTSEEyIFNlY3VyZSBTZXJ2ZXIgQ0EwHhcNMjAwODI2MDAwMDAwWhcN
MjIwODMxMTIwMDAwWjCBgjELMAkGA1UEBhMCVVMxETAPBgNVBAgTCE5ldyBZb3Jr
...
pC5QC+eRr9qc
-----END CERTIFICATE-----

Create a secret that contains the certificate and private key of your wildcard certificate.
The following command creates a SSL/TLS secret that is named cp4a-wildcard from a signed certificate (tls.crt) file and a private key (tls.key) file that matches the certificate.
```
oc create secret tls cp4a-wildcard --cert tls.crt --key tls.key
```
Note: The tls.crt and tls.key are the files that are needed for an external service to connect to all the endpoints of a deployment.
Set the value of the shared_configuration.external_tls_certificate_secret parameter to the name of the secret that contains your wildcard certificate.

If defined, the certificate is used for all external routes. If it is not defined, certificates for all external routes are signed with the certificate in the root_ca_secret parameter.
The following example shows that the external TLS certificate secret is set to the cp4a-wildcard secret.
```
shared_configuration:
   external_tls_certificate_secret: cp4a-wildcard
```

What to do next

There are separate tasks that must be done to update certificates for the routes in the foundation layers of the platform. For more information, see IBM Certificate manager (cert-manager).

When your certificates expire, you must take the following actions to renew the secrets:

Update or re-create the secret with the updated certificate.
Restart the corresponding pods that are associated with the secret.