» Networking

Vagrant uses the docker network command under the hood to create and managenetworks for containers. Vagrant will do its best to create and manage networksfor any containers configured inside the Vagrantfile. Each docker network is groupedby the subnet used for a requested ip address.

For each newly unique network, Vagrant will run the docker network create subcommandwith the provided options from the network config inside your Vagrantfile. If multiplenetworks share the same subnet, Vagrant will reuse that existing network for multiplecontainers. Once these networks have been created, Vagrant will attach thesenetworks to the requested containers using the docker network connect for eachnetwork.

Vagrant names the networks inside docker as vagrantnetwork or vagrant_network<subnet here>where <subnet_here> is the subnet for the network if defined by the user. Anexample of these networks is shown later in this page. If no subnet is requestedfor the network, Vagrant will connect the vagrant_network to the container.

When destroying containers through Vagrant, Vagrant will clean up the network ifthere are no more containers using the network.

» Docker Network Options

Most of the options work similar to other Vagrant providers. Defining either anip or using type: 'dhcp' will give you a network on your container.

  1. docker.vm.network :private_network, type: "dhcp"
  2. docker.vm.network :private_network, ip: "172.20.128.2"

If you want to set something specific with a new network you can use scoped optionswhich align with the command line flags for the docker network createcommand. If there are any specific options you want to enable from the docker network createcommand, you can specify them like this:

  1. docker.vm.network :private_network, type: "dhcp", docker_network__internal: true

This will enable the internal option for the network when created with docker network create.

Where option corresponds to the given flag that will be provided to the docker network createcommand. Similarly, if there is a value you wish to enable when connecting a containerto a given network, you can use the following value in your network config:

  1. docker_connect__option: "value"

When the docker provider creates a new network a netmask is required. If the netmaskis not provided, Vagrant will default to a /24 for IPv4 and /64 for IPv6. To providea different mask, set it using the netmask option:

  1. docker.vm.network :private_network, ip: "172.20.128.2", netmask: 16

For networks which set the type to "dhcp", it is also possible to specify a specificsubnet for the network connection. This allows containers to connect to networks otherthan the default vagrant_network network. The docker provider supports specifyingthe desired subnet in two ways. The first is by using the ip and netmask options:

  1. docker.vm.network :private_network, type: "dhcp", ip: "172.20.128.0", netmask: 24

The second is by using the subnet option:

  1. docker.vm.network :private_network, type: "dhcp", subnet: "172.20.128.0/24"

» Public Networks

The Vagrant docker provider also supports defining public networks. The easiest wayto define a public network is by setting the type option to "dhcp":

  1. docker.vm.network :public_network, type: "dhcp"

A bridge interface is required when setting up a public network. When no bridgedevice name is provided, Vagrant will prompt for the appropriate device to use. Thiscan also be set using the bridge option:

  1. docker.vm.network :public_network, type: "dhcp", bridge: "eth0"

The bridge option also supports a list of interfaces which can be used forsetting up the network. Vagrant will inspect the defined interfaces and usethe first active interface when setting up the network:

  1. docker.vm.network :public_network, type: "dhcp", bridge: ["eth0", "wlan0"]

The available IP range for the bridge interface must be known when setting upthe docker network. Even though a DHCP service may be available on the publicnetwork, docker will manage IP addresses provided to containers. This meansthat the subnet provided when defining the available IP range for the networkshould not be included within the subnet managed by the DHCP service. Vagrantwill prompt for the available IP range information, however, it can also beprovided in the Vagrantfile using the docker_network__ip_range option:

  1. docker.vm.network :public_network, type: "dhcp", bridge: "eth0", docker_network__ip_range: "192.168.1.252/30"

Finally, the gateway for the interface is required during setup. The dockerprovider will default the gateway address to the first address available forthe subnet of the bridge device. Vagrant will prompt for confirmation to usethe default address. The address can also be manually set in the Vagrantfileusing the docker_network__gateway option:

  1. docker.vm.network :public_network, type: "dhcp", bridge: "eth0", docker_network__gateway: "192.168.1.2"

More examples are shared below which demonstrate creating a few common networkinterfaces.

» Docker Network Example

The following Vagrantfile will generate these networks for a container:

  • A IPv4 IP address assigned by DHCP
  • A IPv4 IP address 172.20.128.2 on a network with subnet 172.20.0.0/16
  • A IPv6 IP address assigned by DHCP on subnet 2a02:6b8:b010:9020:1::/80
  1. Vagrant.configure("2") do |config|
  2.   config.vm.define "docker"  do |docker|
  3.     docker.vm.network :private_network, type: "dhcp", docker_network__internal: true
  4.     docker.vm.network :private_network,
  5.         ip: "172.20.128.2", netmask: "16"
  6.     docker.vm.network :private_network, type: "dhcp", subnet: "2a02:6b8:b010:9020:1::/80"
  7.     docker.vm.provider "docker" do |d|
  8.       d.build_dir = "docker_build_dir"
  9.     end
  10.   end
  11. end

You can test that your container has the proper configured networks by lookingat the result of running ip addr, for example:

  1. brian@localghost:vagrant-sandbox % docker ps                                                             ±[●][master]
  2. CONTAINER ID        IMAGE                                  COMMAND                  CREATED             STATUS              PORTS                                              NAMES
  3. 370f4e5d2217        196a06ef12f5                           "tail -f /dev/null"      5 seconds ago       Up 3 seconds        80/tcp, 443/tcp                                    vagrant-sandbox_docker-1_1551810440
  4. brian@localghost:vagrant-sandbox % docker exec 370f4e5d2217 ip addr                                      ±[●][master]
  5. 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
  6.     link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
  7.     inet 127.0.0.1/8 scope host lo
  8.        valid_lft forever preferred_lft forever
  9.     inet6 ::1/128 scope host
  10.        valid_lft forever preferred_lft forever
  11. 24: eth0@if25: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
  12.     link/ether 02:42:ac:11:00:03 brd ff:ff:ff:ff:ff:ff link-netnsid 0
  13.     inet 172.17.0.3/16 brd 172.17.255.255 scope global eth0
  14.        valid_lft forever preferred_lft forever
  15. 27: eth1@if28: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
  16.     link/ether 02:42:ac:13:00:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0
  17.     inet 172.19.0.2/16 brd 172.19.255.255 scope global eth1
  18.        valid_lft forever preferred_lft forever
  19. 30: eth2@if31: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
  20.     link/ether 02:42:ac:14:80:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0
  21.     inet 172.20.128.2/16 brd 172.20.255.255 scope global eth2
  22.        valid_lft forever preferred_lft forever
  23. 33: eth3@if34: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
  24.     link/ether 02:42:ac:15:00:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0
  25.     inet 172.21.0.2/16 brd 172.21.255.255 scope global eth3
  26.        valid_lft forever preferred_lft forever
  27.     inet6 2a02:6b8:b010:9020:1::2/80 scope global nodad
  28.        valid_lft forever preferred_lft forever
  29.     inet6 fe80::42:acff:fe15:2/64 scope link
  30.        valid_lft forever preferred_lft forever

You can also connect your containers to a docker network that was created outsideof Vagrant:

  1. $ docker network create my-custom-network --subnet=172.20.0.0/16
  1. Vagrant.configure("2") do |config|
  2.   config.vm.define "docker"  do |docker|
  3.     docker.vm.network :private_network, type: "dhcp" name: "my-custom-network"
  4.     docker.vm.provider "docker" do |d|
  5.       d.build_dir = "docker_build_dir"
  6.     end
  7.   end
  8. end

Vagrant will not delete or modify these outside networks when deleting the container, however.

» Useful Debugging Tips

The docker network command provides some helpful insights to what might be goingon with the networks Vagrant creates. For example, if you want to know what networksyou currently have running on your machine, you can run the docker network ls command:

  1. brian@localghost:vagrant-sandbox % docker network ls                                                     ±[●][master]
  2. NETWORK ID          NAME                                        DRIVER              SCOPE
  3. a2bfc26bd876        bridge                                      bridge              local
  4. 2a2845e77550        host                                        host                local
  5. f36682aeba68        none                                        null                local
  6. 00d4986c7dc2        vagrant_network                             bridge              local
  7. d02420ff4c39        vagrant_network_2a02:6b8:b010:9020:1::/80   bridge              local
  8. 799ae9dbaf98        vagrant_network_172.20.0.0/16               bridge              local

You can also inspect any network for more information:

  1. brian@localghost:vagrant-sandbox % docker network inspect vagrant_network                                ±[●][master]
  2. [
  3.     {
  4.         "Name": "vagrant_network",
  5.         "Id": "00d4986c7dc2ed7bf1961989ae1cfe98504c711f9de2f547e5dfffe2bb819fc2",
  6.         "Created": "2019-03-05T10:27:21.558824922-08:00",
  7.         "Scope": "local",
  8.         "Driver": "bridge",
  9.         "EnableIPv6": false,
  10.         "IPAM": {
  11.             "Driver": "default",
  12.             "Options": {},
  13.             "Config": [
  14.                 {
  15.                     "Subnet": "172.19.0.0/16",
  16.                     "Gateway": "172.19.0.1"
  17.                 }
  18.             ]
  19.         },
  20.         "Internal": false,
  21.         "Attachable": false,
  22.         "Ingress": false,
  23.         "ConfigFrom": {
  24.             "Network": ""
  25.         },
  26.         "ConfigOnly": false,
  27.         "Containers": {
  28.             "370f4e5d2217e698b16376583fbf051dd34018e5fd18958b604017def92fea63": {
  29.                 "Name": "vagrant-sandbox_docker-1_1551810440",
  30.                 "EndpointID": "166b7ca8960a9f20a150bb75a68d07e27e674781ed9f916e9aa58c8bc2539a61",
  31.                 "MacAddress": "02:42:ac:13:00:02",
  32.                 "IPv4Address": "172.19.0.2/16",
  33.                 "IPv6Address": ""
  34.             }
  35.         },
  36.         "Options": {},
  37.         "Labels": {}
  38.     }
  39. ]

» Caveats

For now, Vagrant only looks at the subnet when figuring out if it should createa new network for a guest container. If you bring up a container with a network,and then change or add some new options (but leave the subnet the same), it willnot apply those changes or create a new network.

Because the —link flag for the docker network connect command is consideredlegacy, Vagrant does not support that option when creating containers and connectingnetworks.

» More Information

For more information on how docker manages its networks, please refer to theirdocumentation: