[ovs-dev] [PATCH 2/2] INSTALL.Docker: A readme file for OVS integration with Docker.

[Gurucharan Shetty]

Open vSwitch does not have native integration with Docker.
INSTALL.Docker explains how Open vSwitch can be integrated
with docker non-natively.

Signed-off-by: Gurucharan Shetty <gshetty at nicira.com>
---
 INSTALL.Docker | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 Makefile.am    |  1 +
 2 files changed, 83 insertions(+)
 create mode 100644 INSTALL.Docker

diff --git a/INSTALL.Docker b/INSTALL.Docker
new file mode 100644
index 0000000..e50bce0
--- /dev/null
+++ b/INSTALL.Docker
@@ -0,0 +1,82 @@
+                 How to Use Open vSwitch with Docker
+                 ====================================
+
+This document describes how to use Open vSwitch with Docker 1.2.0 or
+later.  This document assumes that you followed INSTALL or installed
+Open vSwitch from distribution packaging such as a .deb or .rpm.
+Consult www.docker.com for instructions on how to install Docker.
+
+Limitations
+-----------
+Currently there is no native integration of Open vSwitch in Docker, i.e.,
+one cannot use the Docker client to automatically add a container's
+network interface to an Open vSwitch bridge during the creation of the
+container.  This document describes addition of new network interfaces to an
+already created container and inturn attaching that interface as a port to an
+Open vSwitch bridge.
+
+Setup
+-----
+* Create your container, e.g.:
+
+% docker run -d ubuntu:14.04 /bin/sh -c \
+"while true; do echo hello world; sleep 1; done"
+
+The above command creates a container with one network interface 'eth0'
+and attaches it to a Linux bridge called 'docker0'.  'eth0' by default
+gets an IP address in the 172.17.0.0/16 space.  Docker sets up iptables
+NAT rules to let this interface talk to the outside world.  Also since
+it is connected to 'docker0' bridge, it can talk to all other containers
+connected to the same bridge.  If you prefer that no network interface be
+created by default, you can start your container with
+the option '--net=none', e,g.:
+
+% docker run -d --net=none ubuntu:14.04 /bin/sh -c \
+"while true; do echo hello world; sleep 1; done"
+
+The above commands will return a container id.  You will need to pass this
+value to the utility 'ovs-docker' to create network interfaces attached to an
+Open vSwitch bridge as a port.  This document will reference this value
+as $CONTAINER_ID in the next steps.
+
+* Add a new network interface to the container and attach it to an Open vSwitch
+  bridge.  e.g:
+
+% ovs-docker add-port br-int eth1 $CONTAINER_ID
+
+The above command will create a network interface 'eth1' inside the container
+and then attaches it to the Open vSwitch bridge 'br-int'.  This is done by
+creating a veth pair.  One end of the interface becomes 'eth1' inside the
+container and the other end attached to 'br-int'.
+
+The script also lets one to add an IP address to the interface.  e.g:
+
+% ovs-docker add-port br-int eth1 $CONTAINER_ID 192.168.1.1/24
+
+* A previously added network interface can be deleted.  e.g:
+
+% ovs-docker del-port br-int eth1 $CONTAINER_ID
+
+All the previously added Open vSwitch interfaces inside a container can be
+deleted.  e.g:
+
+% ovs-docker del-ports br-int $CONTAINER_ID
+
+It is important that the same $CONTAINER_ID be passed to both add-port
+and del-port[s] commands.
+
+* More network control.
+
+Once a container interface is added to an Open vSwitch bridge, one can
+set VLANs, create Tunnels, add OpenFlow rules etc for more network control.
+Please read the man pages of ovs-vsctl, ovs-ofctl, ovs-vswitchd,
+ovsdb-server ovs-vswitchd.conf.db etc for more details.
+
+Docker networking is quite flexible and can be used in multiple ways.  For more
+information, please read:
+https://docs.docker.com/articles/networking
+
+Bug Reporting
+-------------
+
+Please report problems to bugs at openvswitch.org.
diff --git a/Makefile.am b/Makefile.am
index 77ceec6..43cc420 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -68,6 +68,7 @@ EXTRA_DIST = \
 	FAQ \
 	INSTALL \
 	INSTALL.Debian \
+	INSTALL.Docker \
         INSTALL.DPDK \
 	INSTALL.Fedora \
 	INSTALL.KVM \
-- 
1.9.1