← volver

Cert-manager, Let's Encrypt y renovación automática en Kubernetes

Por · · [Admin-Sistemas] · lectura estimada: ~4 min

Introducción a la gestión de certificados en Kubernetes

En entornos de producción, la seguridad de las comunicaciones mediante TLS es un requisito innegociable. Kubernetes, como orquestador de contenedores, expone servicios a través de Ingress controllers que necesitan certificados válidos. Cert-manager es el estándar de facto para la emisión y renovación automática de certificados, integrándose con autoridades certificadoras como Let's Encrypt. Este artículo explora su arquitectura, despliegue y configuración avanzada, incluyendo resolución de problemas y optimización de recursos.

Arquitectura de cert-manager

Cert-manager opera como un conjunto de controladores dentro del cluster. Sus componentes clave son:

  • cert-manager-controller: bucle principal que reconcilia recursos personalizados (CRDs).
  • cert-manager-cainjector: inyecta certificados CA en los webhooks de Kubernetes.
  • cert-manager-webhook: valida y muta recursos de cert-manager.

Los CRDs fundamentales son:

  • Issuer/ClusterIssuer: define la autoridad certificadora (ACME, CA interna, Vault, etc.).
  • Certificate: solicita un certificado y gestiona su ciclo de vida.
  • Order y Challenge: objetos internos que manejan el protocolo ACME.

El flujo típico es: un recurso Certificate crea un Order, que genera Challenges (HTTP-01 o DNS-01) para validar el dominio. Una vez superado, Let's Encrypt emite el certificado y cert-manager lo almacena como un Secret de Kubernetes.

Instalación de cert-manager

La instalación se realiza mediante Helm o manifiestos YAML. Recomendamos Helm por su facilidad de actualización:

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

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

Verifica que los pods estén activos:

kubectl get pods -n cert-manager

Salida esperada:

NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-5c4b65b7cf-7k2lz              1/1     Running   0          2m
cert-manager-cainjector-6c8d4f8f9d-x9j2r   1/1     Running   0          2m
cert-manager-webhook-7d8f9f6c9b-4n2h3      1/1     Running   0          2m

Configuración de ClusterIssuer para Let's Encrypt

Un ClusterIssuer es global en el cluster. Para entornos de prueba, usamos el servidor de staging de Let's Encrypt (evita límites de rate limiting). En producción, usamos el servidor de producción.

ClusterIssuer con validación HTTP-01

Este método requiere que el Ingress controller esté accesible públicamente y que cert-manager pueda modificar los recursos del Ingress para resolver el desafío.

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

Aplica el recurso:

kubectl apply -f cluster-issuer-staging.yaml

Para producción, cambia el servidor por:

server: https://acme-v02.api.letsencrypt.org/directory

ClusterIssuer con validación DNS-01

La validación DNS-01 es ideal para dominios wildcard o cuando el Ingress no es accesible públicamente. Requiere credenciales de API del proveedor DNS. Ejemplo con AWS Route53:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-dns
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@tudominio.com
    privateKeySecretRef:
      name: letsencrypt-dns-key
    solvers:
    - dns01:
        route53:
          region: us-east-1
          accessKeyID: AKIAIOSFODNN7EXAMPLE
          secretAccessKeySecretRef:
            name: aws-secret
            key: secret-access-key

El secreto aws-secret debe contener la clave de acceso de IAM con permisos para Route53.

Creación de certificados y renovación automática

Cert-manager renueva automáticamente los certificados 30 días antes de su expiración. Al crear un recurso Certificate, puedes especificar la duración con duration y el período de renovación con renewBefore.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: tls-mi-app
  namespace: default
spec:
  secretName: tls-mi-app-secret
  issuerRef:
    name: letsencrypt-staging
    kind: ClusterIssuer
  dnsNames:
  - app.tudominio.com
  - www.app.tudominio.com
  duration: 2160h  # 90 días
  renewBefore: 360h  # 15 días antes

Aplica el certificado:

kubectl apply -f certificate.yaml

Verifica el estado:

kubectl describe certificate tls-mi-app

En la salida, busca la sección Events que mostrará "Certificate issued successfully". El secreto generado contiene las claves:

kubectl get secret tls-mi-app-secret -o yaml

Integración con Ingress Controller

Para que un Ingress use el certificado, referencia el secreto en la sección tls y configura la anotación del issuer:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mi-app-ingress
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-staging
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - app.tudominio.com
    secretName: tls-mi-app-secret
  rules:
  - host: app.tudominio.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: mi-app-service
            port:
              number: 80

Con las anotaciones cert-manager.io/cluster-issuer, cert-manager detecta automáticamente el Ingress y crea el recurso Certificate correspondiente.

Comandos útiles para diagnóstico

La renovación automática puede fallar por motivos de red, límites de API o configuraciones incorrectas. Aquí algunos comandos esenciales:

# Ver logs del controlador
kubectl logs -n cert-manager deployment/cert-manager-controller

# Listar todos los certificados y su estado
kubectl get certificate --all-namespaces

# Ver detalles de un challenge
kubectl describe challenge -n default

# Verificar el secreto del certificado
kubectl get secret tls-mi-app-secret -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -text -noout | grep "Not After"

Si un desafío HTTP-01 falla, verifica que el Ingress tenga la clase correcta y que el controlador responda en el puerto 80. Para DNS-01, comprueba que las credenciales del proveedor tengan permisos suficientes.

Optimización y buenas prácticas

  • Usa staging para pruebas: Let's Encrypt tiene límites de 50 certificados por dominio por semana. Staging permite probar sin restricciones.
  • Monitoreo de expiración: Implementa alertas con Prometheus usando el exporter de cert-manager. El endpoint /metrics expone certmanager_certificate_expiration_timestamp_seconds.
  • Backup de secretos: Los certificados son críticos. Realiza backups periódicos de los secretos con herramientas como Velero.
  • Evita rate limiting: Si tienes muchos dominios, usa un solo ClusterIssuer y agrupa dominios en un solo certificado SAN (Subject Alternative Name) cuando sea posible.
  • Renovación manual forzada: Si necesitas renovar antes de tiempo, elimina el recurso Certificate y vuelve a crearlo, o modifica el secretName para forzar una nueva emisión.

Resolución de problemas comunes

Error "403 Forbidden" en desafío HTTP-01

Generalmente ocurre porque el Ingress controller no tiene permisos para leer el

comentarios(0)

$ dejar comentario

סHola! Soy SylonBot. Si te pierdes en el artículo, pregúntame 👋
☕ invítame a un café Si el contenido te fue útil · via PayPal