From e895136580d7d5f8033f3dd0cc0d3c700403a0f7 Mon Sep 17 00:00:00 2001 From: Phil Whelan Date: Thu, 12 Nov 2015 15:37:11 -0800 Subject: [PATCH 1/2] typos Signed-off-by: Phil Whelan --- docs/networking.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/networking.md b/docs/networking.md index 4a46d94ec4..9e6caac2f7 100644 --- a/docs/networking.md +++ b/docs/networking.md @@ -56,7 +56,7 @@ As you can see here, the ID is the same on the two nodes, because it's the same network. If you want to create a local scope network (for example with the bridge -driver) you should use `/` otherwise your network will be created on a +driver) you should use `/`. Otherwise your network will be created on a random node. $ docker network create node-0/bridge2 -b bridge @@ -79,7 +79,7 @@ random node. ## Remove a network To remove a network you can use its ID or its name. -If two different networks have the same name, you may use `/`. +If two different networks have the same name, you can use `/`. $ docker network rm swarm_network 42131321acab3233ba342443Ba4312 @@ -94,8 +94,8 @@ If two different networks have the same name, you may use `/`. 8926accb25fd node-1/bridge bridge 6382abccd23d node-1/none null 5262bbfe5616 node-1/bridge2 bridge - -`swarm_network` was removed from every node, `bridge2` was removed only + +`swarm_network` was removed from every node, whereas `bridge2` was removed only from `node-0`. ## Docker Swarm documentation index From c8dd8d8b66d3c2d162248a1ca24e6a46c82e5e16 Mon Sep 17 00:00:00 2001 From: Alexandre Beslic Date: Mon, 14 Dec 2015 13:35:59 -0800 Subject: [PATCH 2/2] carry #1409, improve networking docs, remove duplicate link in discovery.md Signed-off-by: Alexandre Beslic --- docs/discovery.md | 1 - docs/networking.md | 162 +++++++++++++++++++++++++++------------------ 2 files changed, 96 insertions(+), 67 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 4ed4c85f7a..4213c0a108 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -218,4 +218,3 @@ discovery README in the Docker Swarm repository. - [Scheduler strategies](scheduler/strategy.md) - [Scheduler filters](scheduler/filter.md) - [Swarm API](api/swarm-api.md) -- [Docker Swarm overview](index.md) diff --git a/docs/networking.md b/docs/networking.md index 9e6caac2f7..76fb469d31 100644 --- a/docs/networking.md +++ b/docs/networking.md @@ -11,91 +11,121 @@ weight=4 # Networking -Docker Swarm is fully compatible for the new networking model added in docker 1.9 +Docker Swarm is fully compatible with Docker's networking features. This +includes the multi-host networking feature which allows creation of custom +container networks that span multiple Docker hosts. -## Setup +Before using Swarm with a custom network, read through the conceptual +information in [Docker container +networking](https://docs.docker.com/engine/userguide/networking/dockernetworks/). +You should also have walked through the [Get started with multi-host +networking](https://docs.docker.com/engine/userguide/networking/get-started-overlay/) +example. -To use multi-host networking you need to start your docker engines with -`--cluster-store` and `--cluster-advertise` as indicated in the docker -engine docs. +## Create a custom network in a Swarm cluster -### List networks +Multi-host networks require a key-value store. The key-value store holds +information about the network state which includes discovery, networks, +endpoints, IP addresses, and more. Through the Docker's libkv project, Docker +supports Consul, Etcd, and ZooKeeper key-value store backends. For details about +the supported backends, refer to the [libkv +project](https://github.com/docker/libkv). + +To create a custom network, you must choose a key-value store backend and +implement it on your network. Then, you configure the Docker Engine daemon to +use this store. Two required parameters, `--cluster-store` and +`--cluster-advertise`, refer to your key-value store server. + +Once you've configured and restarted the daemon on each Swarm node, you are +ready to create a network. + +## List networks This example assumes there are two nodes `node-0` and `node-1` in the cluster. +From a swarm node, list the networks: - $ docker network ls - NETWORK ID NAME DRIVER - 3dd50db9706d node-0/host host - 09138343e80e node-0/bridge bridge - 8834dbd552e5 node-0/none null - 45782acfe427 node-1/host host - 8926accb25fd node-1/bridge bridge - 6382abccd23d node-1/none null +```bash +$ docker network ls +NETWORK ID NAME DRIVER +3dd50db9706d node-0/host host +09138343e80e node-0/bridge bridge +8834dbd552e5 node-0/none null +45782acfe427 node-1/host host +8926accb25fd node-1/bridge bridge +6382abccd23d node-1/none null +``` As you can see, each network name is prefixed by the node name. ## Create a network -By default, swarm is using the `overlay` network driver, a global -scope driver. +By default, Swarm is using the `overlay` network driver, a global-scope network +driver. A global-scope network driver creates a network across an entire swarm. +When you create an `overlay` network under Swarm, you can omit the `-d` option: - $ docker network create swarm_network - 42131321acab3233ba342443Ba4312 - $ docker network ls - NETWORK ID NAME DRIVER - 3dd50db9706d node-0/host host - 09138343e80e node-0/bridge bridge - 8834dbd552e5 node-0/none null - 42131321acab node-0/swarm_network overlay - 45782acfe427 node-1/host host - 8926accb25fd node-1/bridge bridge - 6382abccd23d node-1/none null - 42131321acab node-1/swarm_network overlay +```bash +$ docker network create swarm_network +42131321acab3233ba342443Ba4312 +$ docker network ls +NETWORK ID NAME DRIVER +3dd50db9706d node-0/host host +09138343e80e node-0/bridge bridge +8834dbd552e5 node-0/none null +42131321acab node-0/swarm_network overlay +45782acfe427 node-1/host host +8926accb25fd node-1/bridge bridge +6382abccd23d node-1/none null +42131321acab node-1/swarm_network overlay +``` -As you can see here, the ID is the same on the two nodes, because it's the same -network. +As you can see here, both the `node-0/swarm_network` and the +`node-1/swarm_network` have the same ID. This is because when you create a +network on the swarm, it is accessible from all the nodes. -If you want to create a local scope network (for example with the bridge -driver) you should use `/`. Otherwise your network will be created on a -random node. +To create a local scope network (for example with the `bridge` network driver) you +should use `/` otherwise your network is created on a random node. - $ docker network create node-0/bridge2 -b bridge - 921817fefea521673217123abab223 - $ docker network create node-1/bridge2 -b bridge - 5262bbfe5616fef6627771289aacc2 - $ docker network ls - NETWORK ID NAME DRIVER - 3dd50db9706d node-0/host host - 09138343e80e node-0/bridge bridge - 8834dbd552e5 node-0/none null - 42131321acab node-0/swarm_network overlay - 921817fefea5 node-0/bridge2 brige - 45782acfe427 node-1/host host - 8926accb25fd node-1/bridge bridge - 6382abccd23d node-1/none null - 42131321acab node-1/swarm_network overlay - 5262bbfe5616 node-1/bridge2 bridge +```bash +$ docker network create node-0/bridge2 -b bridge +921817fefea521673217123abab223 +$ docker network create node-1/bridge2 -b bridge +5262bbfe5616fef6627771289aacc2 +$ docker network ls +NETWORK ID NAME DRIVER +3dd50db9706d node-0/host host +09138343e80e node-0/bridge bridge +8834dbd552e5 node-0/none null +42131321acab node-0/swarm_network overlay +921817fefea5 node-0/bridge2 brige +45782acfe427 node-1/host host +8926accb25fd node-1/bridge bridge +6382abccd23d node-1/none null +42131321acab node-1/swarm_network overlay +5262bbfe5616 node-1/bridge2 bridge +``` ## Remove a network -To remove a network you can use its ID or its name. -If two different networks have the same name, you can use `/`. +To remove a network you can use its ID or its name. If two different networks +have the same name, include the `` value: - $ docker network rm swarm_network - 42131321acab3233ba342443Ba4312 - $ docker network rm node-0/bridge2 - 921817fefea521673217123abab223 - $ docker network ls - NETWORK ID NAME DRIVER - 3dd50db9706d node-0/host host - 09138343e80e node-0/bridge bridge - 8834dbd552e5 node-0/none null - 45782acfe427 node-1/host host - 8926accb25fd node-1/bridge bridge - 6382abccd23d node-1/none null - 5262bbfe5616 node-1/bridge2 bridge - -`swarm_network` was removed from every node, whereas `bridge2` was removed only +```bash +$ docker network rm swarm_network +42131321acab3233ba342443Ba4312 +$ docker network rm node-0/bridge2 +921817fefea521673217123abab223 +$ docker network ls +NETWORK ID NAME DRIVER +3dd50db9706d node-0/host host +09138343e80e node-0/bridge bridge +8834dbd552e5 node-0/none null +45782acfe427 node-1/host host +8926accb25fd node-1/bridge bridge +6382abccd23d node-1/none null +5262bbfe5616 node-1/bridge2 bridge +``` + +The `swarm_network` was removed from every node. The `bridge2` was removed only from `node-0`. ## Docker Swarm documentation index