Red Hat OpenShift Container Platform

Configuring certificates to secure routes in your cluster

To encrypt traffic between external clients and your applications, configure certificates for routes in your Red Hat OpenShift Container Platform cluster. You can secure your routes by defining TLS termination types, such as edge, passthrough, or re-encrypt, to match your specific security policies.

Prerequisites

You have installed version 1.14.0 or later of the cert-manager Operator for Red Hat OpenShift.
You have create permission on the routes/custom-host sub-resource, which is used for both creating and updating routes.
You have a Service resource that you want to expose.

Procedure

Create an Issuer to configure the HTTP-01 solver by running the following command. For other ACME issuer types, see "Configuring ACME an issuer".

$ oc create -f - << EOF
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-acme
  namespace: <namespace>
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-acme-account-key
    solvers:
      - http01:
          ingress:
            ingressClassName: openshift-default
EOF

where:

<namespace>: Specifies the namespace where the Issuer is located. It must be the same as the route namespace.

Create a Certificate object for the route by running the following command. The secretName specifies the TLS secret that is going to be issued and managed by cert-manager and will also be referenced in your route in the following steps.
```
$ oc create -f - << EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-route-cert
  namespace: <namespace>
spec:
  commonName: <common_host>
  dnsNames:
    - <hostname>
  usages:
    - server auth
  issuerRef:
    kind: Issuer
    name: letsencrypt-acme
  secretName: <secret_name>
EOF
```
where:

<namespace>

Specifies the namespace where the Certificate resource is located. It should be the same as the namespace of your route.

<common_host>

Specifies the common name of your certificate by using the hostname of the route.

<hostname>

Specifies the hostname of your route to the DNS names of your certificate.

<secret_name>

Specifies the name of the secret that contains the certificate.
Create a Role to provide the router service account permissions to read the referenced secret by using the following command:
```
$ oc create role secret-reader \
  --verb=get,list,watch \
  --resource=secrets \
  --resource-name=<secret_name> \
  --namespace=<namespace>
```
where:

<secret_name>

Specifies the name of the secret that you want to grant access to. It should be consistent with your secretName specified in the Certificate resource.

<namespace>

Specifies the namespace where both your secret and route are located.
Create a RoleBinding resource to bind the router service account with the newly created Role resource by using the following command:
```
$ oc create rolebinding secret-reader-binding \
  --role=secret-reader \
  --serviceaccount=openshift-ingress:router \
  --namespace=<namespace>
```
where:

<namespace>

Specifies the namespace where both your secret and route are located.
Create a route for your service resource, that uses edge TLS termination and a custom hostname, by running the following command. The hostname is used when creating a Certificate resource in the next step.
```
$ oc create route edge <route_name> \
  --service=<service_name> \
  --hostname=<hostname> \
  --namespace=<namespace>
```
where:

<route_name>

Specifies the name of your route.

<service_name>

Specifies the service you want to expose.

<hostname>

Specifies the hostname of your route.

<namespace>

Specifies the namespace where your route is located.
To reference the secret and use the certificate issued by cert-manager, update the .spec.tls.externalCertificate field in the route by using the following command:
```
$ oc patch route <route_name> \
  -n <namespace> \
  --type=merge \
  -p '{"spec":{"tls":{"externalCertificate":{"name":"<secret_name>"}}}}'
```
where:

<route_name>

Specifies the name of your route.

<namespace>

Specifies the namespace where both your secret and route are located.

<secret_name>

Specifies the name of the secret that contains the certificate.

Verification

Verify that the certificate is created and ready to use by running the following command:
```
$ oc get certificate -n <namespace>
$ oc get secret -n <namespace>
```
where:

<namespace>

Specifies the namespace where both your secret and route are located.
Verify that the router is using the referenced external certificate by running the following command. The command should return with the status code 200 OK.
```
$ curl -IsS https://<hostname>
```
where:

<hostname>

Specifies the hostname of your route.
Verify the subject, subjectAltName, and issuer fields of your server certificate are all as expected from the curl verbose outputs by running the following command:
```
$ curl -v https://<hostname>
```
where:

<hostname>

Specifies the hostname of your route.

The certificate from the referenced secret secures the route. The cert-manager component issues the certificate and automatically manages the certificate lifecycle.