Configuring OpenShift Routes¶

Once you have installed OpenShift Routes , you need to configure it to get a certificate for OpenShift routes from a cert-manager Issuer or ClusterIssuer.

Configuration requires three steps:

1. Configure an issuer.
2. Update your DNS records.
3. Annotate the routes.

Prerequisites¶

• You have cert-manager and OpenShift Routes installed in the same namespace. By default, this is in the venafi namespace.

Step 1: Configure an issuer¶

1. You can use either a ClusterIssuer or a namespace-based Issuer. The following example creates a Issuer. We will use a self-signed CA for this example. In production, use a Venafi(Cluster)Issuer instead.

   my-ca-issuer.yaml

   apiVersion: v1
   kind: Namespace
   metadata:
     name: demo
   ---
   apiVersion: cert-manager.io/v1
   kind: Issuer
   metadata:
     name: selfsigned-issuer
     namespace: demo
   spec:
     selfSigned: {}
   ---
   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: my-ca-cert
     namespace: demo
   spec:
     isCA: true
     commonName: my-ca
     secretName: my-ca-secret
     privateKey:
       algorithm: ECDSA
       size: 256
     issuerRef:
       name: selfsigned-issuer
       kind: Issuer
       group: cert-manager.io
   ---
   apiVersion: cert-manager.io/v1
   kind: Issuer
   metadata:
     name: my-ca-issuer
     namespace: demo
   spec:
     ca:
       secretName: my-ca-secret
   

2. Apply my-ca-issuer.yaml:

   oc apply -f my-ca-issuer.yaml
   

Step 2: Create an annotated route¶

1. If you used the example Issuer above, you can now use the following annotations:

   apiVersion: route.openshift.io/v1
   kind: Route
   metadata:
     name: example-route
     namespace: demo
     annotations:
       cert-manager.io/issuer-group: cert-manager.io
       cert-manager.io/issuer-kind: Issuer
       cert-manager.io/issuer-name: my-ca-issuer
   spec:
     host: app.service.clustername.domain.com
   

2. You can now annotate your routes:

   apiVersion: route.openshift.io/v1
   kind: Route
   metadata:
     name: example-route
     namespace: demo
     annotations:
       cert-manager.io/issuer-name: my-issuer # This is the only required annotation.
       cert-manager.io/issuer-group: cert-manager.io # Optional, defaults to cert-manager.io.
       cert-manager.io/issuer-kind: Issuer # Optional, defaults to Issuer. Other options are ClusterIssuer or an External Issuer
       cert-manager.io/duration: 1h # Optional, defaults to 90 days
       cert-manager.io/renew-before: 30m # Optional, defaults to 1/3 of total certificate duration.
       cert-manager.io/common-name: "My Certificate" # Optional, no default.
       cert-manager.io/alt-names: "mycooldomain.com,mysecondarydomain.com" # Optional, no default.
       cert-manager.io/ip-sans: "10.20.30.40,192.168.192.168" # Optional, no default.
       cert-manager.io/uri-sans: "spiffe://trustdomain/workload" # Optional, no default.
       cert-manager.io/private-key-algorithm: "ECDSA" # Optional, defaults to RSA.
       cert-manager.io/private-key-size: "384" # Optional, defaults to 265 for ECDSA and 2048 for RSA.
       cert-manager.io/email-sans: "me@example.com,you@example.com" # Optional, no default.
       cert-manager.io/subject-organizations: "company" # Optional, no default.
       cert-manager.io/subject-organizationalunits: "company division" # Optional, no default.
       cert-manager.io/subject-countries: "My Country" # Optional, no default.
       cert-manager.io/subject-provinces: "My Province" # Optional, no default.
       cert-manager.io/subject-localities: "My City" # Optional, no default.
       cert-manager.io/subject-postalcodes: "123ABC" # Optional, no default.
       cert-manager.io/subject-streetaddresses: "1 Example St" # Optional, no default.
       cert-manager.io/subject-serialnumber: "123456" # Optional, no default.
   spec:
     host: app.service.clustername.domain.com # Will be added to the Subject Alternative Names of the CertificateRequest.
     port:
       targetPort: 8080
     to:
       kind: Service
       name: hello-openshift
   

3. You should now be able to observe the route.Spec.TLS section of your route being populated automatically by cert-manager.

   The route's TLS certificate will be rotated two-thirds of the way through the certificate's lifetime, or the cert-manager.io/renew-before time, before it expires.

   You should also be able now to call the website: https://app.service.clustername.domain.com. This will be served by the route with a certificate signed by the CA you created in step 1.