Handling automatic generation and renewal of TLS certificates for your service

The WoK Platform leverages the ACME protocol in order to provide an "easy to use" (tm) mechanism for TLS certificates management. Today's Web standards imply the use of encrypted communication between clients and services. This encryption requires TLS certificates to function.

The ACME protocol defines the way these certificates may be automatically obtained from a provider, called Certificate Issuer in the context of the WoK platform.

Note

The WoK platform uses the cert-manager operator and the openshift-routes plugin to provide this feature.

Certificate issuers list

As of today the following Certificate Issuers are available:

Certificate Issuer Name	Issuer production status	Rate limited	Backing provider organization	Optional restrictions
acme-letsencrypt-prod	Production	Yes	Let's encrypt	N/A
acme-ccin2p3-prod	Production	No	CNRS Certificate Provider	Restricted to domains managed by CC-IN2P3

Setting up a route to request a certificate

Using Kubernetes annotations you can easily request a certificate for a route:

kind: Route
apiVersion: route.openshift.io/v1
metadata:
  name: myroute
  namespace: myns
  [...]
  annotations:
    cert-manager.io/issuer-kind: ClusterIssuer
    cert-manager.io/issuer-name: acme-letsencrypt-prod
spec:
  [...]

Using the oc CLI that would give the following command call:

$ oc annotate route/myroute cert-manager.io/issuer-kind="ClusterIssuer" cert-manager.io/issuer-name="acme-letsencrypt-prod"
route.route.openshift.io/myroute annotated

A RSA key will be automatically generated and associated to the route (spec.tls.key field).
A few seconds later, the certificates should be issued.

You can check by describing the route and printing the route details:

$ oc describe route/myroute
Name:                   myroute
Namespace:              myns
[...]
Annotations:            cert-manager.io/certificate-revision=1     <------ Set by cert-manager operator
                        cert-manager.io/issuer-kind=ClusterIssuer
                        cert-manager.io/issuer-name=acme-letsencrypt-prod
[...]
Requested Host:         dn.mydomain.tld
                           exposed on router default (host router-default.apps.wok3.in2p3.fr) 5 minutes ago
Path:                   <none>
TLS Termination:        edge
Insecure Policy:        Redirect
Endpoint Port:          8080-tcp

Service:        myservice
Weight:         100 (100%)
Endpoints:      172.19.a.b:8080

$ oc get -o yaml -n myns route/myroute
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  annotations:
    cert-manager.io/certificate-revision: "1"
    cert-manager.io/issuer-kind: ClusterIssuer
    cert-manager.io/issuer-name: acme-letsencrypt-prod
  [...]
  name: myroute
  namespace: myns
spec:
  host: dn.mydomain.tld
  port:
    targetPort: 8080-tcp
  tls:
    certificate: |                                  <------ Set by cert-manager operator
      -----BEGIN CERTIFICATE-----
      [REDACTED]
      -----END CERTIFICATE-----
    insecureEdgeTerminationPolicy: Redirect
    key: |                                          <------ Set by cert-manager operator
      -----BEGIN RSA PRIVATE KEY-----
      [REDACTED]
      -----END RSA PRIVATE KEY-----
    termination: edge
  to:
    kind: Service
    name: myservice
    weight: 100
  wildcardPolicy: None
status:
  [...]

Additional settings

Warning

Setting bad values for cert-manager.io/duration and cert-manager.io/renew-before might get you rate limited by the provider (for too frequent renewals) on the whole domain.

Certificate duration

You can set the certificate life duration with the following annotation:

cert-manager.io/duration: 1h # Optional, defaults to 90 days

Certificate renewal

You can set the certificate renewal time with the following annotation:

cert-manager.io/renew-before: 30m # Optional, defaults to 1/3 of total certificate duration.