Bug report (or feature request): MAC Address Support for Macvlan Networks in Docker Compose

Docker Engine General
, , ,
1

Summary

Docker Compose does not support setting fixed MAC addresses for containers using external Macvlan networks, despite documentation suggesting it should work as of Docker v2.24.0+.

Environment

  • Docker version: 29.1.3, build f52814d
  • Docker Compose version: 1.29.2, build 5becea4c
  • Network driver: macvlan (external network)
  • OS: Ubuntu 24.04.3 LTS (kernel 6.8.0-90-generic)

Problem

Containers on Macvlan networks receive random MAC addresses on every recreation, making network management (DHCP reservations, statistics, firewall rules) based on MAC addresses impossible.

What I’ve Tried

1. Service-level mac_address (Documented in Compose File reference)

services:
  containerxyz:
    mac_address: "02:42:0a:00:46:27"
    networks:
      macvlan:
        ipv4_address: 192.168.70.27

Result: Deploys successfully, but MAC address is ignored - random MAC assigned

2. Network-level mac_address (Recommended in docs for Engine v25+)

services:
  containerxyz:
    networks:
      macvlan:
        ipv4_address: 192.168.70.27
        mac_address: "02:42:0a:00:46:27"

Result: Either “.networks.macvlan contains unsupported option: ‘mac_address’” error (without quotation marks around the mac address) OR the container deploys but MAC is ignored (if entered with quotation marks like in the example above).

3. Manual docker network connect with MAC

docker network connect --ip 192.168.70.27 --mac-address 02:42:0a:00:46:27 Macvlan containerxyz

Result: unknown flag: --mac-address - flag not available in Docker 29.1.3

4. Driver options workaround

docker network connect --ip 192.168.70.27 --driver-opt "com.docker.network.endpoint.macaddress=02:42:0a:00:46:27" Macvlan containerxyz

Result: Deploys but MAC still random

What Works

Portainer Duplicate/Edit supports setting a mac address, but this bypasses my CI pipeline and makes it really hard to maintain.

docker run --mac-address apparently also supports fixed MAC addresses, but this bypasses Docker Compose entirely.

Request

Please implement one of the following:

  1. Make Compose honor mac_address setting for Macvlan networks (as documentation suggests)
  2. Document the limitation clearly if this is intentional behavior
  3. Add --mac-address flag to docker network connect (then I could do it as a last step workaround in my deploy scripts.)

Currently forced to choose between Docker Compose (maintainability) or fixed MAC addresses (network management).

2

This is a community forum, where community users help other community users. If you want developers to see this, then I recommend opening an issue in docker’s upstream git repository https://github.com/moby/moby/issues

This one is spot on:

The missing --mac-address argument in the implementation and docs looks like a bug to me, since it is available as an option when creating the container:

 docker run -d \
  --network=name=macvlan,ip=192.168.70.27,mac-address=02:42:0a:00:46:27 \
  <image>

(see: options table and examples underneath in the docs: https://docs.docker.com/reference/cli/docker/container/run/#network)

I am surprised 2. didn’t work. I am pretty sure I used external macvlan and a compose file for my tests: How to assign MAC address to specific network when using multiple networks - #26 by damianiw.

3

I am not able to reproduce your problem btw:

docker network create \
  --driver macvlan \
  --subnet=192.168.200.0/24 \
  --ip-range=192.168.200.64/28 \
  --gateway=192.168.200.1 \
  --opt parent=eth0 \
  macvlan

COMPOSE_CONTENT=$(cat <<EOF
networks:
  macvlan:
    name: macvlan
    external: true

services:
  whoami:
    image: traefik/whoami:latest
    container_name: whoami-mac-test
    networks:
      macvlan:
        ipv4_address: 192.168.200.64
        mac_address: 02:de:ad:be:ef:01
EOF
)

docker compose --project-name mac-test --file - up -d <<<${COMPOSE_CONTENT}
docker inspect whoami-mac-test --format '{{json .NetworkSettings.Networks.macvlan}}' | jq
docker compose --project-name mac-test --file - down <<<${COMPOSE_CONTENT}
docker network rm macvlan

My output for docker inspect is:

{
  "IPAMConfig": {
    "IPv4Address": "192.168.200.64",
    "IPv6Address": ""
  },
  "Links": null,
  "Aliases": [
    "whoami-mac-test",
    "whoami"
  ],
  "DriverOpts": null,
  "GwPriority": 0,
  "NetworkID": "3a0f9e95b2b51e0f461f89d418afd9473288d8cfae4be182cad58b6f12300bc1",
  "EndpointID": "38c1442b6c283640f535878bb8f6f50abfc3da9c69494985ce87a8a001ce6894",
  "Gateway": "192.168.200.1",
  "IPAddress": "192.168.200.64",
  "MacAddress": "02:de:ad:be:ef:01",
  "IPPrefixLen": 24,
  "IPv6Gateway": "",
  "GlobalIPv6Address": "",
  "GlobalIPv6PrefixLen": 0,
  "DNSNames": [
    "whoami-mac-test",
    "whoami",
    "468276397eee"
  ]
}
4

I missed this one! This is the reason it’s not working. You are using an outdated client.
Use docker compose (=v2 or v5 client), not docker-compose (=v1 client).

Docker v29.1.3 should come with 5.0.0!

2 Likes
5

Thank you!! That actually solved it. :star_struck:

I’ll stick to using “docker compose” instead of docker-compose then :slight_smile:

Failed to get macvlan set up
6

I opened an issue in the Moby project for this, as I believe docker network connect should support the --mac-address argument, to be aligned with the options that docker run --network supports:

2 Likes
7

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.