Securing routes with the {cert-manager-operator}

In the OpenShift Container Platform, the route API is extended to provide a configurable option to reference TLS certificates via secrets. With externally managed certificates enabled, you can minimize errors from manual intervention, streamline the certificate management process, and enable the OpenShift Container Platform router to promptly serve the referenced certificate.

Configuring certificates to secure routes in your cluster

To encrypt traffic between external clients and your applications, configure certificates for routes in your 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

Replace <namespace> with the namespace where the Issuer is located. It must be the same as your route’s 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 your route’s namespace.

<common_host>

Specifies the certificate’s common name using the hostname of the route.

<hostname>

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

<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>
```
Replace <namespace> with 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 your route’s name.

<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.
Update your route’s .spec.tls.externalCertificate field to reference the previously created secret and use the certificate issued by cert-manager 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 route name.

<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>
```
Replace <namespace> with the namespace name where both your secret and route reside.
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>
```
Replace <hostname> with the hostname of your route.
Verify the server certificate’s subject, subjectAltName and issuer are all as expected from the curl verbose outputs by running the following command:
```
$ curl -v https://<hostname>
```
Replace <hostname> with the hostname of your route. The route is now successfully secured by the certificate from the referenced secret issued by cert-manager. cert-manager will automatically manage the certificate’s lifecycle.

Securing routes with the {cert-manager-operator}

Configuring certificates to secure routes in your cluster

Additional resources