Rede entre contêineres Docker na prática: como conectar contêineres Web e de banco de dados corretamente

Era sexta-feira, 15h, e eu estava prestes a colocar meu ambiente de desenvolvimento local em contêineres, bastante satisfeito comigo mesmo: o contêiner do MySQL tinha iniciado, a aplicação Node.js também estava rodando, e só faltava conectá-los. Atualizei a página no navegador e recebi um erro 500, acompanhado de uma enxurrada de mensagens “Connection refused” nos logs.

Fiquei sem entender nada. Afinal, os dois contêineres estavam em execução. Tentei executar um ping usando o nome do contêiner MySQL e recebi “unknown host”. Então testei pelo endereço IP e, para minha surpresa, funcionou! A aplicação também conseguiu se conectar ao banco de dados. Aliviado, fiz o commit, desliguei o computador e fui embora.

Na segunda-feira, veio o desastre: a aplicação estava fora do ar outra vez. Ao investigar, descobri que o IP do contêiner MySQL havia mudado depois da reinicialização, de 172.17.0.2 para 172.17.0.3. Foi frustrante. Eu teria de alterar o arquivo de configuração sempre que reiniciasse o contêiner?

Se você já passou por algo parecido, este artigo é para você. Passei uma tarde estudando o funcionamento das redes do Docker até entender a maneira correta de conectar contêineres. A seguir, vou mostrar:

• Por que o ping pelo nome do contêiner falha e qual é a causa real
• Quais são as limitações da rede padrão do Docker
• Como uma rede personalizada resolve esses problemas
• Um passo a passo completo para que seus contêineres se acessem pelo nome
• Algumas dicas avançadas e práticas recomendadas

Por que o ping pelo nome do contêiner falha?

Limitações da rede padrão do Docker

A causa do problema está na configuração de rede padrão do Docker. Quando você inicia um contêiner sem especificar uma rede, o Docker o conecta automaticamente à rede bridge padrão, ou seja, à ponte docker0.

Essa rede padrão tem uma limitação importante: ela só permite a comunicação por endereço IP e não resolve nomes de contêiner.

O que isso significa? Na rede padrão:

• ✅ Você pode acessar outro contêiner pelo IP, por exemplo, com ping 172.17.0.2
• ❌ Mas não pode acessá-lo pelo nome, pois ping mysql-container não funciona

Isso acontece porque a rede padrão não tem um serviço DNS integrado. É como um celular sem agenda de contatos: você consegue ligar se memorizar o número, isto é, o IP, mas não encontra alguém pelo nome, ou seja, pelo nome do contêiner.

Para piorar, sempre que um contêiner reinicia, o Docker atribui outro endereço IP. Hoje você pode acessar o MySQL em 172.17.0.2; amanhã, após uma reinicialização, ele pode estar em 172.17.0.3, invalidando o IP definido na configuração da aplicação.

Usei os comandos abaixo para confirmar esse comportamento:

# Inicia um contêiner MySQL usando a rede padrão
docker run -d --name mysql-demo \
  -e MYSQL_ROOT_PASSWORD=123456 \
  mysql:8.0

# Inicia um contêiner BusyBox para testar a rede
docker run -it --name test-box busybox sh

# Dentro do contêiner test-box, tenta executar ping pelo nome do contêiner MySQL
/ # ping mysql-demo
ping: bad address 'mysql-demo'  # ← Falha na resolução

# Consulta o IP do contêiner MySQL
docker inspect mysql-demo | grep IPAddress
# "IPAddress": "172.17.0.2"

# O ping pelo IP funciona
/ # ping 172.17.0.2
PING 172.17.0.2 (172.17.0.2): 56 data bytes
64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.123 ms

Como você pode ver, o ping pelo nome do contêiner falha, e apenas o IP funciona.

O parâmetro —link foi descontinuado

Talvez você já tenha visto o parâmetro --link em tutoriais antigos. Essa foi uma das primeiras soluções oferecidas pelo Docker. O uso era assim:

docker run --link mysql-demo:mysql -d my-app

Com isso, o contêiner my-app realmente consegue acessar o contêiner mysql-demo pelo nome “mysql”. Porém, o Docker já deixou claro que não recomenda o uso de —link e que esse recurso será removido em versões futuras.

Por que ele foi descontinuado? Os principais motivos são:

1. Conexão unidirecional: somente my-app consegue acessar mysql; mysql não consegue acessar my-app no sentido inverso
2. Manutenção difícil: à medida que aumenta o número de contêineres, a configuração de —link fica muito complexa
3. Funcionalidade limitada: não oferece gerenciamento de rede flexível em cenários com vários contêineres

Portanto, se você ainda usa —link, está na hora de migrar para o método atual.

Rede personalizada: a maneira correta de conectar contêineres

Vantagens de uma rede personalizada

A partir da versão 1.12, o Docker passou a oferecer o comando docker network, que permite criar redes personalizadas. Essa é a maneira recomendada oficialmente para conectar contêineres.

Em comparação com a rede padrão, uma rede bridge personalizada oferece estas vantagens:

1. Resolução DNS automática: o Docker executa um servidor DNS integrado na rede personalizada. Os nomes dos contêineres são resolvidos automaticamente para seus respectivos endereços IP. É como se o Docker adicionasse uma “agenda de contatos” à rede.

2. Isolamento de rede: por padrão, contêineres em redes personalizadas diferentes ficam isolados e não conseguem se acessar. Assim, você pode colocar o frontend, o backend e o banco de dados em redes distintas para aumentar a segurança.

3. Mais facilidade de manutenção: se o IP mudar após a reinicialização de um contêiner, não há problema, pois você usa o nome do contêiner e o DNS atualiza o registro automaticamente.

4. Suporte a várias redes: um mesmo contêiner pode participar de várias redes ao mesmo tempo, permitindo topologias mais complexas.

Sinceramente, no começo também achei as redes do Docker complicadas. Depois de entender esses pontos, tudo ficou muito mais claro.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Como criar uma rede personalizada

O comando para criar uma rede personalizada é muito simples:

# Forma mais simples: informe apenas o nome da rede
docker network create my-app-net

# Versão com todos os parâmetros
docker network create \
  --driver bridge \         # Tipo de driver de rede; bridge é o padrão
  --subnet 172.20.0.0/16 \  # Faixa de IP personalizada (opcional)
  --gateway 172.20.0.1 \    # Gateway personalizado (opcional)
  my-app-net                # Nome da rede

Na maioria dos casos, a primeira opção é suficiente. O Docker atribui automaticamente uma faixa de IP que não esteja em conflito.

Após criar a rede, você pode consultar seus detalhes com este comando:

docker network inspect my-app-net

O resultado mostra as configurações da rede, incluindo a faixa de IP, o gateway e os contêineres conectados.

Como adicionar um contêiner a uma rede personalizada

Há duas formas de adicionar um contêiner a uma rede personalizada:

Opção 1: indicar a rede ao iniciar o contêiner (recomendada)

docker run -d \
  --name mysql-demo \
  --network my-app-net \  # ← Parâmetro essencial
  -e MYSQL_ROOT_PASSWORD=123456 \
  mysql:8.0

Opção 2: conectar à rede um contêiner que já está em execução

# Considerando que o contêiner já esteja em execução
docker network connect my-app-net existing-container

A primeira opção é a mais recomendada porque resolve tudo em uma única etapa. A segunda é útil quando você deseja migrar um contêiner existente para uma nova rede.

Exemplo prático: uma aplicação Web acessando um banco de dados MySQL

Chega de teoria. Agora vamos colocar tudo em prática. Vou usar um cenário real: criar um contêiner para uma aplicação Node.js e conectá-lo a um contêiner de banco de dados MySQL.

Definição do cenário

Nosso objetivo é:

• Ter um contêiner MySQL chamado mysql-server, executado em uma rede personalizada
• Ter um contêiner da aplicação Node.js chamado node-app, também conectado à mesma rede
• Fazer a aplicação se conectar ao banco de dados pelo nome do contêiner, “mysql-server”, e não pelo IP

Passo a passo completo

Etapa 1: crie uma rede personalizada

docker network create my-app-net

Após executar o comando, você verá um ID de rede parecido com este:

a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890

Isso indica que a rede foi criada com sucesso.

Etapa 2: inicie o contêiner MySQL e conecte-o à rede

docker run -d \
  --name mysql-server \
  --network my-app-net \
  -e MYSQL_ROOT_PASSWORD=my-secret-pw \
  -e MYSQL_DATABASE=myapp_db \
  mysql:8.0

Explicação dos parâmetros:

• --name mysql-server: atribui um nome ao contêiner; esse nome será usado como host para acessar o banco de dados
• --network my-app-net: conecta o contêiner à rede que acabamos de criar
• -e MYSQL_ROOT_PASSWORD: define a senha do usuário root
• -e MYSQL_DATABASE: cria um banco de dados inicial

Etapa 3: inicie o contêiner da aplicação e conecte-o à rede

Neste exemplo, uso uma aplicação Node.js simples. Você pode adaptar os parâmetros às suas necessidades:

docker run -d \
  --name node-app \
  --network my-app-net \
  -p 3000:3000 \
  -e DB_HOST=mysql-server \
  -e DB_USER=root \
  -e DB_PASSWORD=my-secret-pw \
  -e DB_NAME=myapp_db \
  my-node-app:latest

Observe DB_HOST=mysql-server: o valor é o nome do contêiner, não um endereço IP!

Etapa 4: use o nome do contêiner para conectar ao banco de dados no código da aplicação

Exemplo em Node.js:

const mysql = require('mysql2');

// Usa variáveis de ambiente para configurar a conexão com o banco de dados
const connection = mysql.createConnection({
  host: process.env.DB_HOST,      // O valor é 'mysql-server' (nome do contêiner)
  user: process.env.DB_USER,      // O valor é 'root'
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME
});

connection.connect((err) => {
  if (err) {
    console.error('Falha ao conectar ao banco de dados:', err);
    return;
  }
  console.log('Conexão com o banco de dados MySQL estabelecida!');
});

O ponto principal é que host usa o nome do contêiner, mysql-server. O DNS do Docker o resolve automaticamente para o IP atual do contêiner MySQL.

Etapa 5: verifique a conectividade

Podemos entrar no contêiner node-app e testar manualmente a conexão de rede:

# Entra no contêiner da aplicação
docker exec -it node-app sh

# Executa ping pelo nome do contêiner MySQL
/ # ping mysql-server
PING mysql-server (172.20.0.2): 56 data bytes
64 bytes from 172.20.0.2: seq=0 ttl=64 time=0.089 ms
64 bytes from 172.20.0.2: seq=1 ttl=64 time=0.096 ms

Funcionou! O nome do contêiner foi resolvido e o ping respondeu normalmente.

Você também pode usar nslookup para consultar a resolução DNS:

/ # nslookup mysql-server
Server:    127.0.0.11  # ← Servidor DNS integrado do Docker
Address:   127.0.0.11:53

Name:      mysql-server
Address:   172.20.0.2  # ← Resolvido automaticamente para o IP do contêiner MySQL

Percebeu? O Docker executa um servidor DNS, 127.0.0.11, na rede personalizada para resolver nomes de contêiner.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Agora, mesmo que você reinicie o contêiner MySQL e seu IP mude, a aplicação não será afetada, pois o DNS atualiza o registro automaticamente.

Dicas para solucionar problemas

Se algo não funcionar, estes comandos ajudam na investigação:

1. Consulte os detalhes da rede

docker network inspect my-app-net

O comando retorna informações detalhadas em JSON, incluindo:

• A faixa de IP e o gateway da rede
• A lista de contêineres conectados
• O IP de cada contêiner nessa rede

2. Consulte a configuração de rede do contêiner

docker inspect mysql-server | grep -A 20 Networks

Você verá a quais redes o contêiner está conectado e qual IP ele usa em cada uma.

3. Verifique os logs dos contêineres

docker logs node-app
docker logs mysql-server

Normalmente, os logs exibem detalhes dos erros de conexão.

Checklist de problemas comuns:

Dicas avançadas e práticas recomendadas

Cenário com várias redes: separação entre frontend e backend

Em projetos reais, pode ser necessário criar uma topologia de rede mais complexa. Por exemplo, você pode separar frontend, backend e banco de dados em diferentes camadas de rede:

# Cria duas redes
docker network create frontend-net  # Rede do frontend
docker network create backend-net   # Rede do backend

# O contêiner do frontend se conecta apenas à frontend-net
docker run -d --name nginx \
  --network frontend-net \
  -p 80:80 \
  nginx:latest

# O backend da API se conecta às duas redes, pois frontend e backend precisam acessá-lo
docker run -d --name api-server \
  --network frontend-net \
  my-api:latest

docker network connect backend-net api-server

# O banco de dados se conecta apenas à backend-net; o frontend não consegue acessá-lo, o que aumenta a segurança
docker run -d --name postgres \
  --network backend-net \
  -e POSTGRES_PASSWORD=secret \
  postgres:14

Quais são as vantagens dessa arquitetura?

• O contêiner nginx do frontend consegue acessar api-server, mas não o banco de dados
• api-server consegue acessar o banco de dados
• O banco de dados fica totalmente isolado e somente o backend pode acessá-lo, o que aumenta a segurança

É assim que implantamos os projetos da nossa empresa, e a segurança melhorou bastante.

Simplifique o gerenciamento com Docker Compose

Se sua aplicação tiver muitos contêineres, gerenciá-los manualmente será trabalhoso. É aí que entra o Docker Compose.

Crie um arquivo docker-compose.yml:

version: '3.8'

services:
  # Serviço de banco de dados MySQL
  mysql:
    image: mysql:8.0
    container_name: mysql-server
    environment:
      MYSQL_ROOT_PASSWORD: my-secret-pw
      MYSQL_DATABASE: myapp_db
    networks:
      - app-network
    volumes:
      - mysql-data:/var/lib/mysql

  # Serviço da aplicação Node.js
  app:
    image: my-node-app:latest
    container_name: node-app
    ports:
      - "3000:3000"
    environment:
      DB_HOST: mysql  # ← Use o nome do serviço aqui, não container_name
      DB_USER: root
      DB_PASSWORD: my-secret-pw
      DB_NAME: myapp_db
    networks:
      - app-network
    depends_on:
      - mysql

# Define a rede
networks:
  app-network:
    driver: bridge

# Define o volume de dados
volumes:
  mysql-data:

Depois, inicie todos os serviços com um único comando:

docker-compose up -d

O Docker Compose faz tudo automaticamente:

• Cria a rede app-network
• Inicia todos os contêineres e os conecta à rede
• Configura a resolução DNS entre os contêineres
• Inicia os serviços na ordem definida por depends_on, primeiro mysql e depois app

Parar e limpar os recursos também é simples:

# Para todos os serviços
docker-compose down

# Para os serviços e exclui os volumes de dados
docker-compose down -v

Sinceramente, hoje quase não gerencio contêineres manualmente. Uso Docker Compose para tudo, e a produtividade é muito maior.

Visão geral de outros modos de rede

Além do modo bridge, o Docker oferece outros modos de rede para diferentes cenários:

Na maioria dos casos, uma rede bridge personalizada é suficiente. O modo host é indicado quando há exigências muito altas de desempenho de rede, como em sistemas de negociação de alta frequência. O modo overlay é a tecnologia de base de orquestradores como Swarm e K8s e, em geral, não precisa ser configurado manualmente.

Perguntas frequentes

P1: Por que o acesso funciona por IP, mas não pelo nome do contêiner?

R: Porque os contêineres estão na rede bridge padrão, a docker0. Essa rede não tem um serviço DNS e não resolve nomes de contêiner. A solução é criar uma rede personalizada e adicionar os contêineres a ela.

P2: Ainda posso usar —link?

R: Embora ainda funcione, o Docker não recomenda mais seu uso, e o recurso será removido em versões futuras. Migre para uma rede personalizada assim que possível: ela oferece mais recursos e está alinhada à evolução da plataforma.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

P3: Uma rede personalizada afeta o desempenho?

R: Praticamente não. Tanto a rede personalizada quanto a rede padrão usam o modo bridge e têm a mesma implementação subjacente; a principal diferença é a resolução DNS. A diferença de desempenho pode ser ignorada.

P4: Como um contêiner acessa a internet?

R: Por padrão, contêineres em redes bridge acessam a internet por NAT. Se o acesso não funcionar, verifique as regras de iptables do Docker ou a configuração de rede do host.

P5: Como migrar um contêiner existente para uma rede personalizada?

R: Em duas etapas:

# 1. Conecta o contêiner à nova rede
docker network connect my-app-net old-container

# 2. Opcional: desconecta o contêiner da rede padrão
docker network disconnect bridge old-container

Ainda assim, é mais recomendável recriar o contêiner e conectá-lo diretamente à rede personalizada com o parâmetro --network.

P6: O nome de um contêiner pode ter letras maiúsculas?

R: Pode, mas não é recomendado. As especificações de DNS sugerem letras minúsculas, números e hífens, uma combinação mais compatível e menos sujeita a problemas.

P7: Um contêiner pode participar de várias redes ao mesmo tempo?

R: Sim! Essa é justamente uma das grandes vantagens das redes personalizadas. Você pode usar docker network connect para conectar um contêiner a várias redes e criar topologias complexas.

Conclusão

Vamos recapitular os pontos principais:

Primeira etapa: entenda a causa do problema

• A rede padrão do Docker não resolve nomes de contêiner e só permite acesso por IP
• O IP muda quando o contêiner reinicia, interrompendo a conexão
• O parâmetro —link foi descontinuado e não deve mais ser usado

Segunda etapa: crie uma rede personalizada

docker network create my-app-net

Terceira etapa: conecte os contêineres à rede e use seus nomes na comunicação

# Indica a rede ao iniciar o contêiner
docker run -d --name mysql-server --network my-app-net mysql:8.0

# Usa o nome do contêiner na aplicação
host: 'mysql-server'  // Não é um IP, e sim o nome do contêiner

Além de simples, esse método é a prática recomendada oficialmente pelo Docker. Suas aplicações em contêineres ficam mais estáveis e fáceis de manter.

Se você trabalha com microsserviços ou projetos com vários contêineres, recomendo:

1. Comece agora: migre seu projeto atual para uma rede personalizada e elimine IPs fixos da configuração

2. Experimente o Compose: se houver mais de três contêineres, o Docker Compose torna o gerenciamento muito mais simples

3. Aprofunde seus conhecimentos: estude redes overlay e o modelo de rede do Kubernetes; esses são fundamentos da computação nativa em nuvem

Por fim, redes de contêineres realmente têm uma curva de aprendizado. Depois que você domina o assunto, porém, o Docker fica muito mais fácil de usar. Já está com vontade de testar? Abra o terminal e crie agora sua primeira rede personalizada!

Se tiver alguma dúvida, deixe um comentário. Vou tentar responder.