haskal
/
vagrant
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add docs page about networking with the docker provider

This commit is contained in:
Brian Cain 2019-03-05 11:14:50 -08:00
parent b78dada2c7
commit 93f833d2b3
No known key found for this signature in database
GPG Key ID: 9FC4639B2E4510A0
3 changed files with 194 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/source/docs/docker/basics.html.md
View File

@ -73,8 +73,6 @@ This helps keep your Vagrantfile similar to how it has always looked.
The Docker provider does not support specifying options for `owner` or `group`
on folders synced with a docker container.
Private and public networks are not currently supported.
### Volume Consistency
Docker's [volume consistency](https://docs.docker.com/v17.09/engine/admin/volumes/bind-mounts/) setting can be specified using the `docker_consistency` option when defining a synced folder. This can

193
website/source/docs/docker/networking.html.md Normal file
View File

@ -0,0 +1,193 @@
---
layout: "docs"
page_title: "Networking - Docker Provider"
sidebar_current: "providers-docker-networking"
description: |-
The Vagrant Docker provider supports using the private network using the
`docker network` commands.
---
# Networking
Vagrant uses the `docker network` command under the hood to create and manage
networks for containers. Vagrant will do its best to create and manage networks
for any containers configured inside the Vagrantfile. Each docker network is grouped
by the subnet used for a requested ip address.
For each newly unique network, Vagrant will run the `docker network create` subcommand
with the provided options from the network config inside your Vagrantfile. If multiple
networks share the same subnet, it will reuse that existing network. Once these
networks have been created, Vagrant will attach these networks to the requested
containers using the `docker network connect` for each network.
Most of the options given to `:private_network` align with the command line flags
for the [docker network create](https://docs.docker.com/engine/reference/commandline/network_create/)
command. However, if you want the container to have a specific IP instead of using
DHCP, you also will have to specify a subnet due to how docker networks behave.
It should also be noted that if you want a specific IPv6 address, your `:private_network`
option should use `ip6` rather than `ip`. If you just want to use DHCP, you can
simply say `type: "dhcp"` insetad. More examples are shared below which demonstrate
creating a few common network interfaces.
When destroying containers through Vagrant, Vagrant will clean up the network if
there are no more containers using the network.
## Docker Network Example
The following Vagrantfile will generate these networks for a container:
1. A IPv4 IP address assigned by DHCP
2. A IPv4 IP address 172.20.128.2 on a network with subnet 172.20.0.0/16
3. A IPv6 IP address assigned by DHCP on subnet 2a02:6b8:b010:9020:1::/80
```ruby
Vagrant.configure("2") do |config|
config.vm.define "docker" do |docker|
docker.vm.network :private_network, type: "dhcp"
docker.vm.network :private_network,
ip: "172.20.128.2", subnet: "172.20.0.0/16"
docker.vm.network :private_network, type: "dhcp", ipv6: "true", subnet: "2a02:6b8:b010:9020:1::/80"
docker.vm.provider "docker" do |d|
d.build_dir = "docker_build_dir"
end
end
end
```
You can test that your container has the proper configured networks by looking
at the result of running `ip addr`, for example:
```
brian@localghost:vagrant-sandbox % docker ps ±[●][master]
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
370f4e5d2217 196a06ef12f5 "tail -f /dev/null" 5 seconds ago Up 3 seconds 80/tcp, 443/tcp vagrant-sandbox_docker-1_1551810440
brian@localghost:vagrant-sandbox % docker exec 370f4e5d2217 ip addr ±[●][master]
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
valid_lft forever preferred_lft forever
inet6 ::1/128 scope host
valid_lft forever preferred_lft forever
24: eth0@if25: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 02:42:ac:11:00:03 brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 172.17.0.3/16 brd 172.17.255.255 scope global eth0
valid_lft forever preferred_lft forever
27: eth1@if28: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 02:42:ac:13:00:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 172.19.0.2/16 brd 172.19.255.255 scope global eth1
valid_lft forever preferred_lft forever
30: eth2@if31: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 02:42:ac:14:80:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 172.20.128.2/16 brd 172.20.255.255 scope global eth2
valid_lft forever preferred_lft forever
33: eth3@if34: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 02:42:ac:15:00:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 172.21.0.2/16 brd 172.21.255.255 scope global eth3
valid_lft forever preferred_lft forever
inet6 2a02:6b8:b010:9020:1::2/80 scope global nodad
valid_lft forever preferred_lft forever
inet6 fe80::42:acff:fe15:2/64 scope link
valid_lft forever preferred_lft forever
```
## Useful Debugging Tips
If you provide Vagrant with a faulty config option when setting up a network, Vagrant
will pass that option along to the `docker network` commands it uses. That command
line tool should give you some insight if there is something wrong with the option
you configured:
```ruby
docker.vm.network :private_network,
ip: "172.20.128.2", subnet: "172.20.0.0/16",
unsupported: "option"
```
```
A Docker command executed by Vagrant didn't complete successfully!
The command run along with the output from the command is shown
below.
Command: ["docker", "network", "create", "vagrant_network_172.20.0.0/16", "--subnet=172.20.0.0/16", "--unsupported=option", {:notify=>[:stdout, :stderr]}]
Stderr: unknown flag: --unsupported
See 'docker network create --help'.
Stdout:
```
The `docker network` command provides some helpful insights to what might be going
on with the networks Vagrant creates. For example, if you want to know what networks
you currently have running on your machine, you can run the `docker network ls` command:
```
brian@localghost:vagrant-sandbox % docker network ls ±[●][master]
NETWORK ID NAME DRIVER SCOPE
a2bfc26bd876 bridge bridge local
2a2845e77550 host host local
f36682aeba68 none null local
00d4986c7dc2 vagrant_network bridge local
d02420ff4c39 vagrant_network_2a02:6b8:b010:9020:1::/80 bridge local
799ae9dbaf98 vagrant_network_172.20.0.0/16 bridge local
```
You can also inspect any network for more information:
```
brian@localghost:vagrant-sandbox % docker network inspect vagrant_network ±[●][master]
[
{
"Name": "vagrant_network",
"Id": "00d4986c7dc2ed7bf1961989ae1cfe98504c711f9de2f547e5dfffe2bb819fc2",
"Created": "2019-03-05T10:27:21.558824922-08:00",
"Scope": "local",
"Driver": "bridge",
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Options": {},
"Config": [
{
"Subnet": "172.19.0.0/16",
"Gateway": "172.19.0.1"
}
]
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": ""
},
"ConfigOnly": false,
"Containers": {
"370f4e5d2217e698b16376583fbf051dd34018e5fd18958b604017def92fea63": {
"Name": "vagrant-sandbox_docker-1_1551810440",
"EndpointID": "166b7ca8960a9f20a150bb75a68d07e27e674781ed9f916e9aa58c8bc2539a61",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {},
"Labels": {}
}
]
```
## Caveats
For now, Vagrant only looks at the subnet when figuring out if it should create
a 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 will
not apply those changes or create a new network.
## More Information
For more information on how docker manages its networks, please refer to their
documentation:
- https://docs.docker.com/network/
- https://docs.docker.com/engine/reference/commandline/network/

1
website/source/layouts/docs.erb
View File

@ -166,6 +166,7 @@
<li<%= sidebar_current("providers-docker-commands") %>><a href="/docs/docker/commands.html">Commands</a></li>
<li<%= sidebar_current("providers-docker-boxes") %>><a href="/docs/docker/boxes.html">Boxes</a></li>
<li<%= sidebar_current("providers-docker-configuration") %>><a href="/docs/docker/configuration.html">Configuration</a></li>
<li<%= sidebar_current("providers-docker-networking") %>><a href="/docs/docker/networking.html">Networking</a></li>
</ul>
</li>
<li<%= sidebar_current("providers-hyperv") %>>