Skip to content
Blog

Connecting One Container to Multiple Docker Networks

One container, several networks: connect running containers with docker network connect, repeat --network at run time, and scope aliases per network in Compose or the CLI.

Published on • November 19, 2026

AI Assistant

A proxy needs one foot in the frontend and one in the backend. A migration service must straddle the old and new database networks. Docker’s model for this is the same as a physical host with two NICs — and once you understand that analogy, docker network connect, repeated --network flags, and per-network aliases all behave predictably. The networking overview puts it simply: connecting a container to a network “can be compared to connecting an Ethernet cable to a physical host.”

Connect a running container

The core mechanic needs no recreation — attach to a live container:

docker network create demo-tier-front
docker network create --subnet 10.90.0.0/24 demo-tier-back
docker run -dit --name proxy1 --network demo-tier-front alpine ash
docker network connect --ip 10.90.0.20 --alias api --alias gateway \
  demo-tier-back proxy1

docker network connect accepts several options (from the connect reference):

OptionWhat it does
--aliasNetwork-scoped alias; repeatable, valid only on this network
--ip / --ip6Static address on this network (must fall inside its subnet)
--gw-priorityHighest value provides the default gateway; accepts negatives
--driver-optDriver options for the network, e.g. per-interface sysctls
--linkLegacy link to another container with a preferred alias
--link-local-ipLink-local address for the container

Get the subnet wrong and the daemon rejects the address with no configured subnet contains IP address 10.90.0.10 — the address must belong to the target network, which is exactly why you pin subnets first (Custom subnets, IPAM, and static container IPs). Networks need not share a type: the docs note you can attach one container to a bridge and an overlay network.

At run time: repeat the —network flag

Older tutorials say docker run takes one network. Current Docker disagrees — the docker run reference says it directly: “To connect the container to more than one network, repeat the --network option.”

docker run -dit --name dual1 \
  --network demo-tier-front --network demo-tier-back \
  alpine ash
docker exec dual1 ip route
default via 10.90.0.1 dev eth0
10.90.0.0/24 dev eth0 scope link  src 10.90.0.2
192.168.80.0/20 dev eth1 scope link  src 192.168.80.3

Two interfaces, two subnets, one container. For per-network options there’s an extended syntax — comma-separated key=value pairs on the flag itself, mirroring what network connect offers:

docker run -dit --name dual2 \
  --network name=demo-tier-front,gw-priority=1 \
  --network name=demo-tier-back \
  alpine ash

The documented keys are name (mandatory), alias, ip, ip6, mac-address, link-local-ip, driver-opt, and gw-priority. The docs’ own example combines two of them: --network name=my-net1,ip=192.0.2.42 --network name=my-net2,ip=192.0.3.42.

One planning rule while we’re here: don’t let the two networks’ CIDRs overlap. Docker installs routes per interface, but an address that falls inside both ranges routes by whichever interface the kernel picks — “container A reaches the database, container B doesn’t, and nothing in the logs explains it” is the classic symptom. Pin non-overlapping subnets at creation and overlap becomes a mistake you can’t make.

The Compose path

Repeating flags works, but stacks are declared in Compose — the networking guide’s example is the canonical two-tier shape, where app is the only service that sees both networks:

services:
  proxy:
    build: ./proxy
    networks:
      - frontend
  app:
    build: ./app
    networks:
      - frontend
      - backend
  db:
    image: postgres:latest
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge

Each service joins the networks it lists; membership is the ACL. Compose also gives every service its network-scoped aliases automatically (the service name), which is the declarative version of --alias.

Dual-homed patterns

Two shapes cover most uses:

  • The proxy/edge pattern. Something internet-facing sits on both networks and forwards to peers reachable only on the internal one. The proxy’s dual membership is the architecture — everything else stays single-homed.
  • The strangler-fig migration. During a database migration, a bridge container joins the old network and the new one, reading from old-db and writing to new-db, until cutover. Then you disconnect it and delete the old network. No application changes, no IP hardcoding — just membership changes.

The discipline in both: the dual-homed container is the only path between networks. If every service joins both networks, you’ve built one flat network with extra steps.

When you want no second interface at all

Sometimes the goal isn’t two networks but one shared namespace. The networking overview calls it container networking: docker run --network container:proxy sidecar puts the sidecar in proxy’s stack — same IP, same ports, localhost to localhost, nothing to route. The docs list what you surrender: --publish, --hostname, --dns, --mac-address, and --expose are unsupported in container: mode. It’s the right tool for a log shipper or a mesh sidecar riding along with one process, and the wrong one for anything that needs its own addressable interface — which is what the networks above are for.

Name resolution is scoped per network

Embedded DNS answers with the networks that container is attached to — nothing more. Verified on a host with one container on network A only, one on B only, and one on both:

docker exec sc-b getent hosts sc-a      # exit 2 — sc-a is on another network
docker exec sc-ab getent hosts sc-a sc-b
172.30.0.2        sc-a
172.31.0.2        sc-b

Aliases are scoped the same way: --alias api on the back network resolves for peers on the back network, and doesn’t leak to the frontend. Peers you share a network with resolve by container name too — from the back network, db1 resolved proxy1 back to 10.90.0.20. When a name resolves to a surprising address, docker network inspect is the ground truth; the full mechanics live in How Docker’s embedded DNS resolves container names.

The default gateway is chosen, not obvious

With two networks, one provides the default route — and it may change every time connections change. In testing, the most recently attached network won; after pinning priority, the frontend won decisively:

# dual1, no priority: default went to the back network
default via 10.90.0.1 dev eth0

# dual2 with gw-priority=1 on the frontend
default via 192.168.80.1 dev eth1

gw-priority defaults to 0; the network with the highest value becomes the default gateway, and 1 is enough when a network should always win. Set it whenever a multi-network container must egress through a specific path — otherwise “why did my container’s outbound traffic take the wrong way” becomes a packet-capture session.

The bottom line

Multi-network containers are a first-class feature: docker network connect for running containers with --ip/--alias, repeated --network flags (or the extended name=...,ip=... syntax) at run time, and per-service networks: lists in Compose. Keep membership tight — one dual-homed proxy, everything else single-homed — scope your aliases deliberately, and pin gw-priority so the default route doesn’t move under you.

Further reading