Como instalar um certificado SSL da ACME no Kubernetes

A instalação de um certificado ACME SSL no Kubernetes agora é um processo padronizado e flexível, graças a ferramentas maduras como o cert-manager e ao amplo suporte de CAs comerciais. Se você estiver executando cargas de trabalho de produção por trás do NGINX Ingress, Traefik ou outro gateway, poderá automatizar o HTTPS seguro com controle total.

Este guia mostrará a você como instalar um certificado ACME SSL no Kubernetes usando o cert-manager. Abordaremos a instalação, a configuração de um emissor com External Account Binding (EAB) e a emissão de certificados para proteger seus serviços de entrada.

---

O que você precisará

Antes de mergulhar, certifique-se de que você:

• Você tem um cluster Kubernetes em funcionamento (recomenda-se a versão 1.23 ou superior)
• kubectl está configurado e funcionando
• Você tem acesso ao seu controlador de entrada (por exemplo, NGINX, Traefik)
• Seu domínio aponta para o IP público do controlador de entrada
• Você tem credenciais EAB de sua CA compatível com ACME:
  • URL do diretório ACME (por exemplo, https://acme.example.com/v2/DV)
  • Identificador de chave EAB (KID)
  • Chave HMAC do EAB

Observação: https://acme.example.com/v2/DV é usado em todo este guia como URL de diretório ACME de espaço reservado. Substitua-o pelo endpoint real de sua autoridade de certificação.

---

Etapa 1 – Instalar o cert-manager

cert-manager é o cliente ACME nativo do Kubernetes mais amplamente usado. Ele é executado como um controlador que gerencia a emissão e a renovação de certificados.

Instale via Helm (preferencialmente para produção):

kubectl create namespace cert-manager
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--version v1.14.4 \
--set installCRDs=true

Aguarde alguns segundos e confirme se todos os pods estão funcionando:

kubectl get pods -n cert-manager

Você deverá ver três pods: cert-manager, cert-manager-webhook e cert-manager-cainjector.

---

Etapa 2 – Criar um segredo do Kubernetes para as credenciais do EAB

Crie um segredo do Kubernetes para armazenar sua chave EAB com segurança:

kubectl create secret generic acme-eab-secret \
--namespace cert-manager \
--from-literal=eab-kid="YOUR_EAB_KID" \
--from-literal=eab-hmac-key="YOUR_EAB_HMAC_KEY"

Substitua por suas credenciais reais. Evite copiar e colar espaços em branco.

---

Etapa 3 – Definir um ClusterIssuer ou Emissor

Agora, crie um recurso ClusterIssuer (para todos os namespaces) ou Issuer (namespace único) que conecte o cert-manager à ACME CA usando as credenciais do EAB.

Aqui está um exemplo de ClusterIssuer YAML:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: acme-issuer
spec:
acme:
server: https://your.acme-server.com/v2/DV
email: [email protected]
privateKeySecretRef:
name: acme-private-key
externalAccountBinding:
keyID: YOUR_EAB_KID
keySecretRef:
name: acme-eab-secret
key: eab-hmac-key
solvers:
- http01:
ingress:
class: nginx

Aplique-o:

kubectl apply -f clusterissuer.yaml

Substitua ingress.class: nginx por traefik, nginx-internal ou qualquer outra classe de ingress que você tenha. Você pode encontrar isso na documentação do seu controlador ingress.

---

Etapa 4 – Criar um recurso de certificado

Quando o ClusterIssuer estiver pronto, crie um recurso de certificado que informe ao cert-manager qual domínio você deve proteger. Veja um exemplo:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: my-ssl-cert
namespace: default
spec:
secretName: my-ssl-cert-tls
issuerRef:
name: acme-issuer
kind: ClusterIssuer
commonName: yourdomain.com
dnsNames:
- yourdomain.com
- www.yourdomain.com

Aplique-o:

kubectl apply -f certificate.yaml

O cert-manager usará o emissor, resolverá o desafio via ingress e armazenará o certificado emitido como um segredo TLS do Kubernetes.

---

Etapa 5 – Faça referência ao certificado em seu Ingress

Atualize sua regra de entrada para usar o certificado gerado:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: my-ingress
namespace: default
annotations:
cert-manager.io/cluster-issuer: acme-issuer
spec:
tls:
- hosts:
- yourdomain.com
- www.yourdomain.com
secretName: my-ssl-cert-tls
rules:
- host: yourdomain.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: your-service
port:
number: 80

Aplique-o:

kubectl apply -f ingress.yaml

Quando o cert-manager detectar a anotação, ele começará a resolver o desafio ACME e emitirá o seu certificado.

---

Etapa 6 – Verificar o certificado e a renovação automática

Para verificar se tudo funcionou:

kubectl describe certificate my-ssl-cert

Procure o certificado emitido com sucesso.

Para verificar a configuração de renovação, execute:

kubectl get certificaterequests

O cert-manager lida com a renovação automaticamente cerca de 30 dias antes da expiração. Você pode simular uma renovação como esta:

kubectl cert-manager renew my-ssl-cert

---

Perguntas comuns

A configuração do ACME SSL no Kubernetes pode parecer um pouco abstrata, especialmente quando você faz malabarismos com controladores de entrada, segredos e registros DNS. Abaixo, respondemos a algumas perguntas comuns que os desenvolvedores enfrentam ao instalar certificados ACME em um ambiente Kubernetes, quer você esteja usando o cert-manager ou uma configuração alternativa.

Posso usar o DNS-01 em vez do HTTP-01?

Sim, o cert-manager oferece suporte à validação de DNS com provedores como Cloudflare, AWS e Google Cloud DNS. Use-o se você não expuser a porta 80.

O cert-manager está pronto para produção?

Com certeza. Ele potencializa o SSL para grandes clusters do Kubernetes em empresas e nuvens públicas.

Posso usar um certificado curinga com o ACME no Kubernetes?

Sim, mas os certificados curinga exigem a validação DNS-01, que envolve a atualização de registros DNS em vez de usar desafios HTTP. Confirme se o seu provedor de DNS oferece suporte à automação (via API) e configure o solucionador dns01 de acordo com a configuração do cert-manager.

Palavras finais

Agora você sabe como instalar um certificado ACME SSL no Kubernetes usando o cert-manager e uma autoridade de certificação compatível com o ACME. Essa configuração é totalmente automatizada e dimensionável para ambientes modernos do Kubernetes. Você obtém HTTPS seguro, renovação automática e integração perfeita com o Ingress, tudo isso sem sair do cluster.