// Module included in the following assemblies:
//
// * networking/ingress_load_balancing/routes/securing-routes.adoc

:_mod-docs-content-type: PROCEDURE
[id="nw-ingress-route-secret-load-external-cert_{context}"]
= Creating a route with externally managed certificates

[role="_abstract"]
You can configure {product-title} 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 {product-title} 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`.
+
[IMPORTANT]
====
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:
+
[source,terminal]
----
$ 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:
+
[source,terminal]
----
$ 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
[source,yaml]
----
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:
+
[source,terminal]
----
$ 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.
+
[NOTE]
====
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:

[source,terminal]
----
$ 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.