|
| 1 | +// Module included in the following assemblies: |
| 2 | +// |
| 3 | +// * networking/routes/secured-routes.adoc |
| 4 | + |
| 5 | +:_mod-docs-content-type: PROCEDURE |
| 6 | +[id="nw-ingress-route-secret-load-external-cert_{context}"] |
| 7 | += Creating a route with externally managed certificate |
| 8 | + |
| 9 | +:FeatureName: Securing route with external certificates in TLS secrets |
| 10 | +include::snippets/technology-preview.adoc[] |
| 11 | + |
| 12 | +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. Using the externally managed certificate reduces errors ensuring a smoother rollout of certificate updates, enabling the OpenShift router to serve renewed certificates promptly. |
| 13 | + |
| 14 | +[NOTE] |
| 15 | +==== |
| 16 | +This feature applies to both edge routes and re-encrypt routes. |
| 17 | +==== |
| 18 | + |
| 19 | +.Prerequisites |
| 20 | + |
| 21 | +* You must enable the `RouteExternalCertificate` feature gate. |
| 22 | +* You must have the `create` and `update` permissions on the `routes/custom-host`. |
| 23 | +* You must have a secret containing a valid certificate/key pair in PEM-encoded format of type `kubernetes.io/tls`, which includes both `tls.key` and `tls.crt` keys. |
| 24 | +* You must place the referenced secret in the same namespace as the route you want to secure. |
| 25 | +
|
| 26 | +.Procedure |
| 27 | + |
| 28 | +. Create a `role` in the same namespace as the secret to allow the router service account read access by running the following command: |
| 29 | ++ |
| 30 | +[source,terminal] |
| 31 | +---- |
| 32 | +$ oc create role secret-reader --verb=get,list,watch --resource=secrets --resource-name=<secret-name> \ <1> |
| 33 | +--namespace=<current-namespace> <2> |
| 34 | +---- |
| 35 | +<1> Specify the actual name of your secret. |
| 36 | +<2> Specify the namespace where both your secret and route reside. |
| 37 | + |
| 38 | +. Create a `rolebinding` in the same namespace as the secret and bind the router service account to the newly created role by running the following command: |
| 39 | ++ |
| 40 | +[source,terminal] |
| 41 | +---- |
| 42 | +$ oc create rolebinding secret-reader-binding --role=secret-reader --serviceaccount=openshift-ingress:router --namespace=<current-namespace> <1> |
| 43 | +---- |
| 44 | +<1> Specify the namespace where both your secret and route reside. |
| 45 | + |
| 46 | +. Create a YAML file that defines the `route` and specifies the secret containing your certificate using the following example. |
| 47 | ++ |
| 48 | +.YAML definition of the secure route |
| 49 | +[source,yaml] |
| 50 | +---- |
| 51 | +apiVersion: route.openshift.io/v1 |
| 52 | +kind: Route |
| 53 | +metadata: |
| 54 | + name: myedge |
| 55 | + namespace: test |
| 56 | +spec: |
| 57 | + host: myedge-test.apps.example.com |
| 58 | + tls: |
| 59 | + externalCertificate: |
| 60 | + name: <secret-name> <1> |
| 61 | + termination: edge |
| 62 | + [...] |
| 63 | +[...] |
| 64 | +---- |
| 65 | +<1> Specify the actual name of your secret. |
| 66 | + |
| 67 | +. Create a `route` resource by running the following command: |
| 68 | ++ |
| 69 | +[source,terminal] |
| 70 | +---- |
| 71 | +$ oc apply -f <route.yaml> <1> |
| 72 | +---- |
| 73 | +<1> Specify the generated YAML filename. |
| 74 | + |
| 75 | +If the secret exists and has a certificate/key pair, the router will serve the generated certificate if all prerequisites are met. |
| 76 | + |
| 77 | +[NOTE] |
| 78 | +==== |
| 79 | +If `.spec.tls.externalCertificate` is not provided, the router will use default generated certificates. |
| 80 | +
|
| 81 | +You cannot provide the `.spec.tls.certificate` field or the `.spec.tls.key` field when using the `.spec.tls.externalCertificate` field. |
| 82 | +==== |
0 commit comments