Cert-manager, Let's Encrypt y renovación automática en Kubernetes
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
/metricsexponecertmanager_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