Red Hat OpenShift Container Platform

Creating a route with externally managed certificates

You can configure Red Hat OpenShift Container Platform routes with third-party certificate management solutions by using the .spec.tls.externalCertificate field of the route API. You can reference externally managed TLS certificates via secrets, eliminating the need for manual certificate management.

By using the externally managed certificate, you can reduce errors to ensure a smoother rollout of certificate updates and enable the Red Hat OpenShift Container Platform router to serve renewed certificates promptly. You can use externally managed certificates with both edge routes and re-encrypt routes.

Prerequisites

You must have a secret containing a valid certificate or key pair in PEM-encoded format of type kubernetes.io/tls, which includes both tls.key and tls.crt keys. Example command: $ oc create secret tls myapp-tls --cert=server.crt --key=server.key.

Note the following considerations for externally managed certificates:

When using externalCertificate, the router does not automatically pull a CA bundle from the secret. If your route requires a specific tls.caCertificate (for example, for client authentication or re-encryption), you must either provide it manually in the Route spec or bundle the full certificate chain directly into the tls.crt entry of the secret.
The Ingress Controller uses SubjectAccessReview to load external certificates. This means the ability of the router to serve the certificate is tied to the route creator’s permissions on that secret. If the user’s permissions are revoked, the router will eventually lose its lease on that certificate, and the route status will reflect a validation failure.

Procedure

Create a role object in the same namespace as the secret to allow the router service account read access by running the following command:
```
$ oc create role secret-reader --verb=get,list,watch --resource=secrets --resource-name=<secret-name> \
--namespace=<current-namespace>
```
Where:

<secret-name>

Specifies the actual name of your secret.

<current-namespace>

Specifies the namespace where both your secret and route reside.
Create a rolebinding object in the same namespace as the secret and bind the router service account to the newly created role by running the following command:
```
$ oc create rolebinding secret-reader-binding --role=secret-reader --serviceaccount=openshift-ingress:router --namespace=<current-namespace>
```
Where:

<current-namespace>

Specifies the namespace where both your secret and route reside.

Create a YAML file that defines the route and specifies the secret containing your certificate using the following example.

YAML definition of the secure route

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: myedge
  namespace: test
spec:
  host: myedge-test.apps.example.com
  tls:
    externalCertificate:
      name: <secret-name>
    termination: edge
    [...]
[...]

Where:

<secret-name>: Specifies the actual name of your secret.

Create a route resource by running the following command:

$ oc apply -f <route.yaml>

Where:

<route.yaml>

Specifies the generated YAML filename.

If the secret exists and has a certificate/key pair, the router will serve the generated certificate if all prerequisites are met.

If .spec.tls.externalCertificate is not provided, the router uses default generated certificates.

You cannot provide the .spec.tls.certificate field or the .spec.tls.key field when using the .spec.tls.externalCertificate field.

Troubleshooting

If your route is not serving the externally managed certificate, check the route’s status conditions by running the following command:

$ oc describe route <route-name> -n <route-namespace>

Look for the following specific failure reasons in the output to diagnose the issue without needing to consult the router logs:

ExternalCertificateGetFailed: Indicates an RBAC or SubjectAccessReview issue. Verify that the route creator has the correct permissions to read the secret and that the RoleBinding is properly configured.
ExternalCertificateValidationFailed: Indicates that the secret exists but is the wrong type. Ensure the secret was explicitly created as type kubernetes.io/tls and contains both the tls.key and tls.crt keys.