Conteúdo

Tutorial de docker network: crie redes, conecte contêineres e use aliases

Q: Por que não consigo conectar usando o nome do contêiner na rede padrão?

A rede bridge padrão não oferece resolução de nomes. Redes personalizadas (docker network create) e redes criadas pelo Compose resolvem automaticamente os IPs usando nomes de contêineres e serviços.

Q: O que é uma rede --internal?

Em uma rede criada com --internal, os contêineres podem se comunicar entre si, mas não conseguem acessar redes externas. Ela é adequada para serviços como bancos de dados que não precisam acessar a internet.

docker network gerencia redes do Docker. Para saber mais sobre redes, a rede padrão e a diferença entre redes padrão e personalizadas, consulte Redes e comunicação entre contêineres.

Subcomandos

Comando	Descrição
`docker network ls`	Lista as redes
`docker network create nome`	Cria uma rede
`docker network inspect nome`	Exibe detalhes, incluindo os contêineres conectados e seus IPs
`docker network connect rede contêiner`	Conecta um contêiner em execução à rede
`docker network disconnect rede contêiner`	Desconecta um contêiner da rede
`docker network rm nome...`	Remove redes (não é possível removê-las enquanto houver contêineres conectados)
`docker network prune`	Remove todas as redes personalizadas que não estão sendo usadas por contêineres

Opções comuns de docker network create:

Opção	Descrição
`-d, --driver`	Driver; o padrão é `bridge`
`--subnet`	Sub-rede, por exemplo, `172.30.0.0/24`
`--gateway`	IP do gateway
`--ip-range`	Aloca IPs de um intervalo específico da sub-rede
`--internal`	Impede o acesso a redes externas
`--ipv6`	Ativa o IPv6
`--label`	Adiciona um rótulo

Opções comuns de docker network connect: --alias alias, --ip IP-fixo.

Exemplo

$ docker network ls
NETWORK ID     NAME      DRIVER    SCOPE
58a492b7c501   bridge    bridge    local
720ed2121dc4   host      host      local
07184d7358b0   none      null      local

$ docker network create appnet
c94640ca44aae05529e21bfe93c1fd957f70ca0d4bcc40209e91aa434dbc65e4

$ docker network create --subnet 172.30.0.0/24 fixednet
320f2c205537c3957304a23459143038a39e3b3a9323edc3bb5cec13688a1cf5

$ docker run -d --name api --network appnet --network-alias backend nginx:1.30-alpine
a40d4c075b88d806529bc6b58f9e1a90f6bc918eed0af6a852e3e8983f3e8e7a

$ docker run --rm --network appnet alpine:3.23 sh -c "ping -c1 -W1 api >/dev/null && echo api ok; ping -c1 -W1 backend >/dev/null && echo backend ok"
api ok
backend ok

$ docker network inspect -f "{{range .Containers}}{{.Name}} {{.IPv4Address}}{{end}}" appnet
api 172.19.0.2/16

Há três redes padrão: bridge (padrão), host (usa diretamente a rede do host) e none (sem rede).
Crie appnet e fixednet, que usa uma sub-rede específica.
O contêiner api se conecta a appnet e ganha o nome adicional backend com --network-alias. Outros contêineres na mesma rede podem acessá-lo usando api ou backend.

$ docker network connect fixednet api

$ docker inspect -f "{{range \$k, \$v := .NetworkSettings.Networks}}{{\$k}}={{\$v.IPAddress}} {{end}}" api
appnet=172.19.0.2 fixednet=172.30.0.2

$ docker network disconnect fixednet api

$ docker network rm appnet
Error response from daemon: error while removing network: network appnet has active endpoints (name:"api" id:"df7a1c38176a")
exit status 1

$ docker rm -f api
api

$ docker network rm appnet fixednet
appnet
fixednet

network connect também conecta o api em execução a fixednet. Assim, ele tem duas interfaces de rede e dois IPs: 172.19.0.2 em appnet e 172.30.0.2, da sub-rede especificada, em fixednet. Essa é uma forma de permitir que um contêiner se comunique com dois grupos de serviços ao mesmo tempo, por exemplo, um proxy reverso conectado às redes de frontend e backend.
A remoção de uma rede falha enquanto há contêineres conectados: network appnet has active endpoints. Remova primeiro o contêiner (ou use disconnect) para então remover a rede.

Capítulos relacionados

Redes e comunicação entre contêineres
Nginx e proxy reverso
Sintaxe de compose.yaml: networks no Compose

Exercícios

Exercício: crie uma rede private com --internal, inicie um contêiner conectado a ela e confirme que o contêiner não consegue acessar redes externas (por exemplo, com ping -c1 1.1.1.1).

Resposta

docker network create --internal private
docker run --rm --network private alpine:3.23 ping -c1 -W2 1.1.1.1

A saída observada foi ping: sendto: Network unreachable: o contêiner não tem uma rota para redes externas. Depois do exercício, execute docker network rm private.

Perguntas frequentes

Por que não consigo conectar usando o nome do contêiner na rede padrão?

A rede bridge padrão não oferece resolução de nomes. Redes personalizadas (docker network create) e redes criadas pelo Compose resolvem automaticamente os IPs usando nomes de contêineres e serviços.

Para que serve --network-alias?

Ele dá outro nome ao contêiner na rede. Por exemplo, você pode chamar o contêiner de api-v2, enquanto outros serviços continuam se conectando a backend; ou usar o mesmo alias em vários contêineres para distribuir solicitações com facilidade.

O que é uma rede --internal?

Em uma rede criada com --internal, os contêineres podem se comunicar entre si, mas não conseguem acessar redes externas. Ela é adequada para serviços como bancos de dados que não precisam acessar a internet.

Atualizado 14 de outubro de 2026