1. docker
  2. Commit ca7aa81de8f84b52665b79348dbedccb491dee1b
Browse code

Some users docs with a Vagrant setup

Sebastien Goasguen authored on 2015/07/01 23:20:00
Showing 2 changed files
libnetwork/docs/Vagrantfile
History View file @ ca7aa81
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,57 @@
0 
+# -*- mode: ruby -*-
1 
+# vi: set ft=ruby :
2 
+
3 
+# Vagrantfile API/syntax version. Don't touch unless you know what you're doing!
4 
+VAGRANTFILE_API_VERSION = "2"
5 
+
6 
+$consul=<<SCRIPT
7 
+apt-get update
8 
+apt-get -y install wget
9 
+wget -qO- https://experimental.docker.com/ | sh
10 
+gpasswd -a vagrant docker
11 
+service docker restart
12 
+docker run -d -p 8500:8500 -p 8300-8302:8300-8302/tcp -p 8300-8302:8300-8302/udp -h consul progrium/consul -server -bootstrap
13 
+SCRIPT
14 
+
15 
+$bootstrap=<<SCRIPT
16 
+apt-get update
17 
+apt-get -y install wget curl
18 
+apt-get -y install bridge-utils
19 
+wget -qO- https://experimental.docker.com/ | sh
20 
+gpasswd -a vagrant docker
21 
+echo DOCKER_OPTS=\\"--default-network=overlay:multihost --kv-store=consul:192.168.33.10:8500 --label=com.docker.network.driver.overlay.bind_interface=eth1 --label=com.docker.network.driver.overlay.neighbor_ip=192.168.33.11\\" >> /etc/default/docker
22 
+service docker restart
23 
+SCRIPT
24 
+
25 
+Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
26 
+
27 
+  config.ssh.shell = "bash -c 'BASH_ENV=/etc/profile exec bash'"
28 
+  num_nodes = 2
29 
+  base_ip = "192.168.33."
30 
+  net_ips = num_nodes.times.collect { |n| base_ip + "#{n+11}" }
31 
+
32 
+  config.vm.define "consul-server" do |consul|
33 
+    consul.vm.box = "ubuntu/trusty64"
34 
+    consul.vm.hostname = "consul-server"
35 
+    consul.vm.network :private_network, ip: "192.168.33.10"
36 
+    consul.vm.provider "virtualbox" do |vb|
37 
+     vb.customize ["modifyvm", :id, "--memory", "512"]
38 
+    end
39 
+    consul.vm.provision :shell, inline: $consul
40 
+  end
41 
+
42 
+  num_nodes.times do |n|
43 
+    config.vm.define "net-#{n+1}" do |net|
44 
+      net.vm.box = "chef/ubuntu-14.10"
45 
+      net_ip = net_ips[n]
46 
+      net_index = n+1
47 
+      net.vm.hostname = "net-#{net_index}"
48 
+      net.vm.provider "virtualbox" do |vb|
49 
+        vb.customize ["modifyvm", :id, "--memory", "1024"]
50 
+      end
51 
+      net.vm.network :private_network, ip: "#{net_ip}"
52 
+      net.vm.provision :shell, inline: $bootstrap
53 
+    end
54 
+  end
55 
+
56 
+end
libnetwork/docs/vagrant.md
History View file @ ca7aa81
0 57 
new file mode 100644
... ... 
@@ -0,0 +1,185 @@
0 
+# Vagrant Setup to Test the Overlay Driver
1 
+
2 
+This documentation highlights how to use Vagrant to start a three nodes setup to test Docker network.
3 
+
4 
+## Pre-requisites
5 
+
6 
+This was tested on:
7 
+
8 
+- Vagrant 1.7.2
9 
+- VirtualBox 4.3.26
10 
+
11 
+## Machine Setup
12 
+
13 
+The Vagrantfile provided will start three virtual machines. One will act as a consul server, and the other two will act as Docker host.
14 
+The experimental version of Docker is installed.
15 
+
16 
+- `consul-server` is the Consul server node, based on Ubuntu 14.04, this has IP 192.168.33.10
17 
+- `net-1` is the first Docker host based on Ubuntu 14.10, this has IP 192.168.33.11
18 
+- `net-2` is the second Docker host based on Ubuntu 14.10, this has IP 192.168.33.12
19 
+
20 
+## Getting Started
21 
+
22 
+Clone this repo, change to the `docs` directory and let Vagrant do the work.
23 
+
24 
+    $ vagrant up
25 
+    $ vagrant status
26 
+    Current machine states:
27 
+
28 
+    consul-server             running (virtualbox)
29 
+    net-1                     running (virtualbox)
30 
+    net-2                     running (virtualbox)
31 
+
32 
+You are now ready to SSH to the Docker hosts and start containers.
33 
+
34 
+    $ vagrant ssh net-1
35 
+    vagrant@net-1:~$ docker version
36 
+    Client version: 1.8.0-dev
37 
+    ...<snip>...
38 
+
39 
+Check that Docker network is functional by listing the default networks:
40 
+
41 
+    vagrant@net-1:~$ docker network ls
42 
+    NETWORK ID          NAME                TYPE
43 
+    4275f8b3a821        none                null
44 
+    80eba28ed4a7        host                host
45 
+    64322973b4aa        bridge              bridge
46 
+
47 
+No services has been published so far, so the `docker service ls` will return an empty list:
48 
+
49 
+    $ docker service ls
50 
+    SERVICE ID          NAME                NETWORK             CONTAINER
51 
+
52 
+Start a container and check the content of `/etc/hosts`.
53 
+
54 
+    $ docker run -it --rm ubuntu:14.04 bash
55 
+    root@df479e660658:/# cat /etc/hosts
56 
+    172.21.0.3	df479e660658
57 
+    127.0.0.1	localhost
58 
+    ::1	localhost ip6-localhost ip6-loopback
59 
+    fe00::0	ip6-localnet
60 
+    ff00::0	ip6-mcastprefix
61 
+    ff02::1	ip6-allnodes
62 
+    ff02::2	ip6-allrouters
63 
+    172.21.0.3	distracted_bohr
64 
+    172.21.0.3	distracted_bohr.multihost
65 
+
66 
+In a separate terminal on `net-1` list the networks again. You will see that the _multihost_ overlay now appears.
67 
+The overlay network _multihost_ is your default network. This was setup by the Docker daemon during the Vagrant provisioning. Check `/etc/default/docker` to see the options that were set.
68 
+
69 
+    vagrant@net-1:~$ docker network ls
70 
+    NETWORK ID          NAME                TYPE
71 
+    4275f8b3a821        none                null
72 
+    80eba28ed4a7        host                host
73 
+    64322973b4aa        bridge              bridge
74 
+    b5c9f05f1f8f        multihost           overlay
75 
+
76 
+Now in a separate terminal, SSH to `net-2`, check the network and services. The networks will be the same, and the default network will also be _multihost_ of type overlay. But the service will show the container started on `net-1`:
77 
+
78 
+    $ vagrant ssh net-2
79 
+    vagrant@net-2:~$ docker service ls
80 
+    SERVICE ID          NAME                NETWORK             CONTAINER
81 
+    b00f2bfd81ac        distracted_bohr     multihost           df479e660658
82 
+
83 
+Start a container on `net-2` and check the `/etc/hosts`.
84 
+
85 
+    vagrant@net-2:~$ docker run -ti --rm ubuntu:14.04 bash
86 
+    root@2ac726b4ce60:/# cat /etc/hosts
87 
+    172.21.0.4	2ac726b4ce60
88 
+    127.0.0.1	localhost
89 
+    ::1	localhost ip6-localhost ip6-loopback
90 
+    fe00::0	ip6-localnet
91 
+    ff00::0	ip6-mcastprefix
92 
+    ff02::1	ip6-allnodes
93 
+    ff02::2	ip6-allrouters
94 
+    172.21.0.3	distracted_bohr
95 
+    172.21.0.3	distracted_bohr.multihost
96 
+    172.21.0.4	modest_curie
97 
+    172.21.0.4	modest_curie.multihost
98 
+
99 
+You will see not only the container that you just started on `net-2` but also the container that you started earlier on `net-1`.
100 
+And of course you will be able to ping each container.
101 
+
102 
+## Creating a Non Default Overlay Network
103 
+
104 
+In the previous test we started containers with regular options `-ti --rm` and these containers got placed automatically in the default network which was set to be the _multihost_ network of type overlay.
105 
+
106 
+But you could create your own overlay network and start containers in it. Let's create a new overlay network.
107 
+On one of your Docker hosts, `net-1` or `net-2` do:
108 
+
109 
+    $ docker network create -d overlay foobar
110 
+    8805e22ad6e29cd7abb95597c91420fdcac54f33fcdd6fbca6dd4ec9710dd6a4
111 
+    $ docker network ls
112 
+    NETWORK ID          NAME                TYPE
113 
+    a77e16a1e394        host                host
114 
+    684a4bb4c471        bridge              bridge
115 
+    8805e22ad6e2        foobar              overlay
116 
+    b5c9f05f1f8f        multihost           overlay
117 
+    67d5a33a2e54        none                null
118 
+
119 
+Automatically, the second host will also see this network. To start a container on this new network, simply use the `--publish-service` option of `docker run` like so:
120 
+
121 
+    $ docker run -it --rm --publish-service=bar.foobar.overlay ubuntu:14.04 bash
122 
+
123 
+Note, that you could directly start a container with a new overlay using the `--publish-service` option and it will create the network automatically.
124 
+
125 
+Check the docker services now:
126 
+
127 
+    $ docker service ls
128 
+    SERVICE ID          NAME                NETWORK             CONTAINER
129 
+    b1ffdbfb1ac6        bar                 foobar              6635a3822135
130 
+
131 
+Repeat the getting started steps, by starting another container in this new overlay on the other host, check the `/etc/hosts` file and try to ping each container.
132 
+
133 
+## A look at the interfaces
134 
+
135 
+This new Docker multihost networking is made possible via VXLAN tunnels and the use of network namespaces.
136 
+Check the [design](design.md) documentation for all the details. But to explore these concepts a bit, nothing beats an example.
137 
+
138 
+With a running container in one overlay, check the network namespace:
139 
+
140 
+    $ docker inspect -f '{{ .NetworkSettings.SandboxKey}}' 6635a3822135
141 
+    /var/run/docker/netns/6635a3822135
142 
+
143 
+This is a none default location for network namespaces which might confuse things a bit. So let's become root, head over to this directory that contains the network namespaces of the containers and check the interfaces:
144 
+
145 
+    $ sudo su
146 
+    root@net-2:/home/vagrant# cd /var/run/docker/
147 
+    root@net-2:/var/run/docker# ls netns
148 
+    6635a3822135
149 
+    8805e22ad6e2
150 
+
151 
+To be able to check the interfaces in those network namespace using `ip` command, just create a symlink for `netns` that points to `/var/run/docker/netns`:
152 
+
153 
+    root@net-2:/var/run# ln -s /var/run/docker/netns netns
154 
+    root@net-2:/var/run# ip netns show
155 
+    6635a3822135
156 
+    8805e22ad6e2
157 
+
158 
+The two namespace ID return are the ones of the running container on that host and the one of the actual overlay network the container is in.
159 
+Let's check the interfaces in the container:
160 
+
161 
+    root@net-2:/var/run/docker# ip netns exec 6635a3822135 ip addr show eth0
162 
+    15: eth0: <BROADCAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
163 
+        link/ether 02:42:b3:91:22:c3 brd ff:ff:ff:ff:ff:ff
164 
+        inet 172.21.0.5/16 scope global eth0
165 
+           valid_lft forever preferred_lft forever
166 
+        inet6 fe80::42:b3ff:fe91:22c3/64 scope link
167 
+           valid_lft forever preferred_lft forever
168 
+
169 
+Indeed we get back the network interface of our running container, same MAC address, same IP.
170 
+If we check the links of the overlay namespace we see our vxlan interface and the VLAN ID being used.
171 
+
172 
+    root@net-2:/var/run/docker# ip netns exec 8805e22ad6e2 ip -d link show
173 
+    ...<snip>...
174 
+    14: vxlan1: <BROADCAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master br0 state UNKNOWN mode DEFAULT group default
175 
+        link/ether 7a:af:20:ee:e3:81 brd ff:ff:ff:ff:ff:ff promiscuity 1
176 
+        vxlan id 256 srcport 32768 61000 dstport 8472 proxy l2miss l3miss ageing 300
177 
+        bridge_slave
178 
+    16: veth2: <BROADCAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master br0 state UP mode DEFAULT group default qlen 1000
179 
+        link/ether 46:b1:e2:5c:48:a8 brd ff:ff:ff:ff:ff:ff promiscuity 1
180 
+        veth
181 
+        bridge_slave
182 
+
183 
+If you sniff packets on these interfaces you will see the traffic between your containers.
184 
+