Cert-manager installeren op je Kubernetes-cluster

Cert-manager is een Kubernetes-tool die het beheer van TLS-certificaten in een Kubernetes-cluster automatiseert. Het kan certificaten uitgeven vanuit verschillende bronnen, zoals Let's Encrypt of self-signed certificaten.

Cert-manager verlengt automatisch deze certificaten wanneer 2/3e van de geldigheidsperiode van het certificaat verlopen is.

In deze handleiding laten we zien hoe je Cert-manager installeert en configureert om Let's Encrypt-certificaten uit te geven op je Kubernetes-cluster.

Cert-manager installeren

Stap 1

Voeg de Jetstack-repository toe. Dit is de enige officiële bron van cert-manager Helm charts. Update vervolgens met het tweede commando je repositories om de Jetstack-repository te kunnen gebruiken

helm repo add jetstack https://charts.jetstack.io
helm repo update

Stap 2

Installeer Cert-manager met het commando:

helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.12.0 \
  --set installCRDs=true

• Je bent vrij een andere namespace naam dan cert-manager te gebruiken, maar deze is makkelijk herkenbaar.
• Vervang hier v1.12.0 door de meest recente stabiele versie zoals te zien is hier op Github.
• De optie installCRDs is verplicht, maar je kunt alternatief de installCRDs optie uitcommentarieëren en de CRD's (simpel gezegd is een CRD code om de Kubernetes API uit te breiden met custom resources die niet aanwezig zijn in de core Kubernetes API) los installeren met het commando:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.0/cert-manager.crds.yaml

Je krijgt nu een output zoals hieronder te zien om te bevestigen dat de installatie geslaagd is:

NAME: cert-manager
LAST DEPLOYED: Tue Jun 13 13:21:23 2023
NAMESPACE: cert-manager
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
cert-manager v1.11.0 has been deployed successfully!
In order to begin issuing certificates, you will need to set up a ClusterIssuer
or Issuer resource (for example, by creating a 'letsencrypt-staging' issuer).
More information on the different types of issuers and how to configure them
can be found in our documentation:
https://cert-manager.io/docs/configuration/
For information on how to configure cert-manager to automatically provision
Certificates for Ingress resources, take a look at the `ingress-shim`
documentation:
https://cert-manager.io/docs/usage/ingress/

De status van de Pods en Services die worden aangemaakt voor Cert-manager controleer je met respectievelijk de volgende commando's:

kubectl get pods -n cert-manager
kubectl get svc -n cert-manager

Een (Cluster)Issuer aanmaken

Om gebruik te kunnen maken van Cert-manager heb je een ClusterIssuer of Issuer nodig. Een ClusterIssuer definieert een certificaat uitgever (bijvoorbeeld Let's Encrypt) die gebruikt kan worden om TLS-certificaten voor je gehele Kubernetes-cluster te genereren. Een Issuer kan dat enkel voor een specifieke namespace.

Stap 1

Maak een .yaml bestand aan, bijvoorbeeld letsencrypt-issuer.yaml:

nano letsencrypt-issuer.yaml

Er zijn twee opties voor het genereren van SSL-certificaten; HTTP-01 en DNS-01. Voor wildcard-certificaten (bijv. voor *.voorbeeld.nl) gebruik je de DNS-01 optie. Via onze API ondersteunen wij deze optie en we leggen het gebruik van DNS-01 uit aan de hand hiervan. Mocht je een andere provider kiezen, let dan wel dat die deze functionaliteit moet ondersteunen en dat de domeinen die je gebruikt zijn geregistreerd bij die provider in het account dat je voor deze handleiding gebruikt.

Gebruik je een extern domein? Gebruik dan de optie HTTP-01, maar houd er rekening mee dat je dan geen wildcard-certificaten kunt genereren.

helm repo add cert-manager-webhook-transip https://demeester.dev/cert-manager-webhook-transip
helm install --namespace cert-manager cert-manager-webhook-transip cert-manager-webhook-transip/cert-manager-webhook-transip

mkdir transip

cat << EOF > transip/transip.key
-----BEGIN PRIVATE KEY-----
MIIEwAIBADANBgkqhkiG9w0BAQEFAASCBKowggSmAgEAAoIBAQDKoaYJtbVnJw58
PYGH8WIJ7ZjWd2lke0IbMV+dNGs=
-----END PRIVATE KEY-----
EOF

kubectl create -n cert-manager secret generic transip-key --from-file transip/transip.key

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: letsencrypt-issuer-dns01
spec:
 acme:
   email: <JE_MAILADRES>
   server: https://acme-v02.api.letsencrypt.org/directory
   privateKeySecretRef:
     name: letsencrypt-issuer-dns01
   solvers:
     - dns01:
         webhook:
           groupName: acme.transip.nl
           solverName: transip
           config:
             accountName: <JE_TRANSIPACCOUNTNAAM>
             ttl: 300
             privateKeySecretRef:
               name: transip-secret
               key: privateKey

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-issuer
spec:
  acme:
    email: <JE_MAILADRES>
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-issuer
    solvers:
    - http01:
        ingress:
          class: traefik

Stap 2

Pas de configuratie van het .yaml bestand toe op je cluster:

kubectl apply -f letsencrypt-issuer.yaml   

Je krijgt nu een bevestiging te zien dat de configuratie succesvol is toegepast:

clusterissuer.cert-manager.io/letsencrypt-issuer created

Let op: Wanneer je een certificaat wil genereren (zie de volgende paragraaf) maak je een Ingress resource die precies de waarde hierboven moet gebruiken, oftewel clusterissuer.cert-manager.io/letsencrypt-issuer

Cert-manager gebruiken

Cert-manager is nu klaar voor gebruik. We gaan ervan uit dat je een Nginx Ingress Controller gebruikt op je Kubernetes-cluster. In dat geval is het gebruik van Cert-manager tweedelig: 1) je maakt een certificaat aan 2) je maakt een ingress resource aan. Het is aan te raden om van tevoren alvast de software te deployen waar je het certificaat voor wil gebruiken.

Stap 1

Voor je daadwerkelijk het certificaat genereerd, heb je een (sub)domein nodig in je TransIP-account. Verwijs de DNS-records van dit (sub)domein naar het publieke IP-adres van de loadbalancer van je Nginx Ingress Controller, zie stap 5 van deze handleiding.

Stap 2

Voor je het certificaat aanmaakt, heb je een ingress resource nodig om het certificaat toe te kunnen wijzen. De preciese inhoud van het bestand hangt af van jouw use case. Als voorbeeld gebruiken we hier een ingress voor Grafana. Maak eerst de resource aan:

nano grafana-ingress.yaml

Geef het bestand de onderstaande inhoud, waarbij je de volgende gegevens aanpast:

• metadata name: Pas aan naar de naam van de software waar je het certificaat voor wil gebruiken.
• namespace: De namespace moet overeenkomen met de naam van de namespace waar je het certificaat in wil gebruiken (op te vragen met kubectl get ns).
• annotations cert-manager.io/cluster-issuer: Pas de waarde aan naar de naam van de issuer die je eerder in dit artikel hebt aangemaakt.
• spec rules host: Pas aan naar het (sub)domein waar je het certificaat voor hebt aangemaakt.
• spec tls hosts: Pas deze waarde ook aan naar het (sub)domein waar je het certificaat voor hebt aangemaakt.
• spec tls secretName: Pas aan naar de naam van de secretName waarde uit stap 2 van deze paragraaf.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: grafana
  namespace: grafana
  annotations:
    ingressClassName: "nginx"
    cert-manager.io/cluster-issuer: "letsencrypt-issuer"
spec:
  rules:
  - host: subdomein.voorbeeld.nl
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: grafana
            port:
              number: 3000
  tls:
  - hosts:
    - subdomein.voorbeeld.nl
    secretName: subdomein-voorbeeld-nl-tls

Sla tot slot je wijzigingen op en sluit het bestand (ctrl + c > y > enter).

Stap 3

Pas de aangemaakte ingress toe met het kubectl apply-commando:

kubectl apply -f grafana-ingress.yaml

Stap 4

Maak een certificate resource aan, bijvoorbeeld subdomein-voorbeeld-nl-certificate.yaml

nano subdomein-voorbeeld-nl-certificate.yaml

Geef het bestand de onderstaande inhoud, waarbij je de volgende gegevens aanpast:

• metadata name: Vervang subdomein-voorbeeld-nl door een naam naar keuze, bijvoorbeeld die van je (sub)domein
• metadata namespace: Vervang ingress-nginx door de naam van de namespace waar je Nginx Ingress Controller in is opgenomen (indien die verschilt)
• spec secretName: Vervang door een naam naar keuze, bijvoorbeeld die van je (sub)domein met de toevoeging -tls
• spec issuerRef name: Vervang door de issuerRef name zoals je die hebt ingesteld in stap 1 van de vorige paragraaf. Als je de code uit deze handleiding hebt overgenomen dan is de naam 'letsencrypt-issuer'.
• spec commonName: De naam van je (sub)domein waar je het certificaat voor aanvraagt.
• dnsNames: De naam van het (sub)domein(en) waar je het certificaat voor aanvraagt, bijvoorbeeld voorbeeld.nl en www.voorbeeld.nl.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: subdomein-voorbeeld-nl
  namespace: ingress-nginx
spec:
  secretName: subdomein-voorbeeld-nl-tls
  issuerRef:
    name: letsencrypt-issuer
    kind: ClusterIssuer
  commonName: subdomein.voorbeeld.nl
  dnsNames:
  - subdomein.voorbeeld.nl
  - www.subdomein.voorbeeld.nl
    

Sla tot slot je wijzigingen op en sluit het bestand (ctrl + c > y > enter).

Stap 5

Genereer het certificaat met het kubectl apply-commando:

kubectl apply -f subdomein-voorbeeld-nl-certificate.yaml

Je krijgt een bevestiging te zien die er als volgt uitziet:

certificate.cert-manager.io/subdomein.voorbeeld.nl configured

Controleer vervolgens of het certificaat succesvol is aangemaakt met het commando:

kubectl get cert -n ingress-nginx

Onder 'READY' zou nu de status 'True' zichtbaar moeten zijn.

NAME                    READY   SECRET                      AGE
subdomein.voorbeeld.nl  True    subdomein-voorbeeld-nl-tls  2m14s

Zie je echter de status 'False'? Gebruik dan het volgende commando om te achterhalen wat de oorzaak van het issue is:

kubectl describe cert subdomein.voorbeeld.nl -n ingress-nginx

That's it! Je certificaat is nu gekoppeld aan je applicatie en is in dit voorbeeld bereikbaar vanaf voorbeeld.subdomein.nl/grafana