Cert-Manager pe Kubernetes: Ghid Complet de Configurare pentru Gestionarea Automată a Certificatelor TLS

Cert-Manager este un controller Kubernetes open-source care automatizează complet ciclul de viață al certificatelor TLS — de la emiterea inițială prin validare și reînnoire — prin integrarea directă cu autorități de certificare precum Let’s Encrypt, HashiCorp Vault și sisteme PKI private. Elimină fluxurile manuale de certificate tratând certificatele ca resurse native Kubernetes, gestionate declarativ prin Custom Resource Definitions (CRDs).

Pentru orice cluster Kubernetes de producție, certificatele TLS expirate sau configurate greșit sunt una dintre cele mai frecvente cauze ale întreruperilor neplanificate. Cert-Manager rezolvă această problemă prin reconcilierea continuă a stării certificatelor, reînnoirea automată a credențialelor înainte de expirare și stocarea materialului cheie rezultat în Kubernetes Secrets pe care controlerele Ingress și workload-urile le pot consuma imediat.

De ce Cert-Manager este standardul pentru automatizarea TLS în Kubernetes

Înainte ca Cert-Manager să devină soluția de facto, echipele fie scriptau reînnoirile certbot pe noduri individuale, rotau manual certificatele între namespace-uri, fie se bazau pe integrări specifice furnizorilor cloud care creau dependență de vendor. Cert-Manager unifică toate aceste abordări sub un singur plan de control nativ Kubernetes.

Avantaje cheie față de abordările ad-hoc:

• Gestionare declarativă: Intenția certificatului este exprimată ca manifest YAML, versionat alături de codul aplicației.
• Reconciliere automată: Bucla controlerului detectează diferențele dintre starea dorită și cea actuală a certificatului și le corectează fără intervenție umană.
• Suport multi-issuer: Un singur cluster poate utiliza simultan Let’s Encrypt pentru servicii publice, un CA intern pentru mTLS service-mesh și HashiCorp Vault pentru workload-uri sensibile la secrete.
• Trasabilitate: Fiecare obiect CertificateRequest este persistat în API-ul Kubernetes, oferindu-vă un istoric complet al emiterii.

Rularea Kubernetes pe o platformă de VPS Hosting cu stocare NVMe și acces root complet vă oferă controlul necesar pentru a configura rezolvoare DNS personalizate, a gestiona regulile de firewall pentru provocările ACME HTTP-01 și a instala CRD-uri la nivel de cluster fără restricții — toate condiții prealabile pentru o implementare Cert-Manager de nivel producție.

Arhitectura de bază: Cum funcționează Cert-Manager intern

Înțelegerea arhitecturii interne a Cert-Manager previne configurările greșite și vă ajută să depanați rapid eșecurile de emitere.

Mașina de stări a ciclului de viață al certificatelor

Cert-Manager gestionează certificatele printr-o mașină de stări deterministă. Fiecare resursă Certificate trece prin următoarele stări:

1. Pending — Obiectul Certificate există, dar niciun CertificateRequest valid nu a fost îndeplinit.
2. Issuing — Un CertificateRequest a fost creat și trimis la issuer-ul configurat.
3. Ready — Un certificat valid, neexpirat este stocat în Secret Kubernetes referențiat.
4. Renewal Pending — Certificatul se află în fereastra renewBefore (implicit: 30 de zile înainte de expirare) și un nou CertificateRequest este în curs de procesare.

Controlerul monitorizează toate obiectele Certificate la nivel de cluster și le reconciliază continuu starea. Dacă un Secret este șters manual, Cert-Manager detectează resursa lipsă și declanșează imediat re-emiterea — un comportament critic de auto-vindecare care previne întreruperile accidentale.

Componentele CRD de bază

Resursele Order și Challenge sunt create automat de issuer-ul ACME — rareori interacționați direct cu ele, dar inspectarea lor este calea principală de depanare când emiterea se blochează.

Stocarea certificatelor și formatul Secret

Odată emis, Cert-Manager scrie trei chei de date în Secret Kubernetes țintă:

• tls.crt — Lanțul complet de certificate (leaf + intermediare), codificat PEM.
• tls.key — Cheia privată, codificată PEM.
• ca.crt — Certificatul CA emitent (populat pentru CA-uri interne; poate fi gol pentru issuer-ele ACME).

Controlerele Ingress, service mesh-urile și pod-urile aplicațiilor montează direct acest Secret. Formatul este compatibil cu NGINX, Traefik, Istio, Linkerd și majoritatea celorlalți consumatori TLS nativi Kubernetes.

Issuer-e suportate și când să le utilizați

ACME (Let’s Encrypt și alternative)

Protocolul ACME este cea mai comună cale de emitere. Cert-Manager implementează clientul ACME complet conform RFC 8555, suportând atât endpoint-urile de staging cât și cele de producție.

Provocarea HTTP-01: Cert-Manager servește temporar un token la http://<domain>/.well-known/acme-challenge/<token>. Aceasta necesită ca domeniul să rezolve la un IP accesibil public pe portul 80. Funcționează pentru certificate cu un singur domeniu și SAN, dar nu poate emite certificate wildcard.

Provocarea DNS-01: Cert-Manager creează o înregistrare TXT _acme-challenge.<domain> prin intermediul unui API al furnizorului DNS. Aceasta funcționează în spatele firewall-urilor, suportă certificate wildcard (*.example.com) și este necesară pentru orice cluster care nu este expus direct la internet. Furnizorii DNS suportați includ Cloudflare, Route53, Google Cloud DNS, Azure DNS și mulți alții prin solvere webhook.

HashiCorp Vault

Issuer-ul Vault se integrează cu motorul de secrete PKI al Vault. Este alegerea preferată pentru:

• mTLS intern pentru microservicii unde certificatele trebuie să fie de scurtă durată (ore, nu luni).
• Medii cu cerințe stricte de custodie a cheilor unde cheile private nu trebuie să părăsească niciodată Vault.
• Rotația automată a certificatelor legată de sistemul de reînnoire a lease-urilor Vault.

Issuer-e Self-Signed și CA

Issuer-ul SelfSigned generează certificate semnate de propria cheie privată a certificatului — util pentru bootstrapping-ul unui CA rădăcină în cluster. Issuer-ul CA utilizează un Secret Kubernetes care conține o pereche de chei CA pentru a semna certificate, făcându-l potrivit pentru medii de dezvoltare interne și PKI service mesh.

Venafi

Integrarea Venafi vizează mediile enterprise cu aplicarea centralizată a politicilor de certificate, auditarea conformității și integrarea cu module de securitate hardware (HSM-uri).

Cert-Manager vs. abordări alternative de automatizare TLS

Pentru echipele care rulează Kubernetes pe un Server Dedicat sau VPS, Cert-Manager este singura abordare care este simultan nativă Kubernetes, suportă toate CA-urile majore și nu necesită nicio intervenție manuală continuă.

Instalarea Cert-Manager: Configurare pregătită pentru producție

Condiții prealabile

• Kubernetes 1.22+ (1.26+ recomandat pentru stabilitate completă CRD)
• kubectl configurat cu privilegii cluster-admin
• Helm 3.x instalat
• Un domeniu înregistrat cu acces la gestionarea DNS (pentru DNS-01) sau un IP ingress accesibil public (pentru HTTP-01)

Dacă vă gestionați propriul domeniu, Înregistrarea domeniului prin un furnizor care expune un API este puternic recomandată — permite rezolvarea complet automatizată a provocărilor DNS-01 fără intervenție manuală.

Pasul 1: Instalarea CRD-urilor și a controlerului Cert-Manager

Metoda de instalare recomandată pentru producție utilizează Helm cu CRD-uri gestionate separat pentru a evita conflictele la upgrade-ul Helm:

# Add the Jetstack Helm repository
helm repo add jetstack https://charts.jetstack.io
helm repo update

# Install Cert-Manager with CRDs included
helm install cert-manager jetstack/cert-manager 
  --namespace cert-manager 
  --create-namespace 
  --version v1.14.5 
  --set installCRDs=true 
  --set global.leaderElection.namespace=cert-manager

Verificați că toate cele trei pod-uri de bază rulează înainte de a continua:

kubectl get pods --namespace cert-manager

Rezultat așteptat:

NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-xxxxxxxxx-xxxxx              1/1     Running   0          60s
cert-manager-cainjector-xxxxxxxxx-xxxxx   1/1     Running   0          60s
cert-manager-webhook-xxxxxxxxx-xxxxx      1/1     Running   0          60s

cainjector injectează datele bundle CA în configurațiile webhook. webhook validează și mutează obiectele CRD Cert-Manager — dacă nu rulează, toate operațiunile kubectl apply pe resursele Cert-Manager vor eșua.

Pasul 2: Configurarea unui ClusterIssuer pentru Let’s Encrypt

Începeți întotdeauna cu mediul de staging Let’s Encrypt pentru a evita atingerea limitelor de rată de producție (50 de certificate per domeniu înregistrat pe săptămână):

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef:
      name: letsencrypt-staging-account-key
    solvers:
      - http01:
          ingress:
            class: nginx

Odată ce certificatele de staging sunt emise cu succes, creați issuer-ul de producție:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
      - http01:
          ingress:
            class: nginx

Aplicați ambele manifeste:

kubectl apply -f clusterissuer-staging.yaml
kubectl apply -f clusterissuer-prod.yaml

Verificați disponibilitatea issuer-ului:

kubectl describe clusterissuer letsencrypt-prod

Câmpul Status.Conditions trebuie să afișeze Ready: True. Dacă afișează False, înregistrarea contului ACME a eșuat — verificați adresa de email și conectivitatea rețelei din pod-ul cert-manager.

Pasul 3: Solicitarea explicită a unui certificat

Puteți solicita certificate fie prin crearea directă a unei resurse Certificate, fie prin adnotarea unei resurse Ingress. Abordarea explicită Certificate vă oferă mai mult control:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-tls
  namespace: production
spec:
  secretName: example-com-tls-secret
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  commonName: example.com
  dnsNames:
    - example.com
    - www.example.com
  duration: 2160h    # 90 days (Let's Encrypt default)
  renewBefore: 720h  # Renew 30 days before expiry

Aplicați și monitorizați emiterea:

kubectl apply -f certificate.yaml
kubectl describe certificate example-com-tls -n production

Urmăriți obiectele CertificateRequest și Order pentru starea detaliată:

kubectl get certificaterequest -n production
kubectl describe order -n production

Pasul 4: Metoda de adnotare Ingress (simplificată)

Pentru echipele care utilizează NGINX Ingress Controller, Cert-Manager poate fi declanșat automat printr-o adnotare — nu este necesar un manifest Certificate separat:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: production
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - example.com
        - www.example.com
      secretName: example-com-tls-secret
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

Cert-Manager detectează adnotarea și creează automat resursa Certificate corespunzătoare. Acesta este cel mai comun tipar în fluxurile de lucru GitOps.

Tipare avansate de configurare

Certificate wildcard cu DNS-01 (exemplu Cloudflare)

Certificatele wildcard necesită validare DNS-01. Mai întâi, creați un Secret care conține token-ul API Cloudflare:

kubectl create secret generic cloudflare-api-token 
  --from-literal=api-token=<YOUR_CLOUDFLARE_API_TOKEN> 
  --namespace cert-manager

Configurați ClusterIssuer cu un solver DNS-01:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod-dns
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-dns-account-key
    solvers:
      - dns01:
          cloudflare:
            apiTokenSecretRef:
              name: cloudflare-api-token
              key: api-token

Solicitați certificatul wildcard:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-example-com
  namespace: production
spec:
  secretName: wildcard-example-com-tls
  issuerRef:
    name: letsencrypt-prod-dns
    kind: ClusterIssuer
  dnsNames:
    - "*.example.com"
    - example.com

Capcană critică: Secret care conține credențialele furnizorului DNS trebuie să se afle în namespace-ul cert-manager când este referențiat de un ClusterIssuer. Dacă îl plasați în alt namespace, controlerul nu îl poate citi și emiterea va eșua silențios. Verificați jurnalele controlerului cert-manager cu kubectl logs -n cert-manager deploy/cert-manager dacă provocările se blochează.

PKI intern cu un CA Issuer

Pentru mTLS serviciu-la-serviciu în cadrul unui cluster, un issuer CA susținut de un root self-signed este mai potrivit decât ACME:

# Step 1: Create a self-signed root CA certificate
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned-root
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: internal-root-ca
  namespace: cert-manager
spec:
  isCA: true
  commonName: internal-root-ca
  secretName: internal-root-ca-secret
  issuerRef:
    name: selfsigned-root
    kind: ClusterIssuer
---
# Step 2: Create a CA issuer backed by the root certificate
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: internal-ca-issuer
spec:
  ca:
    secretName: internal-root-ca-secret

Serviciile pot acum solicita certificate de scurtă durată de la internal-ca-issuer pentru mTLS fără nicio dependență de CA extern.

Configurarea renewBefore pentru medii de înaltă securitate

Valoarea implicită renewBefore de 30 de zile este adecvată pentru certificatele Let’s Encrypt de 90 de zile. Pentru certificatele interne de scurtă durată (ex., valabilitate de 24 de ore), setați renewBefore la o fracțiune din durata totală:

spec:
  duration: 24h
  renewBefore: 8h

Cert-Manager va începe reînnoirea cu 8 ore înainte de expirare, oferind controlerului trei ferestre de reînnoire în cadrul unui ciclu de viață al certificatului de 24 de ore — o marjă de siguranță critică dacă clusterul experimentează indisponibilitate tranzitorie a serverului API.

Depanarea eșecurilor comune Cert-Manager

Certificat blocat în starea „Issuing”

# Check the Certificate status
kubectl describe certificate <name> -n <namespace>

# Check the associated CertificateRequest
kubectl describe certificaterequest -n <namespace>

# Check the ACME Order
kubectl describe order -n <namespace>

# Check the Challenge
kubectl describe challenge -n <namespace>

# Check controller logs
kubectl logs -n cert-manager deploy/cert-manager --tail=100

Cauze principale frecvente:

• Eșec HTTP-01: Controlerul Ingress nu rutează corect traficul /.well-known/acme-challenge/. Verificați că obiectul Ingress al provocării a fost creat și că portul 80 este accesibil de pe internet. Firewall-urile de pe host trebuie să permită TCP/80 inbound.
• Eșec DNS-01: Token-ul API al furnizorului DNS are permisiuni insuficiente sau propagarea DNS nu s-a finalizat. Serverele de validare Let’s Encrypt pot interoga rezolvoare diferite față de DNS-ul local — întârzierile de propagare de 60–120 de secunde sunt normale.
• Limită de rată depășită: Let’s Encrypt impune 5 tentative de validare eșuate per domeniu pe oră. După atingerea acestei limite, trebuie să așteptați înainte de a reîncerca. Testați întotdeauna cu endpoint-ul de staging mai întâi.
• Webhook indisponibil: Dacă pod-ul webhook cert-manager nu rulează, toate operațiunile CRD vor eșua cu o eroare de conexiune refuzată. Asigurați-vă că serviciul webhook are un endpoint valid.

Verificarea unui certificat implementat

# Check the Secret contents
kubectl get secret example-com-tls-secret -n production -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -text

# Check expiry date specifically
kubectl get secret example-com-tls-secret -n production -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -enddate

Listă de verificare pentru întărirea producției

Implementarea Cert-Manager într-un mediu de producție necesită mai mult decât o instalare Helm implicită. Aplicați aceste măsuri de întărire înainte de a trece în producție:

• Limite de resurse: Setați requests și limits CPU și memorie pe toate cele trei pod-uri Cert-Manager pentru a preveni contențiunea resurselor pe nodurile partajate.
• Audit RBAC: Cert-Manager necesită permisiuni RBAC extinse. Revizuiți obiectele ClusterRole instalate și restricționați-le la minimul necesar pentru tipurile dvs. de issuer.
• Namespace separat: Implementați întotdeauna Cert-Manager în propriul namespace cert-manager, izolat de workload-urile aplicațiilor.
• Monitorizare: Expuneți endpoint-ul de metrici Prometheus al Cert-Manager (--metrics-listen-address) și alertați pe certmanager_certificate_expiration_timestamp_seconds pentru a detecta eșecurile de reînnoire înainte ca acestea să afecteze serviciile.
• Backup stare CRD: Includeți obiectele Certificate, ClusterIssuer și Issuer în strategia de backup a clusterului. Pierderea acestor manifeste după un eveniment de recuperare în caz de dezastru înseamnă recrearea manuală a tuturor configurațiilor de certificate.
• Validare staging: Nu emiteți niciodată primul certificat față de un endpoint ACME de producție. Violările limitelor de rată pot bloca domeniul dvs. până la o săptămână.

Dacă rulați mai multe clustere Kubernetes — de exemplu, separând workload-urile de staging și producție — Panouri de control VPS pot simplifica gestionarea ciclului de viață al clusterului și vă oferă o interfață unificată pentru provizionarea infrastructurii de bază pe care rulează fiecare cluster.

Pentru workload-urile care necesită inferență accelerată GPU sau servire ML în spatele endpoint-urilor cu terminare TLS, aceleași tipare Cert-Manager se aplică pe infrastructura de GPU Hosting, unde gestionarea automată a certificatelor este la fel de critică pentru securizarea endpoint-urilor API ale modelelor.

Matrice de decizie practică: Alegerea issuer-ului potrivit

Concluzii cheie

• Instalați Cert-Manager folosind Helm cu installCRDs=true și validați întotdeauna față de endpoint-ul ACME de staging înainte de a trece la producție.
• Utilizați ClusterIssuer pentru clustere multi-namespace; utilizați Issuer cu domeniu de namespace numai când aveți nevoie de izolare CA per echipă.
• DNS-01 este strict necesar pentru certificatele wildcard și pentru clusterele care nu sunt direct accesibile de pe internet pe portul 80.
• Câmpul renewBefore nu este opțional în producție — setați-l la cel puțin o treime din duration total al certificatului.
• Când emiterea se blochează, calea de depanare este întotdeauna: Certificate → CertificateRequest → Order → Challenge → jurnalele controlerului.
• Credențialele API ale furnizorului DNS referențiate de un ClusterIssuer trebuie să se afle în namespace-ul cert-manager, nu în namespace-urile aplicațiilor.
• Monitorizați certmanager_certificate_expiration_timestamp_seconds în Prometheus și alertați pe acesta — eșecurile silențioase de reînnoire sunt cel mai periculos mod de eșec.
• Faceți backup la manifestele Certificate și ClusterIssuer ca parte a planului dvs. de recuperare în caz de dezastru.

Întrebări frecvente

Care este diferența dintre un Issuer și un ClusterIssuer în Cert-Manager?

Un Issuer are domeniu de namespace și poate emite certificate doar în namespace-ul unde este definit. Un ClusterIssuer are domeniu la nivel de cluster și poate fi referențiat de resursele Certificate din orice namespace. Pentru majoritatea clusterelor de producție, ClusterIssuer este alegerea corectă, cu excepția cazului în care aveți nevoie de izolare strictă CA la nivel de namespace.

De ce certificatul meu Cert-Manager este blocat în starea „Issuing”?

Inspectați obiectele Order și Challenge din același namespace folosind kubectl describe. Cele mai frecvente cauze sunt: portul 80 blocat de un firewall (HTTP-01), credențiale API DNS incorecte sau întârziere de propagare (DNS-01), limite de rată Let’s Encrypt depășite sau pod-ul webhook cert-manager care nu rulează. Verificați întotdeauna jurnalele controlerului cu kubectl logs -n cert-manager deploy/cert-manager.

Poate Cert-Manager emite certificate wildcard de la Let’s Encrypt?

Da, dar numai folosind tipul de provocare DNS-01. HTTP-01 nu poate valida domeniile wildcard. Trebuie să configurați o integrare cu furnizorul DNS (Cloudflare, Route53, etc.) în configurația solverului ClusterIssuer și să vă asigurați că credențialele API au permisiunea de a crea înregistrări TXT pe domeniul țintă.

Cum gestionează Cert-Manager reînnoirea automată a certificatelor?

Controlerul Cert-Manager compară continuu expirarea fiecărui obiect Certificate cu ora curentă. Când valabilitatea rămasă scade sub pragul renewBefore (implicit: 30 de zile), controlerul creează un nou CertificateRequest, finalizează provocarea ACME și înlocuiește atomic conținutul Secret țintă — totul fără a reporni pod-urile care consumă certificatul. Pod-urile care montează Secret ca volum vor vedea certificatul actualizat la următorul ciclu de sincronizare kubelet.

Este Cert-Manager potrivit pentru securizarea comunicării interne serviciu-la-serviciu, nu doar pentru HTTPS public?

Da. Folosind issuer-ul CA sau issuer-ul HashiCorp Vault, Cert-Manager poate emite certificate de scurtă durată pentru mTLS intern între microservicii. Acesta este un tipar comun în implementările service mesh unde fiecare workload are nevoie de un certificat de identitate unic. Câmpurile duration și renewBefore permit ca certificatele să fie valabile cât de puțin câteva minute, cu rotație complet automatizată.