Serviço de diagnóstico e correção de resolução DNS entre containers Docker e host (bridge, overlay, systemd‑resolved)

Por · Publicado em · 7 min de leitura

Pátio portuário visto de cima com fileiras de contêineres coloridos
Vista aérea organizada de contêineres — metáfora para containers Docker e redes Foto: Diego F. Parra / Pexels

Containers não resolvem nomes, alternam entre timeouts e respostas lentas ou falham ao acessar serviços internos? O serviço de diagnóstico e correção de resolução DNS entre containers Docker e host cobre bridge, overlay e integrações com systemd‑resolved. Investigamos a cadeia de resolução, identificamos causas e aplicamos correções seguras, com validação e orientações para evitar regressões.

O que você recebe neste serviço

O foco é restabelecer a resolução de nomes de forma previsível e estável. Atuamos no Docker, no host e nos encaminhadores, sempre com plano de validação.

O trabalho entrega um diagnóstico claro, correções aplicadas e orientações para manutenção futura.

  • Mapa da cadeia de resolução (container → 127.0.0.11 → host → upstreams)
  • Achados priorizados por impacto e risco
  • Correções em configurações do Docker, redes e resolvedor do host
  • Pull requests ou patches para Compose/Swarm quando aplicável
  • Testes de validação e checklist de regressão

Quais sintomas indicam falha de resolução entre containers e host?

Alguns sintomas apontam diretamente para problemas de DNS no Docker. Identificá-los cedo reduz o tempo de indisponibilidade.

Se você percebe um dos itens abaixo, o diagnóstico direcionado de DNS costuma acelerar a correção.

  • getaddrinfo EAI_AGAIN, timeouts intermitentes ou latência alta em chamadas HTTP
  • Serviços internos resolvem via VPN no host, mas não nos containers
  • Nomes como db, api ou .local funcionam em uma rede e falham em outra
  • Falha de resolução em overlay network entre tarefas do Swarm
  • host.docker.internal indisponível em Linux ou comportamento inconsistente
  • Conexão cai em bridge após mudanças no DNS do host

Como funciona a resolução de nomes no Docker (bridge, overlay e host)

Em redes definidas pelo usuário, o Docker expõe um resolvedor interno no 127.0.0.11. Ele resolve nomes de containers na mesma rede e encaminha domínios externos aos servidores do host.

No host Linux com systemd‑resolved, o /etc/resolv.conf pode apontar para o stub 127.0.0.53. Essa diferença entre stub e upstreams reais costuma ser a raiz de conflitos.

Em overlay (Swarm), o DNS interno fornece service discovery; escolhas de search domain e políticas da VPN afetam o resultado. IPv6 e split‑DNS exigem atenção específica.

Causas comuns e linhas de correção que aplicamos

Problemas de DNS em Docker têm padrões recorrentes. Abaixo estão causas frequentes e direções de correção que usamos conforme o caso. As mudanças são validadas antes de irem a produção.

  • /etc/resolv.conf do host aponta para 127.0.0.53: alinhar Docker ao arquivo com upstreams reais ou definir DNS explícitos
  • Search domains e ndots gerando excesso de tentativas: ajustar opções e ordem de resolução
  • VPN corporativa com split‑DNS: rotas e servidores por interface, com políticas consistentes para containers
  • host.docker.internal em Linux: mapear via host‑gateway ou extra_hosts quando necessário
  • Overlay com conflitos de nomes: padronizar nomes de serviços e isolar redes
  • Timeouts intermitentes sob carga: estabilizar MTU/routing e evitar quedas de encaminhadores
Cenário Causa provável Sinais Linha de correção
Containers não resolvem domínios externos Docker lendo stub 127.0.0.53 do host Respostas variam, ping no host funciona Fazer Docker usar upstreams reais do resolvedor do host
Serviços internos da VPN falham só no container Split‑DNS por interface No host resolve; no container, NXDOMAIN Propagar servidores e rotas corretas ao container/rede
Resolução lenta e intermitente Search domains e ndots agressivos Múltiplas tentativas antes do FQDN Ajustar opções de resolver e ordem de busca
Falha entre tasks no Swarm Conflito de nomes ou rede overlay Service A não encontra B por nome Revisar nomes, redes e DNS do cluster
Acesso ao host por nome especial indisponível Sem mapeamento host‑gateway Aplicação tenta host.docker.internal Adicionar host‑gateway ou entrada estática

Etapas do trabalho: do diagnóstico à validação

Seguimos uma sequência para reduzir risco e acelerar a causa raiz. As ações são registradas para reprodutibilidade.

A priorização considera impacto, facilidade de reversão e janelas de mudança.

  • Triagem e reprodução do erro em ambiente controlado
  • Inspeção de redes (bridge/overlay), resolv.conf e nsswitch no host e containers
  • Coleta de traces e consultas DNS de ponta a ponta
  • Plano de correção com rollback definido
  • Aplicação de mudanças e validação funcional
  • Checklist final e recomendações de prevenção

Como garantimos estabilidade após a correção?

A correção de DNS precisa sobreviver a reinicializações, atualizações e mudanças de rede. Validamos funcionalmente e deixamos guardrails de operação.

Os itens abaixo ajudam a manter previsibilidade no longo prazo.

  • Testes de resolução em CI/CD e health checks de dependências
  • Padronização de Compose/Stacks com dns, dns_search e extra_hosts quando necessário
  • Documentação de procedimentos de mudança de DNS/VPN
  • Alertas para tempo de resolução e picos de NXDOMAIN
  • Revisões periódicas quando há novas sub-redes ou domínios internos

Quanto tempo leva e o que precisamos para começar?

O tempo depende do escopo, número de redes e integrações (VPN, split‑DNS, overlay). Casos simples costumam ser rápidos; ambientes complexos exigem mais verificação.

Para iniciar, é preciso acesso ao host, aos arquivos de Compose/Stacks e possibilidade de executar testes controlados.

  • Acesso ao host e ao Docker/Swarm para inspeção
  • Arquivos docker-compose.yml ou specs de serviços
  • Informações de DNS internos/VPN e políticas de rede
  • Janela para testes e, se necessário, mudança com rollback

Perguntas frequentes

Como saber se o problema está no Docker ou no systemd‑resolved do host?

Teste a resolução dentro do container e no host para o mesmo domínio. Se funciona no host e falha no container, o encaminhamento do Docker aos upstreams do host pode estar incorreto. Inspecione o resolv.conf dos dois lados e a presença de 127.0.0.11 e 127.0.0.53.

host.docker.internal funciona em Linux?

Em muitos ambientes Linux ele não existe por padrão. Você pode mapear o host via host‑gateway ou extra_hosts no Compose. Isso expõe o IP do host ao container de forma previsível e evita dependência de nomes especiais.

Por que em overlay network um serviço não encontra outro por nome?

Geralmente há conflito de nomes, rede incorreta ou serviço não exposto na mesma rede overlay. Revise nomes de serviços, redes associadas e o DNS interno do cluster para garantir que o nome seja resolvido para o VIP ou tarefa correta.

VPN corporativa pode quebrar DNS dos containers?

Sim, especialmente em cenários de split‑DNS. O host recebe servidores por interface, mas os containers não. É preciso propagar esses servidores às redes do Docker ou ajustar o resolvedor do host para encaminhar corretamente.

O que muda ao usar IPv6 com Docker e DNS?

Você precisa garantir prefixos, roteamento e servidores DNS IPv6 válidos. Falhas comuns incluem ausência de rotas ou de DNS AAAA. Valide resolução AAAA e conectividade IPv6. Ajustes de MTU também podem evitar timeouts aparentes de DNS.

Pronto para resolver DNS entre seus containers e o host?

Vamos diagnosticar a cadeia de resolução e aplicar correções seguras para bridge, overlay e systemd‑resolved, com validação e rollback definidos.

Quero um diagnóstico de DNS em Docker

Veja também