Securing routes with the cert-manager Operator for Red Hat OpenShift

Configuring certificates to secure routes in your cluster
Additional resources

In the OpenShift Container Platform, the route API is extended to provide a configurable option to reference TLS certificates via secrets. With the Creating a route with externally managed certificate Technology Preview feature 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.

Securing routes with the cert-manager Operator for Red Hat OpenShift is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

Configuring certificates to secure routes in your cluster

The following steps demonstrate the process of utilizing the cert-manager Operator for Red Hat OpenShift with the Let’s Encrypt ACME HTTP-01 challenge type to secure the route resources in your OpenShift Container Platform cluster.

Prerequisites

You have installed the cert-manager Operator for Red Hat OpenShift 1.14.0 or later.
You have enabled the RouteExternalCertificate feature gate.
You have the create and update permissions on the routes/custom-host sub-resource.
You have a Service resource that you want to expose.

Procedure

Create a Route resource for your Service resource using edge TLS termination and a custom hostname by running the following command. The hostname will be used while creating a Certificate resource in the following steps.
```
$ oc create route edge <route_name> \ (1)
  --service=<service_name> \ (2)
  --hostname=<hostname> \ (3)
  --namespace=<namespace> (4)
```
1 Specify your route’s name.

2 Specify the service you want to expose.

3 Specify the hostname of your route.

4 Specify the namespace where your route is located.

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

Example Issuer.yaml file

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

1	Specify the namespace where the `Issuer` is located. It should 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> (1)
spec:
  commonName: <hostname> (2)
  dnsNames:
    - <hostname> (3)
  usages:
    - server auth
  issuerRef:
    kind: Issuer
    name: letsencrypt-acme
  secretName: <secret_name> (4)
EOF

1	Specify the `namespace` where the `Certificate` resource is located. It should be the same as your route’s namespace.
2	Specify the certificate’s common name using the hostname of the route.
3	Add the hostname of your route to the certificate’s DNS names.
4	Specify 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> \ (1)
  --namespace=<namespace> (2)

1	Specify the name of the secret that you want to grant access to. It should be consistent with your `secretName` specified in the `Certificate` resource.
2	Specify 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> (1)
```
1 Specify the namespace where both your secret and route are 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> \ (1)
  -n <namespace> \ (2)
  --type=merge \
  -p '{"spec":{"tls":{"externalCertificate":{"name":"<secret_name>"}}}}' (3)
```
1 Specify the route name.

2 Specify the namespace where both your secret and route are located.

3 Specify 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> (1)
$ oc get secret -n <namespace> (1)
```
1 Specify the namespace 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> (1)
```
1 Specify 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> (1)
```
1 Specify 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.

1	Specify your route’s name.
2	Specify the service you want to expose.
3	Specify the hostname of your route.
4	Specify the namespace where your route is located.

1	Specify the route name.
2	Specify the namespace where both your secret and route are located.
3	Specify the name of the secret that contains the certificate.

Configuring certificates to secure routes in your cluster

Additional resources