Skip to content

8.04 Network Namespaces

Abstract

Network namespaces provide isolated network stacks on a Linux host.

Containers use network namespaces to get their own interfaces, IP addresses, routing tables, and ARP tables, separate from the host and other containers.

These concepts are important for understanding Docker networking, Kubernetes Pod networking, and CNI plugins.

What is a Namespace?

A namespace isolates resources inside Linux.

For containers, namespaces provide separation for:

  • processes
  • networking
  • mounts
  • users
  • hostnames

Note

A container appears to have its own system view, but the host can still see everything.

Process Namespace

Inside a container, a process may appear as PID 1.

Example inside container:

ps aux

Output may show:

USER   PID   COMMAND
root   1     nginx

On the host, the same process appears with a different PID:

ps aux

Example:

USER   PID    COMMAND
root   3816   nginx

Tip

The same process can have different process IDs inside and outside the container because of process namespaces.

Network Namespace

A network namespace gives an isolated network environment.

Each network namespace can have its own:

  • network interfaces
  • IP addresses
  • routing table
  • ARP table
  • firewall rules

Success

Network namespaces are the foundation of container network isolation.

Host vs Network Namespace

The host has its own interfaces:

ip link

Example:

lo
eth0

A new network namespace initially sees only loopback:

ip netns exec red ip link

or:

ip -n red link

Note

The namespace cannot see the host eth0 unless it is explicitly connected.

Create Network Namespaces

Create two namespaces:

ip netns add red
ip netns add blue

List namespaces:

ip netns

Example output:

red
blue

Execute Commands Inside a Namespace

Use ip netns exec:

ip netns exec red ip link

Alternative short form:

ip -n red link

Tip

ip -n <namespace> works only for ip commands.
For other commands, use ip netns exec.

Example:

ip netns exec red arp
ip netns exec red route

ARP and Routing Isolation

On the host:

arp
route

Inside a namespace:

ip netns exec red arp
ip netns exec red route

Initially, the namespace has:

  • no ARP entries
  • no external routes
  • no network connectivity

Note

Each namespace maintains its own ARP and routing tables.

Connect Two Namespaces with veth Pair

A veth pair acts like a virtual network cable.

Create a veth pair:

ip link add veth-red type veth peer name veth-blue

Attach one end to each namespace:

ip link set veth-red netns red
ip link set veth-blue netns blue

Assign IP addresses:

ip -n red addr add 192.168.15.1/24 dev veth-red
ip -n blue addr add 192.168.15.2/24 dev veth-blue

Bring interfaces up:

ip -n red link set veth-red up
ip -n blue link set veth-blue up

Test connectivity:

ip netns exec red ping 192.168.15.2

Success

The red and blue namespaces can now communicate directly.

Check ARP Tables

Inside red namespace:

ip netns exec red arp

Inside blue namespace:

ip netns exec blue arp

The host ARP table does not know about these namespace interfaces:

arp

Note

Namespace networking is isolated from the host unless connected through a bridge or routing.

Why Linux Bridge Is Needed

A veth pair works for connecting two namespaces.

For multiple namespaces, create a virtual switch using a Linux bridge.

Options include:

  • Linux Bridge
  • Open vSwitch

This guide uses Linux Bridge.

Create Linux Bridge

Create bridge interface:

ip link add v-net-0 type bridge

View it:

ip link

Bring it up:

ip link set dev v-net-0 up

Tip

A Linux bridge acts like a switch for namespaces and like an interface for the host.

Delete Old Direct veth Pair

If red and blue were directly connected, delete the old veth pair:

ip -n red link del veth-red

Note

Deleting one end of a veth pair automatically deletes the other end.

Connect Namespaces to Linux Bridge

Create veth pair for red:

ip link add veth-red type veth peer name veth-red-br

Attach one end to namespace:

ip link set veth-red netns red

Attach bridge-side end to Linux bridge:

ip link set veth-red-br master v-net-0

Create veth pair for blue:

ip link add veth-blue type veth peer name veth-blue-br

Attach one end to namespace:

ip link set veth-blue netns blue

Attach bridge-side end to Linux bridge:

ip link set veth-blue-br master v-net-0

Configure Namespace IPs

Assign IP addresses:

ip -n red addr add 192.168.15.1/24 dev veth-red
ip -n blue addr add 192.168.15.2/24 dev veth-blue

Bring namespace interfaces up:

ip -n red link set veth-red up
ip -n blue link set veth-blue up

Bring bridge-side interfaces up:

ip link set veth-red-br up
ip link set veth-blue-br up

Test:

ip netns exec red ping 192.168.15.2

Success

Both namespaces now communicate through the Linux bridge.

Connect Host to Namespace Network

The bridge is also an interface on the host.

Assign an IP to the bridge:

ip addr add 192.168.15.5/24 dev v-net-0

Now the host can reach namespaces:

ping 192.168.15.1
ping 192.168.15.2

Note

This creates a private network inside the host: 192.168.15.0/24.

Enable Namespace Access to LAN

Assume the host has:

Interface IP
Bridge v-net-0 192.168.15.5
Host LAN eth0 192.168.1.2

If namespace blue wants to reach LAN network 192.168.1.0/24, add a route inside blue:

ip netns exec blue ip route add 192.168.1.0/24 via 192.168.15.5

Warning

The gateway must be reachable from inside the namespace.
Use 192.168.15.5, not the host LAN IP 192.168.1.2.

Enable NAT with iptables

Even with routes, external hosts may not know how to return traffic to the namespace network.

Enable NAT masquerading on the host:

iptables -t nat -A POSTROUTING \
  -s 192.168.15.0/24 \
  -j MASQUERADE

Success

NAT allows namespace traffic to reach external networks using the host’s IP address.

Enable Internet Access from Namespace

Add a default route inside the namespace:

ip netns exec blue ip route add default via 192.168.15.5

Test internet connectivity:

ip netns exec blue ping 8.8.8.8

Tip

A default route sends all unknown traffic through the specified gateway.

Port Forwarding to Namespace

If a namespace hosts a web app on port 80, outside clients cannot directly reach the private namespace IP.

Forward traffic from the host to the namespace:

iptables -t nat -A PREROUTING \
  --dport 80 \
  --to-destination 192.168.15.2:80 \
  -j DNAT

Note

This forwards traffic arriving at the host on port 80 to namespace blue on port 80.

Network Namespace Workflow

Create namespace
      ↓
Create veth pair
      ↓
Attach veth to namespace
      ↓
Attach other end to bridge
      ↓
Assign IP address
      ↓
Bring interfaces up
      ↓
Add routes
      ↓
Enable NAT if external access is needed

Relation to Docker and Kubernetes

Containers use network namespaces for isolation.

Docker and Kubernetes automate the same concepts:

  • create namespace
  • create veth pair
  • connect to bridge or CNI network
  • assign IP
  • configure routes
  • apply NAT or policies

Example

Kubernetes CNI plugins automate these Linux networking steps for every Pod.

Production Best Practices

Recommended

  • Understand namespaces before troubleshooting CNI
  • Use CNI plugins instead of manual namespace networking in Kubernetes
  • Keep Pod CIDRs and node CIDRs non-overlapping
  • Use network policies for traffic control
  • Monitor iptables and routing rules carefully
  • Avoid manual changes on production nodes unless required for troubleshooting

Do's

  • Use ip netns to inspect namespaces
  • Use ip -n <namespace> for quick namespace network checks
  • Use Linux bridges for multi-namespace connectivity
  • Use NAT when private namespaces need external access
  • Validate routes and ARP tables during troubleshooting

Don'ts

  • Don't assume namespaces can reach the host automatically
  • Don't forget to bring interfaces up
  • Don't use unreachable gateways in routes
  • Don't modify iptables blindly in production
  • Don't use overlapping IP ranges

Danger

Incorrect routes, NAT rules, or overlapping CIDRs can break Pod connectivity and cause hard-to-debug Kubernetes networking issues.

Troubleshooting Checklist

When namespace networking fails, check:

  • Does the namespace exist?
  • Are veth interfaces created?
  • Is the correct veth end attached to the namespace?
  • Are interfaces up?
  • Are IP addresses assigned?
  • Is the bridge up?
  • Is routing configured?
  • Is IP forwarding enabled if routing is required?
  • Are iptables NAT rules correct?
  • Are CIDR ranges overlapping?

Quick Commands

ip netns add red
ip netns add blue
ip netns
ip netns exec red ip link
ip -n red link
ip link add veth-red type veth peer name veth-blue
ip link set veth-red netns red
ip link set veth-blue netns blue
ip -n red addr add 192.168.15.1/24 dev veth-red
ip -n blue addr add 192.168.15.2/24 dev veth-blue
ip -n red link set veth-red up
ip -n blue link set veth-blue up
ip netns exec red ping 192.168.15.2

Linux bridge:

ip link add v-net-0 type bridge
ip link set dev v-net-0 up
ip addr add 192.168.15.5/24 dev v-net-0

NAT:

iptables -t nat -A POSTROUTING -s 192.168.15.0/24 -j MASQUERADE

Summary

Quote

  • Network namespaces isolate interfaces, routes, and ARP tables
  • veth pairs connect namespaces like virtual cables
  • Linux bridges connect multiple namespaces like virtual switches
  • Routes and gateways allow namespace traffic to leave its network
  • NAT enables private namespaces to access external networks
  • Kubernetes CNI automates these concepts for Pods