]>
Commit | Line | Data |
---|---|---|
542cc9bb TG |
1 | How to Use Open vSwitch with Docker |
2 | ==================================== | |
ec8f0f0c GS |
3 | |
4 | This document describes how to use Open vSwitch with Docker 1.2.0 or | |
4384556d GS |
5 | later. This document assumes that you installed Open vSwitch by following |
6 | [INSTALL.md] or by using the distribution packages such as .deb or .rpm. | |
7 | Consult www.docker.com for instructions on how to install Docker. | |
ec8f0f0c GS |
8 | |
9 | Limitations | |
10 | ----------- | |
11 | Currently there is no native integration of Open vSwitch in Docker, i.e., | |
12 | one cannot use the Docker client to automatically add a container's | |
13 | network interface to an Open vSwitch bridge during the creation of the | |
14 | container. This document describes addition of new network interfaces to an | |
15 | already created container and in turn attaching that interface as a port to an | |
62dbc5bd GS |
16 | Open vSwitch bridge. If and when there is a native integration of Open vSwitch |
17 | with Docker, the ovs-docker utility described in this document is expected to | |
18 | be retired. | |
ec8f0f0c GS |
19 | |
20 | Setup | |
21 | ----- | |
22 | * Create your container, e.g.: | |
23 | ||
542cc9bb | 24 | ``` |
ec8f0f0c GS |
25 | % docker run -d ubuntu:14.04 /bin/sh -c \ |
26 | "while true; do echo hello world; sleep 1; done" | |
542cc9bb | 27 | ``` |
ec8f0f0c GS |
28 | |
29 | The above command creates a container with one network interface 'eth0' | |
30 | and attaches it to a Linux bridge called 'docker0'. 'eth0' by default | |
31 | gets an IP address in the 172.17.0.0/16 space. Docker sets up iptables | |
32 | NAT rules to let this interface talk to the outside world. Also since | |
33 | it is connected to 'docker0' bridge, it can talk to all other containers | |
34 | connected to the same bridge. If you prefer that no network interface be | |
35 | created by default, you can start your container with | |
36 | the option '--net=none', e,g.: | |
37 | ||
542cc9bb | 38 | ``` |
ec8f0f0c GS |
39 | % docker run -d --net=none ubuntu:14.04 /bin/sh -c \ |
40 | "while true; do echo hello world; sleep 1; done" | |
542cc9bb | 41 | ``` |
ec8f0f0c GS |
42 | |
43 | The above commands will return a container id. You will need to pass this | |
44 | value to the utility 'ovs-docker' to create network interfaces attached to an | |
45 | Open vSwitch bridge as a port. This document will reference this value | |
46 | as $CONTAINER_ID in the next steps. | |
47 | ||
48 | * Add a new network interface to the container and attach it to an Open vSwitch | |
49 | bridge. e.g.: | |
50 | ||
542cc9bb | 51 | `% ovs-docker add-port br-int eth1 $CONTAINER_ID` |
ec8f0f0c GS |
52 | |
53 | The above command will create a network interface 'eth1' inside the container | |
54 | and then attaches it to the Open vSwitch bridge 'br-int'. This is done by | |
55 | creating a veth pair. One end of the interface becomes 'eth1' inside the | |
56 | container and the other end attaches to 'br-int'. | |
57 | ||
6dd3cc39 GS |
58 | The script also lets one to add IP address, MAC address, Gateway address and |
59 | MTU for the interface. e.g.: | |
ec8f0f0c | 60 | |
05444f07 GS |
61 | ``` |
62 | % ovs-docker add-port br-int eth1 $CONTAINER_ID --ipaddress=192.168.1.2/24 \ | |
6dd3cc39 | 63 | --macaddress=a2:c3:0d:49:7f:f8 --gateway=192.168.1.1 --mtu=1450 |
05444f07 | 64 | ``` |
ec8f0f0c GS |
65 | |
66 | * A previously added network interface can be deleted. e.g.: | |
67 | ||
542cc9bb | 68 | `% ovs-docker del-port br-int eth1 $CONTAINER_ID` |
ec8f0f0c GS |
69 | |
70 | All the previously added Open vSwitch interfaces inside a container can be | |
71 | deleted. e.g.: | |
72 | ||
542cc9bb | 73 | `% ovs-docker del-ports br-int $CONTAINER_ID` |
ec8f0f0c GS |
74 | |
75 | It is important that the same $CONTAINER_ID be passed to both add-port | |
76 | and del-port[s] commands. | |
77 | ||
78 | * More network control. | |
79 | ||
80 | Once a container interface is added to an Open vSwitch bridge, one can | |
81 | set VLANs, create Tunnels, add OpenFlow rules etc for more network control. | |
7894385a GS |
82 | Many times, it is important that the underlying network infrastructure is |
83 | plumbed (or programmed) before the application inside the container starts. | |
84 | To handle this, one can create a micro-container, attach an Open vSwitch | |
85 | interface to that container, set the UUIDS in OVSDB as mentioned in | |
86 | [IntegrationGuide.md] and then program the bridge to handle traffic coming out | |
87 | of that container. Now, you can start the main container asking it | |
88 | to share the network of the micro-container. When your application starts, | |
89 | the underlying network infrastructure would be ready. e.g.: | |
90 | ||
91 | ``` | |
92 | % docker run -d --net=container:$MICROCONTAINER_ID ubuntu:14.04 /bin/sh -c \ | |
93 | "while true; do echo hello world; sleep 1; done" | |
94 | ``` | |
95 | ||
ec8f0f0c | 96 | Please read the man pages of ovs-vsctl, ovs-ofctl, ovs-vswitchd, |
7894385a | 97 | ovsdb-server and ovs-vswitchd.conf.db etc for more details about Open vSwitch. |
ec8f0f0c GS |
98 | |
99 | Docker networking is quite flexible and can be used in multiple ways. For more | |
100 | information, please read: | |
101 | https://docs.docker.com/articles/networking | |
102 | ||
103 | Bug Reporting | |
104 | ------------- | |
105 | ||
106 | Please report problems to bugs@openvswitch.org. | |
9feb1017 TG |
107 | |
108 | [INSTALL.md]:INSTALL.md | |
7894385a | 109 | [IntegrationGuide.md]:IntegrationGuide.md |