Using MACVLAN in

Using MACVLAN in

Pretty much everyone is comfortable with docker bridge networking, and probably even overlay networking, but how many have used Docker's MACVLAN network driver? MY guess is not many, primarily because its a nightmare to setup. Well not anymore, as now with Portainer 1.19.2 we have dramatically simplified the setup and use of this powerful networking option.

For those unfamiliar with MACVLAN, its a way to give your containers and network identity (IP address primarily) on the real network, no NAT and no private IPs needed, your container has its own network stack on the real network (so keep in mind, if you use this, you need a firewall in your container!)

MACVLAN is fast, really fast.. if you need a way to deliver extreme network performance into a container, this is definitely the way to do it. Its also a really easy way to run load balancers or software firewalls as a container.

Anyway, lets get started...

Before we go anywhere near portainer, you first need to SSH into one of your Docker hosts to find out what your network card is called (if you have multiple network cards in your host and you want to use a specific card for MACVLAN, make sure you get the name of that one).

SSH in to a host, and then ifconfig to get a list of all devices (it might be a long list); or use ifconfig |grep eth or ifconfig |frep ens if you want to filter for these two most common names.


As you can see from the picture, my network card on my host is called ens160. Note that down somewhere, you will need it later.

Now, go into Portainer, select your endpoint, and then click on "Networks"


Click on "Add Network", then give your new network a name. Note that to use MACVLAN, you first need to create a config, so the first time, append "config" after the name (in my example, i am using mymacvlanconfig as the name.

Change the driver type to "macvlan". You will now see two boxes "Configuration" and "Creation". As there is currently no config, you cannot use "creation" for now, so lets go ahead and build a config.


In the "parent network card" box, type in the name of your network card (as you noted previously - oh, all nodes in your cluster must use the same name for this to work).

In the "Select the nodes" area, multi-select the hosts you wish to apply the config to (if you have just one host, you wont see this area).

In the "Subnet" box, enter the IP range and subnet mask of the underlying physical network the parent network card is attached to.

In the "Gateway" box, enter the default gateway for this subnet

In the "IP range" box, enter an ip range (in the form of IP/Subnet) to assign to containers that use this network; to have just ONE IP, enter the IP address and then /32 as the subnet.

If you want to use an IP range that has real devices on it already, you can add IPs to be excluded from Docker IPAM in the "excluded IPs" box.

Click "Create the network"

Click on "Add network" again, this time we will create the actual MACVLAN network.


Change the driver to "MACVLAN" and you can now see you are able to select "Creation", do so.

Select the previously created config in the "Configuration" drop-down box.

If you want to use MACVLAN for Containers as well as Swarm, then enable the switch for "enable manual container attachment".

Click "Create the network"

You can now test its work. Create a container, attach it to the MACVLAN network


Now, open the container console and run ifconfig or ip addr (depending on your container)


You can see you have been assigned .80 as the IP (as we previously allocated as the IP range); note you can also ping the default gateway directly from the container.

So there you go, a container (or service, if you use swarm) with real IP addresses on the physical network, no NAT, no Overlay..


      • Hi. Thanks for this write-up. Here’s the question, won’t deploying the same IP range to every node in your swarm lead to IP Address conflicts quickly? You will end up with an IP address conflict the first time a container gets deployed to a second node. Is there anything portainer does to automatically break your range into non-overlapping subnets?


      • Neil Cresswell

        This is managed by Docker’s IPAM module. It ensures there are no overlapping IP addresses across the cluster. Note that there was a known issue with IPAM in earlier versions of Docker, so always run a recent version if using MACVLAN


    • Steven Marshall

      Going back to cralsh comment. I agree. In fact I currently have this exact issue. Any other container except the first on a different host and the IP conflicts. Any resolution to this?


    • Neil Cresswell

      Are you using the latest version of Docker? MACVLAN is a Docker feature, and early version of it had a number of issues related to IPAM.


Leave a comment!

All fields marked with an asterisk* are required.