Infra Assinado Tem Hifen

Como lidar com infra assinado que tem hifen

A maioria dos erros que vejo em containers e Kubernetes não são bugs — é gente aplicando regras de nomenclatura do jeito errado. Quando você trabalha com infraestrutura assinada (certificates, ingress TLS, admission webhooks, tudo que passa por validação), o hífen aparece como obstáculo em dois lugares que quase ninguém prepara com antecedência. Sim, tem. O problema não é o hífen em si. O hífen é permitido em nomes de recursos Kubernetes dentro de certos limites. O problema é que os certificados X.509 e os CN/SANs que acompanham essas assinaturas têm regras diferentes, e as ferramentas não avisam quando você erra até o deploy falhar em produção. O campo DNS label no Kubernetes aceita letras minúsculas, números e hífen. O hífen não pode ser primeiro ou último caractere. Isso é documentado em lugar visível. O que pouca gente lê é que o certificado gerado ou vinculado a esse recurso segue regras do RFC 1035 para DNS, mas as autoridades emissoras de certificado (CA) também impõem restrições no Subject Alternative Name (SAN) que podem não ser óbvias.

Eu passei três horas numa sexta à noite corrigindo um ingress que simplesmente não carregava o TLS. O erro era um Certificado com SAN contendo dois subdomínios com hífen na posição errada. O ingress estava tecnicamente válido. O certificado também parecia ok. Mas o kube-proxy não conseguia montar a regra de roteamento porque o nome do recurso Secret tinha um hífen na frente do domínio no campo DNSName da Certificate. A mensagem de erro dizia algo genérico sobre "failed to get certificate". Se você não sabe onde olhar, gasta mais tempo do que deveria. A correção foi simples, mas o diagnóstico não. Eu mudei o padrão do cert-manager para gerar SANs a partir do campo spec.dnsNames do recurso Certificate, garantindo que cada entrada tivesse pelo menos um caractere antes e depois do hífen. Depois atualizei o valor do campo spec.secretName do ingress para bater exatamente com o nome do Secret que o certificado criava. Deu certo na primeira aplicação.

Regras práticas para infra assinado com hífen

Vamos direto ao que funciona. Não vou listar conceitos teóricos. Vou dizer o que você precisa verificar na ordem correta, porque a ordem importa. O fluxo de assinatura em Kubernetes passa por três etapas. Se uma falhar, as seguintes não acontecem, e o erro fica escondido. A ordem é: nome do recurso nome do Secret SANs do certificado regra de ingress (ou equivalentes em outras ferramentas). Verifique sempre nessa sequência. O nome do recurso.infra assinado tem hifen deve respeitar a regex [a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?. Isso limita o nome a no máximo 63 caracteres, sem hífen no início ou no final, e apenas minúsculas. Se seu nome vem de um chart Helm ou de um arquivo Terraform, verifique se a variável que gera o nome aplica essa sanitização automaticamente. Muitos não aplicam.

O Secret que armazena o par de chaves precisa ter exatamente o mesmo nome definido no recurso Certificate como spec.secretName. Eu já vi gente usar variáveis diferentes nos arquivos helm-values.yaml e no template do Certificate, resultando em dois Secrets e o ingress apontando para um que nunca foi preenchido com o certificado correto. Os SANs do certificado precisam seguir o RFC 1035 para labels DNS. Cada label pode ter até 63 caracteres, começando e terminando com alfanumérico, e só pode conter letras, números e hífen. Domínios completos como meu-app.svc.cluster.local são válidos. Domínios como -app.teste.com não são. Se você estiver usando namespaces customizados ou subdomínios gerados dinamicamente, garanta que o gerador respeite essas regras.

Provedores de certificado e surpresas comuns

O cert-manager com o issuer Let's Encrypt é o padrão da indústria. Ele gera certificados via ACME, e o desafio HTTP-01 ou DNS-01 precisa corresponder exatamente ao domínio no SAN. Se o domínio tem hífen, o registro TXT do desafio também precisa ter o hífen exatamente como está. Eu já perdi tempo pensando que o desafio falhava por causa do provedor DNS, quando na verdade o problema era um hífen duplicado na hora de construir o nome do record. A solução foi ajustar a annotations do Gateway no provedor DNS para escapar corretamente o hífen, usando a sintaxe do próprio provedor. Para Route53, por exemplo, o nome do record precisa ser algo como _acme-challenge.meu-app.exemplo.com., com ponto final. Se você usa issuers internos com PKI (como o issuer Vault ou um operador de certificates personalizado), a regra muda. O nome do certificado gerado pelo Vault segue o padrão do caminho da API, não o nome do recurso Kubernetes. Se o caminho contém um hífen e o nome do Secret também contém um hífen em posição diferente, o mapeamento quebra. Anote o caminho exato e teste com um curl antes de aplicar o manifest inteiro.

Admission webhooks e validadores

Webhooks de validação também são infra assinada. O webhook aponta para um service que tem um certificado TLS. Se o CN ou SAN desse certificado não incluir o nome completo do service no namespace (no formato nome-servico.namespace.svc), o kube-apiserver rejeita a conexão. O erro é silencioso: o webhook simplesmente não responde, e a validação cai em timeout. Meu workaround foi adicionar uma annotation no Service do webhook com o campo webhook.cert-manager.io/issue-extra-san listando todos os SANs necessários, incluindo o fqdn completo. Assim o certificado gerado cobre todas as formas que o apiserver pode usar para conectar. Use estes comandos na ordem. Eles levam menos de dois minutos e evitam dor de cabeça posterior. Para checar o recurso Certificate:

kubectl describe certificate nome-do-cert -n seu-namespace Olhe o campo Events. Se houver algo como "Failed to issue certificate" ou "waiting for certificate request", anote a causa raiz. Não ignore. Para checar o Secret resultante:

kubectl get secret nome-do-secret -n seu-namespace -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -text Verifique o campo Subject Alternative Name. Ele deve conter exatamente os domínios que você espera, sem hífen solto no início ou no final de qualquer label. Para checar o ingress:

kubectl describe ingress nome-do-ingress -n seu-namespace O campo TLS deve listar o mesmo nome de Secret que você verificou no passo anterior. Se não listar, o ingress não está usando o certificado correto.

Pegadinhas que ninguém conta

Primeiro: renomear um recurso que já tem certificado associado não renova o certificado automaticamente. O cert-manager cria um novo pedido de certificate, mas o Secret antigo continua existindo até que o novo seja emitido. Se você renomeou o ingress e o certificado ainda referencia o nome antigo, o novo ingress aponta para um Secret vazio. Verifique sempre com kubectl get certificate e kubectl get secret antes de fazer rename em produção. Segundo: o tempo de propagação do DNS para desafios DNS-01 varia entre provedores. Route53 costuma propagar em segundos. Cloudflare em cerca de um minuto. AWS Route53 pode levar até 30 segundos, mas o cert-manager já espera por padrão 60 segundos. Se seu provedor for lento, aumente o annotation cert-manager.io/acme-dns01-check-propagation para 120 ou 180 segundos. Isso evita retries desnecessários que consomem cota do Let's Encrypt. Terceiro: o padrão de naming de services no Kubernetes inclui automaticamente o sufixo do namespace quando você resolve via ClusterIP. Um service chamado web-api no namespace prod é resolvido como web-api.prod.svc.cluster.local. Se o certificado só tem o SAN web-api.prod, a conexão do tipo host interno pode falhar. Adicione o fqdn completo ao SAN para evitar isso.

Quando infra assinado com hífen simplesmente não funciona

Existem cenários em que o hífen é impossível de usar sem reestruturar o ambiente. Se você precisa de compatibilidade com sistemas legados que fazem parsing de nomes de host e não suportam RFC 1035 completo, o hífen vai quebrar em algum ponto do pipeline. Nesse caso, a solução mais prática é usar underscores no nome interno do recurso Kubernetes e mapeá-los para hífens no DNS externo, mas isso exige um controlador de DNS personalizado ou um proxy que faça a tradução. Eu já vi times adotarem esse padrão em clusters On-premise que precisavam coexistir com sistemas mainframe, mas é uma exceção, não a regra. Outro caso é quando a autoridade certificadora negativa explicitamente domain labels com hífen. Algumas CAs empresariais internas têm políticas que rejeitam SANs com certos padrões. O erro volta como "invalid identifier" sem muitos detalhes. Nesses casos, o workaround é pedir uma exceção à equipe de segurança ou usar um issuer alternativo que não tenha essa restrição. O que funciona na prática é seguir a ordem de validação, testar cada camada isoladamente antes de avançar, e não confiar em nomes gerados automaticamente sem revisar o resultado final. O hífen em si não é o vilão. O vilão é aplicar regras de um contexto em outro contexto sem verificar.