Docker VLAN Netmasks

I wrote previously about using ipvlans in Docker. For the first few months everything was groovy, but I ran into a surprising and irritating issue I thought I should write about.

About a month ago I changed my network to expand the IP address pool. Going from 10.49.1.0/24 to 10.49.0.0/22, which added addresses from 10.49.0.x, 10.49.2.x, and 10.49.3.x. I had reasons and things just worked for the most part.

I was working on a new ESPHome project a little bit later and was running into a very annoying bug. While the ESPHome node was happily sending updates to Home Assistant, Home Assistant would stop being able to send data to the node after a short time window. I would see the message in the logs WARNING Home Assistant 2025.10.2 (10.49.1.98): is unresponsive; disconnecting followed by INFO Successfully connected. I would be able to connect for about 10-30 seconds, then poof, connection gone.

I went down a ton of rabbit holes with ESPHome, and opened an topic on their forum. The culprit turned out to be a Docker configuration issue on my end.

When I updated my subnet, I failed to update the Docker vlan subnet. My initial configuration looked like.

resource "docker_network" "vlan" {
  name   = "ipvlan"
  driver = "ipvlan"

  ipam_config {
    subnet   = "10.49.1.0/24"
    gateway  = "10.49.1.1"
    ip_range = "10.49.1.0/24" # optional
  }

  options = {
    parent = "enp2s0f0"
  }
} 

This worked great, and since all the devices that get an address on my vlan are mostly sending data either to the Internet or in response to data, I did not notice the problem when I expanded my subnet on my OPNsense LAN interface.

Home Assistant could establish a connection when the ESPHome node announced itself, but after a few moments the connection dropped. Since the Docker vlan subnet (10.49.1.0/24) didn’t include the node’s actual IP (10.49.0.50), the routing table lacked a route back to the node’s IP, preventing reconnection. So even though the node had the correct subnet and could communicate, Home Assistant’s network interface couldn’t route back to it.

Once I diagnosed the problem, the fix was easy:

resource "docker_network" "vlan" {
  name   = "ipvlan"
  driver = "ipvlan"

  ipam_config {
    subnet   = "10.49.0.0/22"
    gateway  = "10.49.1.1"
    ip_range = "10.49.0.0/22" # optional
  }

  options = {
    parent = "enp2s0f0"
  }
} 

Now containers on my vlan know about my entire network and have correct routing tables. My ESPHome node is now stable and I am back to mostly just cursing at YAML.