HTTPS Setup

As almost all our services are exposed web services, HTTPs access over TLS is crucial. We want to use Let's Encrypt services and automatic renewal of certificates is mandatory.

There are multiple ways to handle certificates and certificates renewal with k8s. We chose cert-manager for its ease of use and robustness.

Setup

• Install cert-manager, using documentation
• Create a ClusterIssuer. Make sure to use staging, verify it's working then reproduce with prod and eventually remove staging.

kubectl apply -f le-staging-clusterissuer.yaml
kubectl get clusterissuer -o wide
kubectl describe clusterissuer letsencrypt-staging

kubectl apply -f le-prod-clusterissuer.yaml
kubectl get clusterissuer -o wide
kubectl describe clusterissuer letsencrypt-prod

# optionnal
kubectl delete clusterissuer letsencrypt-staging

# STAGING
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: contact+certs@kiwix.org
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - selector: {}
      http01:
        ingress:
          class: nginx

# PRODUCTION
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: contact+certs@kiwix.org
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - selector: {}
      http01:
        ingress:
          class: nginx

Creating a certificate

• Make sure your domain points to the Ingress server. For scaleway, this can be done by using a CNAME to the DNS entry displayed in the Scaleway Cluster dashboard (ex: {uuid}.nodes.k8s.fr-par.scw.cloud. – for PAR Availability Zone)
• Create a Certificate referencing our ClusterIssuer but using appropriate namespace. The certificate will be stored in a Secret that your Ingress will need to access. Thus, your Ingress and the Certificate must reside in the same namespace.
• Again, recommended to use the staging ClusterIssuer first and test the procedure before using on prod.

kubectl apply -f my-domain-certificate.yaml
kubectl get certificates -o wide --namespace my-ns
kubectl describe certificate my-domain-tld --namespace my-ns

---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-domain-tld
  namespace: my-ns
spec:
  secretName: my-domain-tld-tls
  issuerRef:
    kind: ClusterIssuer
    name: letsencrypt-staging
  commonName: my-domain.tld
  dnsNames:
  - my-domain.tld
  - www.my-domain.tld

If you don't have multiple entries for you domain (ex: no www. entry), you still must use commonName and an identical entry in dnsNames.

References

• https://cert-manager.io/docs/installation/
• https://cert-manager.io/docs/tutorials/acme/http-validation/