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.9.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 Docker 1.9.0 comes with support for multi-host networking.  Integration
  10 of Docker networking and Open vSwitch can be achieved via Open vSwitch
  11 virtual network (OVN).
  12
  13
  14 Setup
  15 =====
  16
  17 For multi-host networking with OVN and Docker, Docker has to be started
  18 with a destributed key-value store.  For e.g., if you decide to use consul
  19 as your distributed key-value store, and your host IP address is $HOST_IP,
  20 start your Docker daemon with:
  21
  22 ```
  23 docker daemon --cluster-store=consul://127.0.0.1:8500 \
  24 --cluster-advertise=$HOST_IP:0
  25 ```
  26
  27 OVN provides network virtualization to containers.  OVN's integration with
  28 Docker currently works in two modes - the "underlay" mode or the "overlay"
  29 mode.
  30
  31 In the "underlay" mode, OVN requires a OpenStack setup to provide container
  32 networking.  In this mode, one can create logical networks and can have
  33 containers running inside VMs, standalone VMs (without having any containers
  34 running inside them) and physical machines connected to the same logical
  35 network.  This is a multi-tenant, multi-host solution.
  36
  37 In the "overlay" mode, OVN can create a logical network amongst containers
  38 running on multiple hosts.  This is a single-tenant (extendable to
  39 multi-tenants depending on the security characteristics of the workloads),
  40 multi-host solution.  In this mode, you do not need a pre-created OpenStack
  41 setup.
  42
  43 For both the modes to work, a user has to install and start Open vSwitch in
  44 each VM/host that he plans to run his containers.
  45
  46
  47 The "overlay" mode
  48 ==================
  49
  50 OVN in "overlay" mode needs a minimum Open vSwitch version of 2.5.
  51
  52 * Start the central components.
  53
  54 OVN architecture has a central component which stores your networking intent
  55 in a database.  On one of your machines, with an IP Address of $CENTRAL_IP,
  56 where you have installed and started Open vSwitch, you will need to start some
  57 central components.
  58
  59 Start ovn-northd daemon.  This daemon translates networking intent from Docker
  60 stored in the OVN_Northbound database to logical flows in OVN_Southbound
  61 database.
  62
  63 ```
  64 /usr/share/openvswitch/scripts/ovn-ctl start_northd
  65 ```
  66
  67 * One time setup.
  68
  69 On each host, where you plan to spawn your containers, you will need to
  70 run the following command once.  (You need to run it again if your OVS database
  71 gets cleared.  It is harmless to run it again in any case.)
  72
  73 $LOCAL_IP in the below command is the IP address via which other hosts
  74 can reach this host.  This acts as your local tunnel endpoint.
  75
  76 $ENCAP_TYPE is the type of tunnel that you would like to use for overlay
  77 networking.  The options are "geneve" or "stt".  (Please note that your
  78 kernel should have support for your chosen $ENCAP_TYPE.  Both geneve
  79 and stt are part of the Open vSwitch kernel module that is compiled from this
  80 repo.  If you use the Open vSwitch kernel module from upstream Linux,
  81 you will need a minumum kernel version of 3.18 for geneve.  There is no stt
  82 support in upstream Linux.  You can verify whether you have the support in your
  83 kernel by doing a "lsmod | grep $ENCAP_TYPE".)
  84
  85 ```
  86 ovs-vsctl set Open_vSwitch . external_ids:ovn-remote="tcp:$CENTRAL_IP:6642" \
  87   external_ids:ovn-nb="tcp:$CENTRAL_IP:6641" external_ids:ovn-encap-ip=$LOCAL_IP external_ids:ovn-encap-type="$ENCAP_TYPE"
  88 ```
  89
  90 And finally, start the ovn-controller.  (You need to run the below command
  91 on every boot)
  92
  93 ```
  94 /usr/share/openvswitch/scripts/ovn-ctl start_controller
  95 ```
  96
  97 * Start the Open vSwitch network driver.
  98
  99 By default Docker uses Linux bridge for networking.  But it has support
 100 for external drivers.  To use Open vSwitch instead of the Linux bridge,
 101 you will need to start the Open vSwitch driver.
 102
 103 The Open vSwitch driver uses the Python's flask module to listen to
 104 Docker's networking api calls.  So, if your host does not have Python's
 105 flask module, install it with:
 106
 107 ```
 108 easy_install -U pip
 109 pip install Flask
 110 ```
 111
 112 Start the Open vSwitch driver on every host where you plan to create your
 113 containers.  (Please read a note on $OVS_PYTHON_LIBS_PATH that is used below
 114 at the end of this document.)
 115
 116 ```
 117 PYTHONPATH=$OVS_PYTHON_LIBS_PATH ovn-docker-overlay-driver --detach
 118 ```
 119
 120 Docker has inbuilt primitives that closely match OVN's logical switches
 121 and logical port concepts.  Please consult Docker's documentation for
 122 all the possible commands.  Here are some examples.
 123
 124 * Create your logical switch.
 125
 126 To create a logical switch with name 'foo', on subnet '192.168.1.0/24' run:
 127
 128 ```
 129 NID=`docker network create -d openvswitch --subnet=192.168.1.0/24 foo`
 130 ```
 131
 132 * List your logical switches.
 133
 134 ```
 135 docker network ls
 136 ```
 137
 138 You can also look at this logical switch in OVN's northbound database by
 139 running the following command.
 140
 141 ```
 142 ovn-nbctl --db=tcp:$CENTRAL_IP:6640 ls-list
 143 ```
 144
 145 * Docker creates your logical port and attaches it to the logical network
 146 in a single step.
 147
 148 For e.g., to attach a logical port to network 'foo' inside cotainer busybox,
 149 run:
 150
 151 ```
 152 docker run -itd --net=foo --name=busybox busybox
 153 ```
 154
 155 * List all your logical ports.
 156
 157 Docker currently does not have a CLI command to list all your logical ports.
 158 But you can look at them in the OVN database, by running:
 159
 160 ```
 161 ovn-nbctl --db=tcp:$CENTRAL_IP:6640 lsp-list $NID
 162 ```
 163
 164 * You can also create a logical port and attach it to a running container.
 165
 166 ```
 167 docker network create -d openvswitch --subnet=192.168.2.0/24 bar
 168 docker network connect bar busybox
 169 ```
 170
 171 You can delete your logical port and detach it from a running container by
 172 running:
 173
 174 ```
 175 docker network disconnect bar busybox
 176 ```
 177
 178 * You can delete your logical switch by running:
 179
 180 ```
 181 docker network rm bar
 182 ```
 183
 184
 185 The "underlay" mode
 186 ===================
 187
 188 This mode requires that you have a OpenStack setup pre-installed with OVN
 189 providing the underlay networking.
 190
 191 * One time setup.
 192
 193 A OpenStack tenant creates a VM with a single network interface (or multiple)
 194 that belongs to management logical networks.  The tenant needs to fetch the
 195 port-id associated with the interface via which he plans to send the container
 196 traffic inside the spawned VM.  This can be obtained by running the
 197 below command to fetch the 'id'  associated with the VM.
 198
 199 ```
 200 nova list
 201 ```
 202
 203 and then by running:
 204
 205 ```
 206 neutron port-list --device_id=$id
 207 ```
 208
 209 Inside the VM, download the OpenStack RC file that contains the tenant
 210 information (henceforth referred to as 'openrc.sh').  Edit the file and add the
 211 previously obtained port-id information to the file by appending the following
 212 line: export OS_VIF_ID=$port_id.  After this edit, the file will look something
 213 like:
 214
 215 ```
 216 #!/bin/bash
 217 export OS_AUTH_URL=http://10.33.75.122:5000/v2.0
 218 export OS_TENANT_ID=fab106b215d943c3bad519492278443d
 219 export OS_TENANT_NAME="demo"
 220 export OS_USERNAME="demo"
 221 export OS_VIF_ID=e798c371-85f4-4f2d-ad65-d09dd1d3c1c9
 222 ```
 223
 224 * Create the Open vSwitch bridge.
 225
 226 If your VM has one ethernet interface (e.g.: 'eth0'), you will need to add
 227 that device as a port to an Open vSwitch bridge 'breth0' and move its IP
 228 address and route related information to that bridge. (If it has multiple
 229 network interfaces, you will need to create and attach an Open vSwitch bridge
 230 for the interface via which you plan to send your container traffic.)
 231
 232 If you use DHCP to obtain an IP address, then you should kill the DHCP client
 233 that was listening on the physical Ethernet interface (e.g. eth0) and start
 234 one listening on the Open vSwitch bridge (e.g. breth0).
 235
 236 Depending on your VM, you can make the above step persistent across reboots.
 237 For e.g.:, if your VM is Debian/Ubuntu, you can read
 238 [openvswitch-switch.README.Debian].  If your VM is RHEL based, you can read
 239 [README.RHEL]
 240
 241
 242 * Start the Open vSwitch network driver.
 243
 244 The Open vSwitch driver uses the Python's flask module to listen to
 245 Docker's networking api calls.  The driver also uses OpenStack's
 246 python-neutronclient libraries.  So, if your host does not have Python's
 247 flask module or python-neutronclient install them with:
 248
 249 ```
 250 easy_install -U pip
 251 pip install python-neutronclient
 252 pip install Flask
 253 ```
 254
 255 Source the openrc file. e.g.:
 256 ````
 257 . ./openrc.sh
 258 ```
 259
 260 Start the network driver and provide your OpenStack tenant password
 261 when prompted.  (Please read a note on $OVS_PYTHON_LIBS_PATH that is used below
 262 at the end of this document.)
 263
 264 ```
 265 PYTHONPATH=$OVS_PYTHON_LIBS_PATH ovn-docker-underlay-driver --bridge breth0 \
 266 --detach
 267 ```
 268
 269 From here-on you can use the same Docker commands as described in the
 270 section 'The "overlay" mode'.
 271
 272 Please read 'man ovn-architecture' to understand OVN's architecture in
 273 detail.
 274
 275 Note on $OVS_PYTHON_LIBS_PATH
 276 =============================
 277
 278 $OVS_PYTHON_LIBS_PATH should point to the directory where Open vSwitch
 279 python modules are installed.  If you installed Open vSwitch python
 280 modules via the debian package of 'python-openvswitch' or via pip by
 281 running 'pip install ovs', you do not need to specify the path.
 282 If you installed it by following the instructions in INSTALL.md, you
 283 should specify the path.  The path in that case depends on the options passed
 284 to ./configure.  (It is usually either '/usr/share/openvswitch/python' or
 285 '/usr/local/share/openvswitch/python'.)
 286
 287 [INSTALL.md]: INSTALL.md
 288 [openvswitch-switch.README.Debian]: debian/openvswitch-switch.README.Debian
 289 [README.RHEL]: rhel/README.RHEL