docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updates to Get started with multi-host networking 

Updates primarily to expand usage of Swarm cluster and make Compose
section more verbose plus other minor corrections.

Signed-off-by: David Currie <david_currie@uk.ibm.com>
This commit is contained in:
David Currie 2015-11-08 22:58:10 +00:00
parent 37dfae3cde
commit f16dceb632
1 changed files with 60 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
docs/userguide/networking/get-started-overlay.md
View File

@ -7,13 +7,13 @@ keywords = ["Examples, Usage, network, docker, documentation, user guide, multih
parent = "smn_networking" parent = "smn_networking"
weight=-3 weight=-3
+++ +++
<![end-metadata]--> <![end-metadata]-->
# Get started with multi-host networking # Get started with multi-host networking
This article uses an example to explain the basics of creating a multi-host This article uses an example to explain the basics of creating a multi-host
network. Docker Engine supports multi-host-networking out-of-the-box through the network. Docker Engine supports multi-host networking out-of-the-box through the
`overlay` network driver. Unlike `bridge` networks overlay networks require `overlay` network driver. Unlike `bridge` networks, overlay networks require
some pre-existing conditions before you can create one. These conditions are: some pre-existing conditions before you can create one. These conditions are:
* A host with a 3.16 kernel version or higher. * A host with a 3.16 kernel version or higher.
@ -22,8 +22,8 @@ some pre-existing conditions before you can create one. These conditions are:
* A properly configured Engine `daemon` on each host in the cluster. * A properly configured Engine `daemon` on each host in the cluster.
Though Docker Machine and Docker Swarm are not mandatory to experience Docker Though Docker Machine and Docker Swarm are not mandatory to experience Docker
multi-host-networking, this example uses them to illustrate how they are multi-host networking, this example uses them to illustrate how they are
integrated. You'll use Machine to create both the the key-value store integrated. You'll use Machine to create both the key-value store
server and the host cluster. This example creates a Swarm cluster. server and the host cluster. This example creates a Swarm cluster.
## Prerequisites ## Prerequisites
@ -39,10 +39,10 @@ Machine to the latest versions.
## Step 1: Set up a key-value store ## Step 1: Set up a key-value store
An overlay network requires a key-value store. The key-value stores information An overlay network requires a key-value store. The key-value store holds
about the network state which includes discovery, networks, endpoints, information about the network state which includes discovery, networks,
ip-addresses, and more. Docker supports Consul, Etcd, and ZooKeeper (Distributed endpoints, IP addresses, and more. Docker supports Consul, Etcd, and ZooKeeper
store) key-value stores. This example uses Consul. key-value stores. This example uses Consul.
1. Log into a system prepared with the prerequisite Docker Engine, Docker Machine, and VirtualBox software. 1. Log into a system prepared with the prerequisite Docker Engine, Docker Machine, and VirtualBox software.
@ -62,9 +62,10 @@ store) key-value stores. This example uses Consul.
-h "consul" \ -h "consul" \
progrium/consul -server -bootstrap progrium/consul -server -bootstrap
You passed the `docker run` command the connection configuration using a bash A bash expansion `$(docker-machine config mh-keystore)` is used to pass the
expansion `$(docker-machine config mh-keystore)`. The client started a connection configuration to the `docker run` command. The client starts a
`progrium/consul` image running in the `mh-keystore` machine. The server is called `consul`and is listening port `8500`. `progrium/consul` image running in the `mh-keystore` machine. The server is
called `consul` and is listening on port `8500`.
4. Set your local environment to the `mh-keystore` machine. 4. Set your local environment to the `mh-keystore` machine.
@ -82,7 +83,7 @@ Keep your terminal open and move onto the next step.
## Step 2: Create a Swarm cluster ## Step 2: Create a Swarm cluster
In this step, you use `docker-machine` to provision the hosts for your network. In this step, you use `docker-machine` to provision the hosts for your network.
At this point, you won't actually created the network. You'll create several At this point, you won't actually create the network. You'll create several
machines in VirtualBox. One of the machines will act as the Swarm master; machines in VirtualBox. One of the machines will act as the Swarm master;
you'll create that first. As you create each host, you'll pass the Engine on you'll create that first. As you create each host, you'll pass the Engine on
that machine options that are needed by the `overlay` network driver. that machine options that are needed by the `overlay` network driver.
@ -91,7 +92,7 @@ that machine options that are needed by the `overlay` network driver.
$ docker-machine create \ $ docker-machine create \
-d virtualbox \ -d virtualbox \
--swarm --swarm-image="swarm" --swarm-master \ --swarm --swarm-master \
--swarm-discovery="consul://$(docker-machine ip mh-keystore):8500" \ --swarm-discovery="consul://$(docker-machine ip mh-keystore):8500" \
--engine-opt="cluster-store=consul://$(docker-machine ip mh-keystore):8500" \ --engine-opt="cluster-store=consul://$(docker-machine ip mh-keystore):8500" \
--engine-opt="cluster-advertise=eth1:2376" \ --engine-opt="cluster-advertise=eth1:2376" \
@ -102,7 +103,7 @@ that machine options that are needed by the `overlay` network driver.
2. Create another host and add it to the Swarm cluster. 2. Create another host and add it to the Swarm cluster.
$ docker-machine create -d virtualbox \ $ docker-machine create -d virtualbox \
--swarm --swarm-image="swarm" \ --swarm \
--swarm-discovery="consul://$(docker-machine ip mh-keystore):8500" \ --swarm-discovery="consul://$(docker-machine ip mh-keystore):8500" \
--engine-opt="cluster-store=consul://$(docker-machine ip mh-keystore):8500" \ --engine-opt="cluster-store=consul://$(docker-machine ip mh-keystore):8500" \
--engine-opt="cluster-advertise=eth1:2376" \ --engine-opt="cluster-advertise=eth1:2376" \
@ -112,14 +113,13 @@ that machine options that are needed by the `overlay` network driver.
$ docker-machine ls $ docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM NAME ACTIVE DRIVER STATE URL SWARM
default virtualbox Running tcp://192.168.99.100:2376 default - virtualbox Running tcp://192.168.99.100:2376
mh-keystore virtualbox Running tcp://192.168.99.103:2376 mh-keystore * virtualbox Running tcp://192.168.99.103:2376
mhs-demo0 virtualbox Running tcp://192.168.99.104:2376 mhs-demo0 (master) mhs-demo0 - virtualbox Running tcp://192.168.99.104:2376 mhs-demo0 (master)
mhs-demo1 virtualbox Running tcp://192.168.99.105:2376 mhs-demo0 mhs-demo1 - virtualbox Running tcp://192.168.99.105:2376 mhs-demo0
At this point you have a set of hosts running on your network. You are ready to create a multi-host network for containers using these hosts. At this point you have a set of hosts running on your network. You are ready to create a multi-host network for containers using these hosts.
Leave your terminal open and go onto the next step. Leave your terminal open and go onto the next step.
## Step 3: Create the overlay Network ## Step 3: Create the overlay Network
@ -155,7 +155,7 @@ To create an overlay network
Total Memory: 2.043 GiB Total Memory: 2.043 GiB
Name: 30438ece0915 Name: 30438ece0915
From this information, you can see that you are running three containers and 2 images on the Master. From this information, you can see that you are running three containers and two images on the Master.
3. Create your `overlay` network. 3. Create your `overlay` network.
@ -167,54 +167,51 @@ To create an overlay network
$ docker network ls $ docker network ls
NETWORK ID NAME DRIVER NETWORK ID NAME DRIVER
412c2496d0eb mhs-demo1/host host 412c2496d0eb mhs-demo1/host host
dd51763e6dd2 mhs-demo0/bridge bridge dd51763e6dd2 mhs-demo0/bridge bridge
6b07d0be843f my-net overlay 6b07d0be843f my-net overlay
b4234109bd9b mhs-demo0/none null b4234109bd9b mhs-demo0/none null
1aeead6dd890 mhs-demo0/host host 1aeead6dd890 mhs-demo0/host host
d0bb78cbe7bd mhs-demo1/bridge bridge d0bb78cbe7bd mhs-demo1/bridge bridge
1c0eb8f69ebb mhs-demo1/none null 1c0eb8f69ebb mhs-demo1/none null
Because you are in the Swarm master environment, you see all the networks on all Swarm agents. Notice that each `NETWORK ID` is unique. The default networks on each engine and the single overlay network. As you are in the Swarm master environment, you see all the networks on all
the Swarm agents: the default networks on each engine and the single overlay
network. Notice that each `NETWORK ID` is unique.
5. Switch to each Swarm agent in turn and list the network. 5. Switch to each Swarm agent in turn and list the networks.
$ eval $(docker-machine env mhs-demo0) $ eval $(docker-machine env mhs-demo0)
$ docker network ls $ docker network ls
NETWORK ID NAME DRIVER NETWORK ID NAME DRIVER
6b07d0be843f my-net overlay 6b07d0be843f my-net overlay
dd51763e6dd2 bridge bridge dd51763e6dd2 bridge bridge
b4234109bd9b none null b4234109bd9b none null
1aeead6dd890 host host 1aeead6dd890 host host
$ eval $(docker-machine env mhs-demo1) $ eval $(docker-machine env mhs-demo1)
$ docker network ls $ docker network ls
NETWORK ID NAME DRIVER NETWORK ID NAME DRIVER
d0bb78cbe7bd bridge bridge d0bb78cbe7bd bridge bridge
1c0eb8f69ebb none null 1c0eb8f69ebb none null
412c2496d0eb host host 412c2496d0eb host host
6b07d0be843f my-net overlay 6b07d0be843f my-net overlay
Both agents reports it has the `my-net `network with the `6b07d0be843f` id. You have a multi-host container network running! Both agents report they have the `my-net` network with the `6b07d0be843f` ID.
You now have a multi-host container network running!
## Step 4: Run an application on your Network ## Step 4: Run an application on your Network
Once your network is created, you can start a container on any of the hosts and it automatically is part of the network. Once your network is created, you can start a container on any of the hosts and it automatically is part of the network.
1. Point your environment to your `mhs-demo0` instance. 1. Point your environment to the Swarm master.
$ eval $(docker-machine env mhs-demo0) $ eval $(docker-machine env --swarm mhs-demo0)
2. Start an Nginx server on `mhs-demo0`. 2. Start an Nginx web server on the `mhs-demo0` instance.
$ docker run -itd --name=web --net=my-net --env="constraint:node==mhs-demo0" nginx $ docker run -itd --name=web --net=my-net --env="constraint:node==mhs-demo0" nginx
This command starts a web server on the Swarm master. 4. Run a BusyBox instance on the `mhs-demo1` instance and get the contents of the Nginx server's home page.
3. Point your Machine environment to `mhs-demo1`
$ eval $(docker-machine env mhs-demo1)
4. Run a Busybox instance and get the contents of the Ngnix server's home page.
$ docker run -it --rm --net=my-net --env="constraint:node==mhs-demo1" busybox wget -O- http://web $ docker run -it --rm --net=my-net --env="constraint:node==mhs-demo1" busybox wget -O- http://web
Unable to find image 'busybox:latest' locally Unable to find image 'busybox:latest' locally
@ -284,7 +281,7 @@ to have external connectivity outside of their cluster.
412c2496d0eb host host 412c2496d0eb host host
97102a22e8d2 docker_gwbridge bridge 97102a22e8d2 docker_gwbridge bridge
2. Check the Ngnix container's network interfaces. 2. Check the Nginx container's network interfaces.
$ docker exec web ip addr $ docker exec web ip addr
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default
@ -314,9 +311,11 @@ to have external connectivity outside of their cluster.
You can try starting a second network on your existing Swarm cluster using Docker Compose. You can try starting a second network on your existing Swarm cluster using Docker Compose.
1. Log into the Swarm master. 1. If you haven't already, install Docker Compose.
2. Install Docker Compose. 2. Change your environment to the Swarm master.
$ eval $(docker-machine env --swarm mhs-demo0)
3. Create a `docker-compose.yml` file. 3. Create a `docker-compose.yml` file.
@ -336,7 +335,15 @@ You can try starting a second network on your existing Swarm cluster using Docke
6. Start the application with Compose. 6. Start the application with Compose.
$ docker-compose --x-networking up -d $ docker-compose --x-networking --project-name=counter up -d
7. Get the Swarm master's IP address.
$ docker-machine ip mhs-demo0
8. Put the IP address into your web browser.
Upon success, the browser should display the web application.
## Related information ## Related information