Using a macvlan Network in Docker Compose

Edit 2020-10-28: Update docker-compose to v1.27.0+ and you might be able to use IPAM config in a v3 compose file (Link)

Docker Compose v3+ does not support IPAM configuration (gateway, ip_range, aux_addresses) of macvlan networks.

This network definition used to work in v2, but as v3 targets Docker Swarm use cases, it was removed (NOT deprecated!?):

networks:
home-lan:
name: home-lan
driver: macvlan
driver_opts:
parent: eth0
ipam:
config:
- subnet: 192.168.1.0/24
ip_range: 192.168.1.0/24
gateway: 192.168.1.1

Tips

• Use ip_range that matches your home network if you’d like your containers to appear with everything else on that network
• DHCP is NOT supported for containers on macvlan networks – make sure to assign a static ipv4_address to the container if you don’t want it to conflict with something else on your network – this will create big problems

More Info:

Docker Compose Spec – IPAM: https://docs.docker.com/compose/compose-file/#ipam

Note: Additional IPAM configurations, such as gateway, are only honored for version 2 at the moment.

Docker Macvlan Tutorial: https://docs.docker.com/network/network-tutorial-macvlan/#prerequisites

Note: macvlan is NOT supported on Windows hosts

Related Links:

• Github: Support IPAM gateway in version 3.x
  ^ Looks like this situation may be fixed in v1.27.0+ of docker-compose….
• Github: docker-compose network ipam config values are not allowed
• Github: version 1.10.0 error on gateway spec
• Github: Add note that Compose version 3 doesn’t support additional IPAM configs
• Github: add support for ip-range option to network creation
• Stackoverflow: How to create a Docker macvlan with user defined IP and MAC address using Compose