INSTALL.Docker.md

   1 How to Use Open vSwitch with Docker
   2 ====================================
   3
   4 This document describes how to use Open vSwitch with Docker 1.2.0 or
   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.
   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
  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.
  19
  20 Setup
  21 -----
  22 * Create your container, e.g.:
  23
  24 ```
  25 % docker run -d ubuntu:14.04 /bin/sh -c \
  26 "while true; do echo hello world; sleep 1; done"
  27 ```
  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
  38 ```
  39 % docker run -d --net=none ubuntu:14.04 /bin/sh -c \
  40 "while true; do echo hello world; sleep 1; done"
  41 ```
  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
  51 `% ovs-docker add-port br-int eth1 $CONTAINER_ID`
  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
  58 The script also lets one to add IP address, MAC address, Gateway address and
  59 MTU for the interface.  e.g.:
  60
  61 ```
  62 % ovs-docker add-port br-int eth1 $CONTAINER_ID --ipaddress=192.168.1.2/24 \
  63 --macaddress=a2:c3:0d:49:7f:f8 --gateway=192.168.1.1 --mtu=1450
  64 ```
  65
  66 * A previously added network interface can be deleted.  e.g.:
  67
  68 `% ovs-docker del-port br-int eth1 $CONTAINER_ID`
  69
  70 All the previously added Open vSwitch interfaces inside a container can be
  71 deleted.  e.g.:
  72
  73 `% ovs-docker del-ports br-int $CONTAINER_ID`
  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.
  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
  96 Please read the man pages of ovs-vsctl, ovs-ofctl, ovs-vswitchd,
  97 ovsdb-server and ovs-vswitchd.conf.db etc for more details about Open vSwitch.
  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.
 107
 108 [INSTALL.md]:INSTALL.md
 109 [IntegrationGuide.md]:IntegrationGuide.md