Before namespace sharing makes sense, you need a solid mental model of what a network namespace is, what it isolates, and why Docker creates one for every container by default.

What a network namespace actually is

A network namespace is a Linux kernel feature that gives a group of processes its own completely separate copy of the networking stack. That copy includes its own network interfaces (like eth0), its own IP addresses, its own routing table, its own firewall rules, its own list of open ports, and even its own view of files like /proc/net. Two processes in two different network namespaces can both bind to port 80 at the same time, on what looks like the same machine, because as far as the kernel is concerned they are on two entirely different network stacks that simply happen to live on the same physical computer.

Namespaces are a kernel feature, not a Docker invention

It is worth being precise here: Docker did not invent network namespaces. They are a Linux kernel facility that has existed since the mid-2000s, originally built for network virtualization and testing. Docker’s real contribution was building a friendly, automated layer on top of this low-level kernel primitive — creating the namespace, wiring up a virtual network cable into it, connecting that cable to a virtual switch, assigning an IP address, and tearing the whole thing down cleanly when the container stops. Understanding that the namespace itself is a generic Linux object — not something tied to the word “container” — makes the sharing behavior much easier to reason about, because sharing a namespace is really just pointing two different groups of processes at the same kernel object.

The four Docker network modes and where sharing fits

Docker exposes namespace behavior through four network modes you choose when starting a container. In bridge mode — the default — Docker creates a brand-new network namespace for the container and connects it to a private virtual switch. In host mode, Docker skips creating a new namespace entirely and simply runs the container’s processes directly inside the host machine’s own network namespace, so the container sees the host’s real network interfaces. In none mode, Docker creates an isolated namespace but never attaches any interface to it beyond a loopback, so the container has no external networking at all. The fourth mode — sometimes written as container:<name-or-id> — is network namespace sharing itself: instead of creating a new namespace, Docker reuses the exact namespace that already belongs to another, already-running container.

This fourth mode is the one this article focuses on. When container B is started with its network mode set to point at container A, Docker does not build container B a new virtual interface, does not assign it a new IP address, and does not give it its own port space. Instead, container B’s process simply attaches to container A’s existing network namespace. From that point forward, the two containers are, from a purely networking point of view, indistinguishable: same IP address, same interfaces, same routing table, same open ports, and — critically — the same localhost.

Namespace sharing touches several moving parts inside the Linux and Docker networking stack. Understanding each piece makes the internal working chapter much easier to follow.

flowchart TB
    subgraph HOST["Docker Host Kernel"]
        BR["docker0 Virtual Bridge"]
        subgraph NS1["Network Namespace #1"]
            VETH1["veth (container side)"]
            IP1["IP: 172.17.0.2"]
        end
        subgraph SHARED["Shared Network Namespace"]
            VETH2["veth (container side)"]
            IP2["IP: 172.17.0.3"]
            APP["App Container Process"]
            SIDE["Sidecar Container Process"]
        end
        BR --- VETH1
        BR --- VETH2
        APP -. shares .- SHARED
        SIDE -. shares .- SHARED
    end
    

The core building blocks

Where the “pause” or first container fits in

In hand-rolled Docker Compose setups, whichever container is started first with a normal (bridge or host) network mode becomes the namespace owner, and every other container that names it as a shared target simply attaches afterward. In orchestrated systems like Kubernetes, this idea is formalized: every pod silently runs an invisible, minimal “pause” container whose only job is to hold the network namespace open for the lifetime of the pod. Every real application container in that pod is then started in shared mode against the pause container, not against each other. This detail matters because it means the namespace’s lifecycle is deliberately decoupled from any single application container’s lifecycle — the namespace survives even if an application container inside it crashes and restarts.

This is the mechanical heart of the topic: what actually happens, system call by system call, when Docker builds a normal namespace versus when it shares one.

Building a fresh namespace (the default path)

When you start an ordinary container on the default bridge network, four things happen in sequence deep inside the kernel and the Docker daemon. First, the runtime calls the kernel’s clone system call with the CLONE_NEWNET flag, which manufactures a brand-new, empty network namespace containing nothing but a disabled loopback interface. Second, Docker creates a veth pair — a virtual two-ended cable — and moves one end of that cable into the new namespace, where it is renamed to eth0. Third, the other end of the cable is attached to the docker0 bridge on the host side. Fourth, the IPAM allocator hands out an unused IP address from the bridge’s subnet, assigns it to the new eth0, brings the interface up, and installs a default route pointing back through the bridge. Only after all four steps finish does your container’s main process actually begin executing inside that namespace.

Joining an existing namespace (the sharing path)

Sharing skips almost the entire sequence above. When you start a container with its network mode pointed at another container, the runtime does not call clone with CLONE_NEWNET at all. Instead, it looks up the target container’s process, opens the special file /proc/<target-pid>/ns/net — which is a handle to that container’s already-existing network namespace — and calls the kernel’s setns system call on it before starting the new process. No veth pair is created for the second container. No new IP address is allocated. No route is installed. The second container’s process simply begins its life already standing inside the first container’s fully wired-up network namespace, seeing the exact same eth0, the exact same IP address, and the exact same loopback interface.

sequenceDiagram
    participant U as docker run
    participant D as Docker Daemon
    participant K as Linux Kernel
    participant NS as Target Namespace

    U->>D: start container B, network=container:A
    D->>K: lookup PID of container A
    K-->>D: PID + /proc/PID/ns/net handle
    D->>K: setns(handle, CLONE_NEWNET)
    K->>NS: attach container B's process
    Note over NS: eth0, IP, routes, ports
now shared with container A
    D-->>U: container B running, sharing A's network
    

Why localhost becomes shared, not just the IP address

A detail that trips up many engineers: sharing a namespace does not just mean “same IP address” — it means the two containers are now talking over the very same loopback interface. A process in the sidecar container can open a socket to 127.0.0.1:9090 and reach a service bound to that port by the application container’s process, because from the kernel’s point of view there is only one loopback device involved, shared by two different process trees. This is precisely why the sidecar pattern works at all: it lets a proxy, log shipper, or metrics exporter reach the main application over plain localhost sockets with zero network configuration, exactly as if both programs were threads inside the same process rather than separate containers.

Namespace lifetime and ownership

A network namespace is kept alive by the kernel as long as at least one process is attached to it, or as long as something is holding a reference to it, such as a bind-mounted namespace file. In Docker’s model, the namespace is conceptually owned by whichever container was started without a shared network mode — the “owner” container. If that owner container is stopped and removed while other containers are still sharing its namespace, the shared network configuration effectively becomes orphaned: the dependent containers keep their existing sockets alive but lose the ability to have DNS records or port mappings updated, which is why Docker and orchestrators like Kubernetes tie the health of the whole namespace group to the owner’s lifecycle rather than letting it be deleted independently.

How does a packet actually travel once two containers share a namespace, and what does the full lifecycle look like from container creation to teardown?

Inbound packet journey

Consider a client on another machine sending a request to a web server running inside a sidecar-sharing pod. The packet arrives at the host’s physical network interface, is routed by the host kernel to the veth end attached to the docker0 bridge (or, in host-mode setups, directly to the shared namespace’s interface), crosses into the shared network namespace through that single veth pair, and lands on the one eth0 that both the application and the sidecar container can see. The kernel then delivers it to whichever process — application or sidecar — is bound to the destination port. There is no second hop, no extra bridge crossing, and no additional NAT translation between the two containers, because as far as the kernel’s routing logic is concerned, they are the same network endpoint.

Container-to-container communication inside the shared namespace

When the application container needs to hand data to the sidecar (for example, an access-log line, or a metrics scrape request), that traffic never leaves the machine’s memory. It travels entirely over the shared loopback device, exactly like two ordinary processes on a single Linux server talking to each other over 127.0.0.1. This is measurably faster and simpler than the alternative — two containers on separate namespaces communicating over the bridge — because it skips the bridge’s Layer 2 forwarding logic, any NAT rules, and any DNS resolution step entirely.

Restart semantics and why orchestrators use a stable owner

Because the dependent container’s networking identity is borrowed, restarting the dependent container is cheap and safe — it simply re-joins the same still-running namespace and keeps the same IP address. Restarting the owner container is far more disruptive: the namespace it held is destroyed and a brand-new one is built, typically with a new IP address, meaning every dependent container attached to the old namespace is left pointing at a namespace that no longer exists. This asymmetry is exactly why Kubernetes never lets an application container be the network owner of a pod — the invisible pause container fills that role specifically because it almost never restarts, giving the whole pod a stable network identity for its entire lifetime regardless of how many times the real application containers inside it crash and are recreated.

Namespace sharing is a powerful tool with real costs. Weighing them clearly is what separates a deliberate architectural choice from an accidental one.

The core trade-off: isolation versus intimacy

Every Docker network mode sits somewhere on a spectrum between strong isolation and easy communication. Bridge mode leans toward isolation with moderate communication cost (a hop through the virtual switch). Host mode leans hard toward communication convenience at the total cost of isolation from the host itself. Namespace sharing occupies a special middle position: it sacrifices network isolation between a small, deliberately chosen group of containers, while still keeping the host’s own namespace fully isolated from all of them. The right mental model is that namespace sharing turns a “loosely coupled group of containers” into a “tightly coupled network unit” without touching process, filesystem, or user isolation at all — you are choosing exactly one axis of coupling, not giving up containerization altogether.

Sharing a network namespace is one of the more consequential security decisions available in Docker’s configuration surface, and it deserves the same scrutiny as sharing a process namespace or mounting the host filesystem.

What sharing actually exposes

Once two containers share a network namespace, every port either one of them opens on that shared eth0 or loopback interface is reachable by the other, regardless of any application-level authentication the port’s owner might expect. A debugging or admin interface that a developer assumed was “only reachable from inside the container” because it binds to 127.0.0.1 is, inside a shared namespace, reachable from every other container sharing that namespace too — the isolation boundary that made binding to localhost feel safe has been deliberately removed. Traffic sniffing is the other major exposure: a process with the right capabilities inside a shared namespace can, in principle, observe traffic destined for the same interface that other containers in that namespace are using, something that is impossible across genuinely separate namespaces without additional privilege.

Threat model implications

Security teams generally treat a shared network namespace as a single trust boundary, not two. If a container joining a namespace is a third-party image whose provenance you don’t fully control, it now has unrestricted network-layer access to every service the owner container exposes on that namespace, bypassing any firewall rules that would otherwise apply between separately namespaced containers. Compromise of the lower-privileged container in a sharing group should therefore be assumed to grant network-level visibility into the higher-privileged one, and access controls (authentication on each service, not just network reachability) should be designed with that assumption in mind rather than relying on “it’s on a private container network” as a defense.

Combining with other isolation primitives

Because network namespace sharing only affects one of Docker’s six isolation mechanisms, teams often deliberately keep the other five intact even when sharing the network: separate process ID namespaces so containers cannot see or signal each other’s processes, separate mount namespaces and filesystems so a compromised sidecar cannot read the application’s files, and separate user namespaces or dropped Linux capabilities so a sidecar has the minimum privilege needed to do its job — commonly just enough to open outbound connections and read the shared loopback, nothing more. This layered approach is what makes the sidecar pattern broadly acceptable in production despite the network-sharing exposure: the blast radius of a sidecar compromise is deliberately capped everywhere except the network dimension.

Because several containers now present as one network identity, the tools you use to observe that identity need to be interpreted differently than they would for isolated containers.

What “container IP” tooling actually shows you

Standard container inspection commands report network settings per-container, but for containers in shared-namespace mode, every dependent container will report the exact same IP address, the exact same gateway, and the exact same list of exposed ports as the owner — because they are all describing the same underlying namespace, not because Docker is generating duplicate or incorrect data. Engineers unfamiliar with sharing sometimes interpret this as a bug (“why do these two containers have identical IPs?”), when it is in fact the expected, correct signature of namespace sharing and a useful diagnostic signal in its own right: if you see two containers with matching IPs, you are almost certainly looking at a shared-namespace group.

Designing dashboards and alerts for shared namespaces

Because per-container network throughput and connection-count metrics collapse to a single shared value across the group, dashboards built on the assumption that “container-level network metrics equal that container’s own traffic” will silently double-count or mis-attribute traffic in a shared-namespace group. The more accurate approach is to treat the shared namespace itself as the unit of network observability — tagging metrics by “namespace group” or “pod,” which is exactly what orchestrators like Kubernetes do by default — and to rely on process-level or cgroup-level metrics (which do stay separate even inside a shared namespace) for attributing CPU, memory, or per-process bandwidth back to an individual container.

Logging correlation as a side benefit

On the positive side, namespace sharing simplifies one common observability task: correlating a sidecar’s logs with the exact network session the main application handled, since both containers are observing traffic through the same interface and can reference the same connection five-tuple (source IP, source port, destination IP, destination port, protocol) without any address translation in between. This is one reason service-mesh sidecar proxies are almost universally deployed in shared-namespace mode rather than as separate bridge-networked containers — it lets the proxy attribute every connection back to the application with perfect fidelity.

Namespace sharing has become the load-bearing mechanism behind several well-known container design patterns, and just as easily behind several well-known mistakes.

Why the sidecar pattern specifically needs namespace sharing

It is worth being explicit about why this pattern could not be built as easily on top of ordinary bridge networking. If a log shipper sidecar were on its own separate namespace, it would need to know the application container’s bridge IP address, would incur a network hop for every log line, would be affected by any network policy or firewall rule that applies between bridge-networked containers, and would see a different IP than the application when both are inspected — breaking any downstream system that correlates logs by source IP. Namespace sharing eliminates every one of those complications in a single step, which is precisely why it became the default substrate for the sidecar pattern rather than a niche alternative to it.

Practical guardrails that separate a smooth namespace-sharing deployment from a confusing production incident.

A note on troubleshooting

When something in a shared-namespace group misbehaves on the network side, the most productive first question is not “which container has the bug” but “which container owns this namespace, and is it healthy” — because a namespace-level problem (an exhausted port range, a misconfigured route, a firewall rule installed by one container that blocks another) will manifest identically in every container attached to that namespace, and can easily be mistaken for a bug in whichever container happens to be easiest to inspect first.

Namespace sharing is not a theoretical curiosity — it is the invisible foundation underneath some of the most widely used infrastructure in the industry.

The scale here is worth sitting with: a technique that started as a fairly obscure Docker command-line flag became, once Kubernetes adopted it as the mechanism for pod networking, one of the most-executed pieces of container infrastructure logic on the planet, running silently underneath essentially every production Kubernetes workload that has ever shipped a sidecar proxy or log agent.

Network namespace sharing turns a low-level Linux kernel primitive into one of the most quietly influential design patterns in modern container infrastructure.