From f16dceb63233bd2c1fd327b92d7112e8012347ac Mon Sep 17 00:00:00 2001 From: David Currie Date: Sun, 8 Nov 2015 22:58:10 +0000 Subject: [PATCH] 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 --- .../networking/get-started-overlay.md | 113 ++++++++++-------- 1 file changed, 60 insertions(+), 53 deletions(-) diff --git a/docs/userguide/networking/get-started-overlay.md b/docs/userguide/networking/get-started-overlay.md index fc0acfa44c..708684e2da 100644 --- a/docs/userguide/networking/get-started-overlay.md +++ b/docs/userguide/networking/get-started-overlay.md @@ -7,13 +7,13 @@ keywords = ["Examples, Usage, network, docker, documentation, user guide, multih parent = "smn_networking" weight=-3 +++ - + # Get started with multi-host networking 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 -`overlay` network driver. Unlike `bridge` networks overlay networks require +network. Docker Engine supports multi-host networking out-of-the-box through the +`overlay` network driver. Unlike `bridge` networks, overlay networks require some pre-existing conditions before you can create one. These conditions are: * 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. Though Docker Machine and Docker Swarm are not mandatory to experience Docker -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 +multi-host networking, this example uses them to illustrate how they are +integrated. You'll use Machine to create both the key-value store server and the host cluster. This example creates a Swarm cluster. ## Prerequisites @@ -39,10 +39,10 @@ Machine to the latest versions. ## Step 1: Set up a key-value store -An overlay network requires a key-value store. The key-value stores information -about the network state which includes discovery, networks, endpoints, -ip-addresses, and more. Docker supports Consul, Etcd, and ZooKeeper (Distributed -store) key-value stores. This example uses Consul. +An overlay network requires a key-value store. The key-value store holds +information about the network state which includes discovery, networks, +endpoints, IP addresses, and more. Docker supports Consul, Etcd, and ZooKeeper +key-value stores. This example uses Consul. 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" \ progrium/consul -server -bootstrap - You passed the `docker run` command the connection configuration using a bash - expansion `$(docker-machine config mh-keystore)`. The client started a - `progrium/consul` image running in the `mh-keystore` machine. The server is called `consul`and is listening port `8500`. + A bash expansion `$(docker-machine config mh-keystore)` is used to pass the + 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 on port `8500`. 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 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; 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. @@ -91,7 +92,7 @@ that machine options that are needed by the `overlay` network driver. $ docker-machine create \ -d virtualbox \ - --swarm --swarm-image="swarm" --swarm-master \ + --swarm --swarm-master \ --swarm-discovery="consul://$(docker-machine ip mh-keystore):8500" \ --engine-opt="cluster-store=consul://$(docker-machine ip mh-keystore):8500" \ --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. $ docker-machine create -d virtualbox \ - --swarm --swarm-image="swarm" \ + --swarm \ --swarm-discovery="consul://$(docker-machine ip mh-keystore):8500" \ --engine-opt="cluster-store=consul://$(docker-machine ip mh-keystore):8500" \ --engine-opt="cluster-advertise=eth1:2376" \ @@ -112,14 +113,13 @@ that machine options that are needed by the `overlay` network driver. $ docker-machine ls NAME ACTIVE DRIVER STATE URL SWARM - default virtualbox Running tcp://192.168.99.100: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-demo1 virtualbox Running tcp://192.168.99.105:2376 mhs-demo0 + default - virtualbox Running tcp://192.168.99.100: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-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. - Leave your terminal open and go onto the next step. ## Step 3: Create the overlay Network @@ -155,7 +155,7 @@ To create an overlay network Total Memory: 2.043 GiB 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. @@ -167,54 +167,51 @@ To create an overlay network $ docker network ls NETWORK ID NAME DRIVER - 412c2496d0eb mhs-demo1/host host - dd51763e6dd2 mhs-demo0/bridge bridge - 6b07d0be843f my-net overlay - b4234109bd9b mhs-demo0/none null - 1aeead6dd890 mhs-demo0/host host - d0bb78cbe7bd mhs-demo1/bridge bridge - 1c0eb8f69ebb mhs-demo1/none null + 412c2496d0eb mhs-demo1/host host + dd51763e6dd2 mhs-demo0/bridge bridge + 6b07d0be843f my-net overlay + b4234109bd9b mhs-demo0/none null + 1aeead6dd890 mhs-demo0/host host + d0bb78cbe7bd mhs-demo1/bridge bridge + 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) $ docker network ls NETWORK ID NAME DRIVER - 6b07d0be843f my-net overlay - dd51763e6dd2 bridge bridge - b4234109bd9b none null - 1aeead6dd890 host host + 6b07d0be843f my-net overlay + dd51763e6dd2 bridge bridge + b4234109bd9b none null + 1aeead6dd890 host host $ eval $(docker-machine env mhs-demo1) $ docker network ls NETWORK ID NAME DRIVER - d0bb78cbe7bd bridge bridge - 1c0eb8f69ebb none null - 412c2496d0eb host host - 6b07d0be843f my-net overlay + d0bb78cbe7bd bridge bridge + 1c0eb8f69ebb none null + 412c2496d0eb host host + 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 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 - This command starts a web server on the Swarm master. - -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. +4. Run a BusyBox instance on the `mhs-demo1` instance and get the contents of the Nginx server's home page. $ docker run -it --rm --net=my-net --env="constraint:node==mhs-demo1" busybox wget -O- http://web Unable to find image 'busybox:latest' locally @@ -284,7 +281,7 @@ to have external connectivity outside of their cluster. 412c2496d0eb host host 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 1: lo: 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. -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. @@ -336,7 +335,15 @@ You can try starting a second network on your existing Swarm cluster using Docke 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