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 4a46d94ec4..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 may 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 +```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 +``` -`swarm_network` was removed from every node, `bridge2` was removed only +The `swarm_network` was removed from every node. The `bridge2` was removed only from `node-0`. ## Docker Swarm documentation index