To bind Docker containers to specific VLANs on Ubuntu, you must create Linux network interfaces tagged with the desired VLAN ID and then attach those interfaces to a custom Docker bridge network. This approach leverages Docker’s built-in networking capabilities to ensure that container traffic is isolated and routed through the correct physical or logical network segment, enhancing security and segmentation for your applications without requiring complex external routing configurations.
Prerequisites and Network Interface Preparation
Before configuring Docker, you need to ensure that your Ubuntu host has the necessary kernel modules loaded to handle 802.1Q VLAN tagging. Most modern Ubuntu installations include these modules by default, but it is wise to verify that the
8021q module is active. You can check this by running
lsmod | grep 8021q. If the module is not listed, load it using
sudo modprobe 8021q.
Next, identify the physical network interface that connects to the switch port configured for your target VLAN. On Ubuntu, you can list all available interfaces using the
ip link show command. Look for an interface such as
eth0 or
ens33, depending on your system's naming convention. You will need this parent interface name to create the virtual VLAN sub-interface.
It is also important to note that if you are managing network connections via Netplan or NetworkManager, creating VLAN interfaces manually might be overwritten during reboots or network service restarts. For production environments, consider defining the VLAN in your Netplan configuration file located in
/etc/netplan/. However, for immediate testing and manual setup, the
vconfig tool or direct
ip commands provide a quick way to establish the tagged interface.
Creating the VLAN Sub-Interface
The core of this process involves creating a virtual network interface that carries the VLAN tag. Use the
ip command to add a sub-interface to your physical NIC. The syntax follows the pattern
ip link add link [parent_interface] name [vlan_name] type vlan id [vlan_id]. For example, if your physical interface is
eth0 and you want to use VLAN ID 100, the command would be:
sudo ip link add link eth0 name eth0.100 type vlan id 100
Once created, the new interface
eth0.100 will appear in the list of network devices. However, it will likely be in a DOWN state by default. You must bring it up to allow traffic to pass through it. Execute the following command to activate the interface:
sudo ip link set eth0.100 up
You can verify that the interface is active and correctly tagged by running
ip addr show eth0.100. At this stage, the interface exists on the host OS, but it does not yet have an IP address assigned unless you configure one. For Docker bridging, we typically do not assign an IP to the VLAN interface itself; instead, we use it as a transport mechanism for the Docker bridge.
Configuring the Docker Bridge Network
Docker allows you to define custom networks with specific drivers. To bind containers to our newly created VLAN interface, we will create a bridge network and specify the parent interface using the
com.docker.network.bridge.parent.interface option. First, create a new bridge network named vlannet using the bridge driver.
docker network create --driver bridge \
--opt com.docker.network.bridge.name=docker-br-vlan \
--opt com.docker.network.bridge.parent.interface=eth0.100 \
vlannet
This command instructs Docker to create a Linux bridge named docker-br-vlan and attach it to the eth0.100 interface. Any container attached to this network will have its egress and ingress traffic tagged with VLAN 100 when it leaves the host. This effectively isolates the container's network traffic from other containers on different bridges or the default bridge.
If you need to assign a specific subnet to this network to avoid IP conflicts with your existing infrastructure, you can add the --subnet flag. For instance:
docker network create --driver bridge \
--subnet 192.168.100.0/24 \
--opt com.docker.network.bridge.name=docker-br-vlan \
--opt com.docker.network.bridge.parent.interface=eth0.100 \
vlannet
This ensures that containers launched on this network receive IPs within the specified range, which should align with the VLAN's DHCP scope or static assignment plan.
Running Containers on the VLAN Network
With the network ready, you can launch containers and attach them to the vlannet network. When starting a container, use the --network flag to specify the custom bridge. For example, to start an Nginx container on this VLAN:
docker run -d --name nginx-vlan --network vlannet nginx
You can verify that the container is correctly associated with the VLAN by inspecting the network details using docker network inspect vlannet. The output will show the connected containers and their IP addresses within the defined subnet. Additionally, you can check the host's routing table to ensure that traffic destined for the container's IP is being forwarded through the VLAN interface.
For persistent setups, always remember to save your VLAN configuration. If you used manual ip commands, they will disappear after a reboot. Integrate the VLAN creation into your Netplan YAML files or use a systemd service to recreate the interface at boot time. This ensures that your Docker containers remain bound to the correct VLAN even after system restarts.
Troubleshooting Connectivity Issues
If containers cannot reach external resources or other hosts on the same VLAN, check several common pitfalls. First, verify that the switch port connected to the Ubuntu host is configured to trunk the specific VLAN or access mode for that VLAN ID. Second, ensure that IP forwarding is enabled on the host if the containers need to communicate with other subnets. Run sysctl net.ipv4.ip_forward to check this setting.
Third, review your firewall rules. Ubuntu often uses UFW (Uncomplicated Firewall) or iptables directly. Ensure that traffic between the Docker bridge and the VLAN interface is not blocked. You may need to adjust UFW settings to allow forwarding between interfaces. Finally, confirm that there are no IP address conflicts between the Docker subnet and the physical network's DHCP pool.
Frequently Asked Questions
Can I use Docker overlay networks for VLAN binding?
No, overlay networks are designed for multi-host swarm clusters and encapsulate traffic in VXLAN tunnels, which bypasses standard VLAN tagging. To bind to a specific VLAN on a single host, you must use the bridge driver with the parent interface option as described in this guide.
How do I make the VLAN interface persistent across reboots?
Manual ip commands are lost on reboot. You should define the VLAN in your Netplan configuration file under /etc/netplan/ or create a systemd service that runs the ip link add command during startup to ensure the interface is always available for Docker.
What happens if the physical switch port does not support the VLAN ID?
If the switch port is not configured to accept the VLAN tag, traffic from the container will be dropped by the switch. Ensure that the switch port is either set to access mode for that VLAN or configured as a trunk port allowing that specific VLAN ID to pass through.
Can multiple Docker containers share the same VLAN bridge?
Yes, multiple containers can be attached to the same custom bridge network. They will share the same Layer 2 domain and can communicate directly with each other, while all their external traffic will be tagged with the same VLAN ID.
Is it possible to route traffic from a VLAN-bound container to the internet?
Yes, provided that your host has proper routing and NAT (Network Address Translation) configured. The host must forward traffic from the Docker bridge to the VLAN interface and then to the gateway, ensuring that return traffic is correctly routed back to the container's IP.