OSDOCS-3628: Adding ability to create an ingress route with a custom certificate

Author: skrthomas

modules/nw-ingress-creating-a-route-via-an-ingress.adoc

@@ -6,7 +6,7 @@
 [id="nw-ingress-creating-a-route-via-an-ingress_{context}"]
 = Creating a route through an Ingress object
 
-Some ecosystem components have an integration with `Ingress` resources but not with `Route` resources. To cover this case, {product-title} automatically creates managed route objects when an Ingress object is created. These route objects are deleted when the corresponding `Ingress` objects are deleted.
+Some ecosystem components have an integration with Ingress resources but not with route resources. To cover this case, {product-title} automatically creates managed route objects when an Ingress object is created. These route objects are deleted when the corresponding Ingress objects are deleted.
 
 .Procedure
 
@@ -21,6 +21,7 @@ metadata:
   name: frontend
   annotations:
     route.openshift.io/termination: "reencrypt" <1>
+    route.openshift.io/destination-ca-certificate-secret: secret-ca-cert <3>
 spec:
   rules:
   - host: www.example.com <2>
@@ -39,9 +40,8 @@ spec:
     secretName: example-com-tls-certificate
 ----
 +
-<1> The `route.openshift.io/termination` annotation can be used to configure the `spec.tls.termination` field of the `Route` as `Ingress` has no field for this. The accepted values are `edge`, `passthrough` and `reencrypt`. All other values are silently ignored. When the annotation value is unset, `edge` is the default route. The TLS certificate details must be defined in the template file to implement the default edge route and to prevent producing an insecure route.
-<2> When working with an `Ingress` object, you must specify an explicit host name, unlike when working with routes. You can use the `<host_name>.<cluster_ingress_domain>` syntax, for example `apps.openshiftdemos.com`, to take advantage of the `*.<cluster_ingress_domain>` wildcard DNS record and serving certificate for the cluster. Otherwise, you must ensure that there is a DNS record for the chosen hostname.
-
+<1> The `route.openshift.io/termination` annotation can be used to configure the `spec.tls.termination` field of the `Route` as `Ingress` has  no field for this. The accepted values are `edge`, `passthrough` and `reencrypt`. All other values are silently ignored. When  the annotation value is unset, `edge` is the default route. The TLS certificate details must be defined in the template file to implement the default edge route.
+<2> When working with an `Ingress` object, you must specify an explicit hostname, unlike when working with routes. You can use the `<host_name>.<cluster_ingress_domain>` syntax, for example `apps.openshiftdemos.com`, to take advantage of the `*.<cluster_ingress_domain>` wildcard DNS record and serving certificate for the cluster. Otherwise, you must ensure that there is a DNS record for the chosen hostname.
 
 .. If you specify the `passthrough` value in the `route.openshift.io/termination` annotation, set `path` to `''` and `pathType` to `ImplementationSpecific` in the spec:
 +
@@ -60,14 +60,17 @@ spec:
               port:
                 number: 443
 ----
-
 +
 [source,terminal]
 ----
 $ oc apply -f ingress.yaml
 ----
 +
+<3> The `route.openshift.io/destination-ca-certificate-secret` can be used on an Ingress object to define a route with a custom destination certificate (CA). The annotation references a kubernetes secret, `secret-ca-cert` that will be inserted into the generated route.
 
+.. To specify a route object with a destination CA from an ingress object, you must create a `kubernetes.io/tls` or `Opaque` type secret with a certificate in PEM-encoded format in the `data.tls.crt` specifier of the secret.
+
++
 . List your routes:
 +
 [source,terminal]
@@ -114,6 +117,10 @@ spec:
       [...]
       -----END RSA PRIVATE KEY-----
     termination: reencrypt
+    destinationCACertificate: |
+      -----BEGIN CERTIFICATE-----
+      [...]
+      -----END CERTIFICATE-----
   to:
     kind: Service
     name: frontend

modules/nw-ingress-reencrypt-route-custom-cert.adoc

@@ -0,0 +1,58 @@
+// This is included in the following assemblies:
+//
+// networking/routes/route-configuration.adoc
+
+:_content-type: PROCEDURE
+[id="creating-re-encrypt-route-with-custom-certificate_{context}"]
+= Creating a route using the destination CA certificate in the Ingress annotation
+
+The `route.openshift.io/destination-ca-certificate-secret` annotation can be used on an Ingress object to define an route with a custom certificate (CA).
+
+.Prerequisites
+* You must have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host.
+* You may have a separate CA certificate in a PEM-encoded file that completes the certificate chain.
+* You must have a separate destination CA certificate in a PEM-encoded file.
+* You must have a service that you want to expose.
+
+
+.Procedure
+
+. Add the `route.openshift.io/destination-ca-certificate-secret` to the Ingress annotations:
++
+[source,yaml]
+----
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: frontend
+  annotations:
+    route.openshift.io/termination: "reencrypt"
+    route.openshift.io/destination-ca-certificate-secret: secret-ca-cert <1>
+...
+----
+<1> The annotation references a kubernetes secret.
+
++
+. The secret referenced in this annotation will be inserted into the generated route.
++
+.Example output
+[source,yaml]
+----
+apiVersion: route.openshift.io/v1
+kind: Route
+metadata:
+  name: frontend
+  Annotations:
+    route.openshift.io/termination: reencrypt
+    route.openshift.io/destination-ca-certificate-secret: secret-ca-cert
+spec:
+...
+  tls:
+    insecureEdgeTerminationPolicy: Redirect
+    termination: reencrypt
+    destinationCACertificate: |
+      -----BEGIN CERTIFICATE-----
+      [...]
+      -----END CERTIFICATE-----
+...
+----

networking/routes/route-configuration.adoc

@@ -43,4 +43,6 @@ include::modules/nw-route-admission-policy.adoc[leveloffset=+1]
 
 include::modules/nw-ingress-creating-a-route-via-an-ingress.adoc[leveloffset=+1]
 
+include::modules/nw-ingress-reencrypt-route-custom-cert.adoc[leveloffset=+1]
+
 include::modules/nw-router-configuring-dual-stack.adoc[leveloffset=+1]