beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Networking API and UX documentation

Browse source 
More doc updates will follow

Signed-off-by: Madhu Venugopal <madhu@docker.com>
This commit is contained in:
Madhu Venugopal 2015-09-28 18:57:03 -07:00
parent 22a9ba090e
commit dd28ded711
21 changed files with 994 additions and 901 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
docs/articles/networking.md
View file

@ -2,7 +2,7 @@
+++ +++
title = "Network configuration" title = "Network configuration"
description = "Docker networking" description = "Docker networking"
keywords = ["network, networking, bridge, docker, documentation"] keywords = ["network, networking, bridge, overlay, cluster, multihost, docker, documentation"]
[menu.main] [menu.main]
parent= "smn_administrate" parent= "smn_administrate"
+++ +++
@ -10,6 +10,9 @@ parent= "smn_administrate"
# Network configuration # Network configuration
> **Note:**
> This document is outdated and needs a major overhaul.
## Summary ## Summary
When Docker starts, it creates a virtual interface named `docker0` on When Docker starts, it creates a virtual interface named `docker0` on

7
docs/extend/index.md
View file

@ -15,6 +15,7 @@ weight = 6
Currently, you can extend Docker by adding a plugin. This section contains the following topics: Currently, you can extend Docker by adding a plugin. This section contains the following topics:
* [Understand Docker plugins](/extend/plugins) * [Understand Docker plugins](/extend/plugins.md)
* [Write a volume plugin](/extend/plugins_volume) * [Write a volume plugin](/extend/plugins_volume.md)
* [Docker plugin API](/extend/plugin_api) * [Write a network plugin](/extend/plugins_network.md)
* [Docker plugin API](/extend/plugin_api.md)

6
docs/extend/plugins.md
View file

@ -17,8 +17,10 @@ plugins.
## Types of plugins ## Types of plugins
Plugins extend Docker's functionality. They come in specific types. For Plugins extend Docker's functionality. They come in specific types. For
example, a [volume plugin](/extend/plugins_volume) might enable Docker example, a [volume plugin](/extend/plugins_volume.md) might enable Docker
volumes to persist across multiple Docker hosts. volumes to persist across multiple Docker hosts and a
[network plugin](/extend/plugins_network.md) might provide network plumbing
using a favorite networking technology, such as vxlan overlay, ipvlan, EVPN, etc.
Currently Docker supports volume and network driver plugins. In the future it Currently Docker supports volume and network driver plugins. In the future it
will support additional plugin types. will support additional plugin types.

13
experimental/plugins_network.md → docs/extend/plugins_network.md
View file

@ -1,4 +1,4 @@
# Experimental: Docker network driver plugins # Docker network driver plugins
Docker supports network driver plugins via Docker supports network driver plugins via
[LibNetwork](https://github.com/docker/libnetwork). Network driver plugins are [LibNetwork](https://github.com/docker/libnetwork). Network driver plugins are
@ -21,7 +21,9 @@ commands. For example,
Some network driver plugins are listed in [plugins.md](/docs/extend/plugins.md) Some network driver plugins are listed in [plugins.md](/docs/extend/plugins.md)
The network thus created is owned by the plugin, so subsequent commands The network thus created is owned by the plugin, so subsequent commands
referring to that network will also be run through the plugin. referring to that network will also be run through the plugin such as,
docker run --net=mynet busybox top
## Network driver plugin protocol ## Network driver plugin protocol
@ -36,10 +38,3 @@ Google Groups, or the IRC channel #docker-network.
- [#14083](https://github.com/docker/docker/issues/14083) Feedback on - [#14083](https://github.com/docker/docker/issues/14083) Feedback on
experimental networking features experimental networking features
Other pertinent issues:
- [#13977](https://github.com/docker/docker/issues/13977) UI for using networks
- [#14023](https://github.com/docker/docker/pull/14023) --default-network option
- [#14051](https://github.com/docker/docker/pull/14051) --publish-service option
- [#13441](https://github.com/docker/docker/pull/13441) (Deprecated) Networks API & UI

212
docs/reference/api/docker_remote_api_v1.21.md
View file

@ -2484,6 +2484,218 @@ Status Codes
- **409** - volume is in use and cannot be removed - **409** - volume is in use and cannot be removed
- **500** - server error - **500** - server error
## 2.5 Networks
### List networks
`GET /networks`
**Example request**:
GET /networks HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
```
[
{
"name": "bridge",
"id": "f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4",
"driver": "bridge"
},
{
"name": "none",
"id": "21e34df9b29c74ae45ba312f8e9f83c02433c9a877cfebebcf57be78f69b77c8",
"driver": "null"
},
{
"name": "host",
"id": "3f43a0873f00310a71cd6a71e2e60c113cf17d1812be2ec22fd519fbac68ec91",
"driver": "host"
}
]
```
Query Parameters:
- **filter** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters: `name=[network-names]` , `id=[network-ids]`
Status Codes:
- **200** - no error
- **500** - server error
### Inspect network
`GET /networks/<network-id>`
**Example request**:
GET /networks/f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4 HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
```
{
"name": "bridge",
"id": "f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4",
"driver": "bridge",
"containers": {
"931d29e96e63022a3691f55ca18b28600239acf53878451975f77054b05ba559": {
"endpoint": "aa79321e2899e6d72fcd46e6a4ad7f81ab9a19c3b06e384ef4ce51fea35827f9",
"mac_address": "02:42:ac:11:00:04",
"ipv4_address": "172.17.0.4/16"
},
"961249b4ae6c764b11eed923e8463c102689111fffd933627b2e7e359c7d0f7c": {
"endpoint": "4f62c5aea6b9a70512210be7db976bd4ec2cdba47125e4fe514d18c81b1624b1",
"mac_address": "02:42:ac:11:00:02",
"ipv4_address": "172.17.0.2/16"
},
"9f6e0fec4449f42a173ed85be96dc2253b6719edd850d8169bc31bdc45db675c": {
"endpoint": "352b512a5bccdfc77d16c2c04d04408e718f879a16f9ce3913a4733139e4f98d",
"mac_address": "02:42:ac:11:00:03",
"ipv4_address": "172.17.0.3/16"
}
}
}
```
Status Codes:
- **200** - no error
- **404** - network not found
### Create a network
`POST /networks/create`
Create a network
**Example request**:
POST /networks/create HTTP/1.1
Content-Type: application/json
```
{
"name":"isolated_nw",
"driver":"bridge"
}
```
**Example response**:
HTTP/1.1 201 Created
Content-Type: application/json
```
{
"id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
"warning": ""
}
```
Status Codes:
- **201** - no error
- **404** - driver not found
- **500** - server error
JSON Parameters:
- **name** - The new network's name. this is a mandatory field
- **driver** - Name of the network driver to use. Defaults to `bridge` driver
- **options** - Network specific options to be used by the drivers
- **check_duplicate** - Requests daemon to check for networks with same name
### Connect a container to a network
`POST /networks/(id)/connect`
Connects a container to a network
**Example request**:
POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1
Content-Type: application/json
```
{
"container":"3613f73ba0e4"
}
```
**Example response**:
HTTP/1.1 200 OK
Status Codes:
- **201** - no error
- **404** - network or container is not found
JSON Parameters:
- **container** - container-id/name to be connected to the network
### Disconnect a container from a network
`POST /networks/(id)/disconnect`
Disconnects a container from a network
**Example request**:
POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1
Content-Type: application/json
```
{
"container":"3613f73ba0e4"
}
```
**Example response**:
HTTP/1.1 200 OK
Status Codes:
- **201** - no error
- **404** - network or container not found
JSON Parameters:
- **container** - container-id/name to be disconnected from a network
### Remove a network
`DELETE /networks/(id)`
Instruct the driver to remove the network (`id`).
**Example request**:
DELETE /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1
**Example response**:
HTTP/1.1 204 No Content
Status Codes
- **204** - no error
- **404** - no such network
- **500** - server error
# 3. Going further # 3. Going further
## 3.1 Inside `docker run` ## 3.1 Inside `docker run`

30
docs/reference/commandline/network_connect.md Normal file
View file

@ -0,0 +1,30 @@
<!--[metadata]>
+++
title = "network connect"
description = "The network connect command description and usage"
keywords = ["network, connect"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# network connect
Usage: docker network connect [OPTIONS] NETWORK CONTAINER
Connects a container to a network
--help=false Print usage
Connects a running container to a network. This enables instant communication with other containers belonging to the same network.
```
$ docker network create -d overlay multi-host-network
$ docker run -d --name=container1 busybox top
$ docker network connect multi-host-network container1
```
the container will be connected to the network that is created and managed by the driver (multi-host overlay driver in the above example) or external network plugins.
Multiple containers can be connected to the same network and the containers in the same network will start to communicate with each other. If the driver/plugin supports multi-host connectivity, then the containers connected to the same multi-host network will be able to communicate seamlessly.

32
docs/reference/commandline/network_create.md Normal file
View file

@ -0,0 +1,32 @@
<!--[metadata]>
+++
title = "network create"
description = "The network create command description and usage"
keywords = ["network, create"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# network create
Usage: docker network create [OPTIONS] NETWORK-NAME
Creates a new network with a name specified by the user
-d, --driver= Driver to manage the Network
--help=false Print usage
Creates a new network that containers can connect to. If the driver supports multi-host networking, the created network will be made available across all the hosts in the cluster. Daemon will do its best to identify network name conflicts. But its the users responsibility to make sure network name is unique across the cluster. You create a network and then configure the container to use it, for example:
```
$ docker network create -d overlay multi-host-network
$ docker run -itd --net=multi-host-network busybox
```
the container will be connected to the network that is created and managed by the driver (multi-host overlay driver in the above example) or external network plugins.
Multiple containers can be connected to the same network and the containers in the same network will start to communicate with each other. If the driver/plugin supports multi-host connectivity, then the containers connected to the same multi-host network will be able to communicate seamlessly.
*Note*: UX needs enhancement to accept network options to be passed to the drivers

27
docs/reference/commandline/network_disconnect.md Normal file
View file

@ -0,0 +1,27 @@
<!--[metadata]>
+++
title = "network disconnect"
description = "The network disconnect command description and usage"
keywords = ["network, disconnect"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# network disconnect
Usage: docker network disconnect [OPTIONS] NETWORK CONTAINER
Disconnects a container from a network
--help=false Print usage
Disconnects a running container from a network.
```
$ docker network create -d overlay multi-host-network
$ docker run -d --net=multi-host-network --name=container1 busybox top
$ docker network disconnect multi-host-network container1
```
the container will be disconnected from the network.

49
docs/reference/commandline/network_inspect.md Normal file
View file

@ -0,0 +1,49 @@
<!--[metadata]>
+++
title = "network inspect"
description = "The network inspect command description and usage"
keywords = ["network, inspect"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# network inspect
Usage: docker network inspect [OPTIONS] NETWORK
Displays detailed information on a network
--help=false Print usage
Returns information about a network. By default, this command renders all results
in a JSON object.
Example output:
```
$ sudo docker run -itd --name=container1 busybox
f2870c98fd504370fb86e59f32cd0753b1ac9b69b7d80566ffc7192a82b3ed27
$ sudo docker run -itd --name=container2 busybox
bda12f8922785d1f160be70736f26c1e331ab8aaf8ed8d56728508f2e2fd4727
$ sudo docker network inspect bridge
{
"name": "bridge",
"id": "7fca4eb8c647e57e9d46c32714271e0c3f8bf8d17d346629e2820547b2d90039",
"driver": "bridge",
"containers": {
"bda12f8922785d1f160be70736f26c1e331ab8aaf8ed8d56728508f2e2fd4727": {
"endpoint": "e0ac95934f803d7e36384a2029b8d1eeb56cb88727aa2e8b7edfeebaa6dfd758",
"mac_address": "02:42:ac:11:00:03",
"ipv4_address": "172.17.0.3/16"
},
"f2870c98fd504370fb86e59f32cd0753b1ac9b69b7d80566ffc7192a82b3ed27": {
"endpoint": "31de280881d2a774345bbfb1594159ade4ae4024ebfb1320cb74a30225f6a8ae",
"mac_address": "02:42:ac:11:00:02",
"ipv4_address": "172.17.0.2/16"
}
}
}
```

32
docs/reference/commandline/network_ls.md Normal file
View file

@ -0,0 +1,32 @@
<!--[metadata]>
+++
title = "network ls"
description = "The network ls command description and usage"
keywords = ["network, list"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# docker network ls
Usage: docker network ls [OPTIONS]
Lists all the networks created by the user
--help=false Print usage
-l, --latest=false Show the latest network created
-n=-1 Show n last created networks
--no-trunc=false Do not truncate the output
-q, --quiet=false Only display numeric IDs
Lists all the networks Docker knows about. This include the networks that spans across multiple hosts in a cluster.
Example output:
```
$ sudo docker network ls
NETWORK ID NAME DRIVER
7fca4eb8c647 bridge bridge
9f904ee27bf5 none null
cf03ee007fb4 host host
```

23
docs/reference/commandline/network_rm.md Normal file
View file

@ -0,0 +1,23 @@
<!--[metadata]>
+++
title = "network rm"
description = "the network rm command description and usage"
keywords = ["network, rm"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# network rm
Usage: docker network rm [OPTIONS] NETWORK
Deletes a network
--help=false Print usage
Removes a network. You cannot remove a network that is in use by 1 or more containers.
```
$ docker network rm my-network
```

13
docs/reference/glossary.md
View file

@ -132,6 +132,12 @@ namespaces, cgroups, capabilities, and filesystem access controls. It allows
you to manage the lifecycle of the container performing additional operations you to manage the lifecycle of the container performing additional operations
after the container is created. after the container is created.
## libnetwork
libnetwork provides a native Go implementation for creating and managing container
network namespaces and other network resources. It manage the networking lifecycle
of the container performing additional operations after the container is created.
## link ## link
links provide an interface to connect Docker containers running on the same host links provide an interface to connect Docker containers running on the same host
@ -149,7 +155,12 @@ installs Docker on them, then configures the Docker client to talk to them.
*Also known as : docker-machine* *Also known as : docker-machine*
## overlay ## overlay network driver
Overlay network driver provides out of the box multi-host network connectivity
for docker containers in a cluster.
## overlay storage driver
OverlayFS is a [filesystem](#filesystem) service for Linux which implements a OverlayFS is a [filesystem](#filesystem) service for Linux which implements a
[union mount](http://en.wikipedia.org/wiki/Union_mount) for other file systems. [union mount](http://en.wikipedia.org/wiki/Union_mount) for other file systems.

44
docs/reference/run.md
View file

@ -245,11 +245,12 @@ of the containers.
## Network settings ## Network settings
--dns=[] : Set custom dns servers for the container --dns=[] : Set custom dns servers for the container
--net="bridge" : Set the Network mode for the container --net="bridge" : Connects a container to a network
'bridge': creates a new network stack for the container on the docker bridge 'bridge': creates a new network stack for the container on the docker bridge
'none': no networking for this container 'none': no networking for this container
'container:<name|id>': reuses another container network stack 'container:<name|id>': reuses another container network stack
'host': use the host network stack inside the container 'host': use the host network stack inside the container
'NETWORK': connects the container to user-created network using `docker network create` command
--add-host="" : Add a line to /etc/hosts (host:IP) --add-host="" : Add a line to /etc/hosts (host:IP)
--mac-address="" : Sets the container's Ethernet device's MAC address --mac-address="" : Sets the container's Ethernet device's MAC address
@ -269,12 +270,12 @@ By default, the MAC address is generated using the IP address allocated to the
container. You can set the container's MAC address explicitly by providing a container. You can set the container's MAC address explicitly by providing a
MAC address via the `--mac-address` parameter (format:`12:34:56:78:9a:bc`). MAC address via the `--mac-address` parameter (format:`12:34:56:78:9a:bc`).
Supported networking modes are: Supported networks :
<table> <table>
<thead> <thead>
<tr> <tr>
<th class="no-wrap">Mode</th> <th class="no-wrap">Network</th>
<th>Description</th> <th>Description</th>
</tr> </tr>
</thead> </thead>
@ -304,19 +305,25 @@ Supported networking modes are:
its *name* or *id*. its *name* or *id*.
</td> </td>
</tr> </tr>
<tr>
<td class="no-wrap"><strong>NETWORK</strong></td>
<td>
Connects the container to a user created network (using `docker network create` command)
</td>
</tr>
</tbody> </tbody>
</table> </table>
#### Mode: none #### Network: none
With the networking mode set to `none` a container will not have a With the network is `none` a container will not have
access to any external routes. The container will still have a access to any external routes. The container will still have a
`loopback` interface enabled in the container but it does not have any `loopback` interface enabled in the container but it does not have any
routes to external traffic. routes to external traffic.
#### Mode: bridge #### Network: bridge
With the networking mode set to `bridge` a container will use docker's With the network set to `bridge` a container will use docker's
default networking setup. A bridge is setup on the host, commonly named default networking setup. A bridge is setup on the host, commonly named
`docker0`, and a pair of `veth` interfaces will be created for the `docker0`, and a pair of `veth` interfaces will be created for the
container. One side of the `veth` pair will remain on the host attached container. One side of the `veth` pair will remain on the host attached
@ -325,9 +332,9 @@ container's namespaces in addition to the `loopback` interface. An IP
address will be allocated for containers on the bridge's network and address will be allocated for containers on the bridge's network and
traffic will be routed though this bridge to the container. traffic will be routed though this bridge to the container.
#### Mode: host #### Network: host
With the networking mode set to `host` a container will share the host's With the network set to `host` a container will share the host's
network stack and all interfaces from the host will be available to the network stack and all interfaces from the host will be available to the
container. The container's hostname will match the hostname on the host container. The container's hostname will match the hostname on the host
system. Note that `--add-host` `--hostname` `--dns` `--dns-search` system. Note that `--add-host` `--hostname` `--dns` `--dns-search`
@ -343,9 +350,9 @@ or a High Performance Web Server.
> **Note**: `--net="host"` gives the container full access to local system > **Note**: `--net="host"` gives the container full access to local system
> services such as D-bus and is therefore considered insecure. > services such as D-bus and is therefore considered insecure.
#### Mode: container #### Network: container
With the networking mode set to `container` a container will share the With the network set to `container` a container will share the
network stack of another container. The other container's name must be network stack of another container. The other container's name must be
provided in the format of `--net container:<name|id>`. Note that `--add-host` provided in the format of `--net container:<name|id>`. Note that `--add-host`
`--hostname` `--dns` `--dns-search` `--dns-opt` and `--mac-address` are `--hostname` `--dns` `--dns-search` `--dns-opt` and `--mac-address` are
@ -360,6 +367,21 @@ running the `redis-cli` command and connecting to the Redis server over the
$ # use the redis container's network stack to access localhost $ # use the redis container's network stack to access localhost
$ docker run --rm -it --net container:redis example/redis-cli -h 127.0.0.1 $ docker run --rm -it --net container:redis example/redis-cli -h 127.0.0.1
#### Network: User-Created NETWORK
In addition to all the above special networks, user can create a network using
their favorite network driver or external plugin. The driver used to create the
network takes care of all the network plumbing requirements for the container
connected to that network.
Example creating a network using the inbuilt overlay network driver and running
a container in the created network
```
$ docker network create -d overlay multi-host-network
$ docker run --net=multi-host-network -itd --name=container3 busybox
```
### Managing /etc/hosts ### Managing /etc/hosts
Your container will have lines in `/etc/hosts` which define the hostname of the Your container will have lines in `/etc/hosts` which define the hostname of the

4
docs/userguide/dockerlinks.md
View file

@ -347,7 +347,7 @@ allowing linked communication to continue.
# Next step # Next step
Now that you know how to link Docker containers together, the next step is Now that you know how to link Docker containers together, the next step is
learning how to manage data, volumes and mounts inside your containers. learning how to take complete control over docker networking.
Go to [Managing Data in Containers](/userguide/dockervolumes). Go to [Docker Networking](/userguide/dockernetworks.md).

510
docs/userguide/dockernetworks.md Normal file
View file

@ -0,0 +1,510 @@
<!--[metadata]>
+++
title = "Docker container networking"
description = "How do we connect docker containers within and across hosts ?"
keywords = ["Examples, Usage, network, docker, documentation, user guide, multihost, cluster"]
[menu.main]
parent = "smn_containers"
weight = 3
+++
<![end-metadata]-->
# Docker container networking
So far we've been introduced to some [basic Docker
concepts](/userguide/usingdocker/), seen how to work with [Docker
images](/userguide/dockerimages/) as well as learned about basic [networking
and links between containers](/userguide/dockerlinks/). In this section
we're going to discuss how you can take control over more advanced
container networking.
This section makes use of `docker network` commands and outputs to explain the
advanced networking functionality supported by Docker.
# Default Networks
By default, docker creates 3 networks using 3 different network drivers :
```
$ sudo docker network ls
NETWORK ID NAME DRIVER
7fca4eb8c647 bridge bridge
9f904ee27bf5 none null
cf03ee007fb4 host host
```
`docker network inspect` gives more information about a network
```
$ sudo docker network inspect bridge
{
"name": "bridge",
"id": "7fca4eb8c647e57e9d46c32714271e0c3f8bf8d17d346629e2820547b2d90039",
"driver": "bridge"
}
```
By default containers are launched on Bridge network
```
$ sudo docker run -itd --name=container1 busybox
f2870c98fd504370fb86e59f32cd0753b1ac9b69b7d80566ffc7192a82b3ed27
$ sudo docker run -itd --name=container2 busybox
bda12f8922785d1f160be70736f26c1e331ab8aaf8ed8d56728508f2e2fd4727
```
```
$ sudo docker network inspect bridge
{
"name": "bridge",
"id": "7fca4eb8c647e57e9d46c32714271e0c3f8bf8d17d346629e2820547b2d90039",
"driver": "bridge",
"containers": {
"bda12f8922785d1f160be70736f26c1e331ab8aaf8ed8d56728508f2e2fd4727": {
"endpoint": "e0ac95934f803d7e36384a2029b8d1eeb56cb88727aa2e8b7edfeebaa6dfd758",
"mac_address": "02:42:ac:11:00:03",
"ipv4_address": "172.17.0.3/16"
},
"f2870c98fd504370fb86e59f32cd0753b1ac9b69b7d80566ffc7192a82b3ed27": {
"endpoint": "31de280881d2a774345bbfb1594159ade4ae4024ebfb1320cb74a30225f6a8ae",
"mac_address": "02:42:ac:11:00:02",
"ipv4_address": "172.17.0.2/16"
}
}
}
```
`docker network inspect` command above shows all the connected containers and its network resources on a given network
Containers in a network should be able to communicate with each other using container names
```
$ sudo docker attach container1
/ # ifconfig
eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:02
inet addr:172.17.0.2 Bcast:0.0.0.0 Mask:255.255.0.0
inet6 addr: fe80::42:acff:fe11:2/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:17 errors:0 dropped:0 overruns:0 frame:0
TX packets:3 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:1382 (1.3 KiB) TX bytes:258 (258.0 B)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
/ # ping container2
PING container2 (172.17.0.3): 56 data bytes
64 bytes from 172.17.0.3: seq=0 ttl=64 time=0.125 ms
64 bytes from 172.17.0.3: seq=1 ttl=64 time=0.130 ms
64 bytes from 172.17.0.3: seq=2 ttl=64 time=0.172 ms
^C
--- container2 ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 0.125/0.142/0.172 ms
/ # cat /etc/hosts
172.17.0.2 f2870c98fd50
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
172.17.0.2 container1
172.17.0.2 container1.bridge
172.17.0.3 container2
172.17.0.3 container2.bridge
```
```
$ sudo docker attach container2
/ # ifconfig
eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03
inet addr:172.17.0.3 Bcast:0.0.0.0 Mask:255.255.0.0
inet6 addr: fe80::42:acff:fe11:3/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:8 errors:0 dropped:0 overruns:0 frame:0
TX packets:8 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:648 (648.0 B) TX bytes:648 (648.0 B)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
/ # ping container1
PING container1 (172.17.0.2): 56 data bytes
64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.277 ms
64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.179 ms
64 bytes from 172.17.0.2: seq=2 ttl=64 time=0.130 ms
64 bytes from 172.17.0.2: seq=3 ttl=64 time=0.113 ms
^C
--- container1 ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max = 0.113/0.174/0.277 ms
/ # cat /etc/hosts
172.17.0.3 bda12f892278
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
172.17.0.2 container1
172.17.0.2 container1.bridge
172.17.0.3 container2
172.17.0.3 container2.bridge
/ #
```
# User defined Networks
In addition to the inbuilt networks, user can create networks using inbuilt drivers
(such as bridge or overlay driver) or external plugins supplied by the community.
Networks by definition should provides complete isolation for the containers.
```
$ docker network create -d bridge isolated_nw
8b05faa32aeb43215f67678084a9c51afbdffe64cd91e3f5bb8267475f8bf1a7
$ docker network inspect isolated_nw
{
"name": "isolated_nw",
"id": "8b05faa32aeb43215f67678084a9c51afbdffe64cd91e3f5bb8267475f8bf1a7",
"driver": "bridge"
}
$ docker network ls
NETWORK ID NAME DRIVER
9f904ee27bf5 none null
cf03ee007fb4 host host
7fca4eb8c647 bridge bridge
8b05faa32aeb isolated_nw bridge
```
Container can be launched on a user-defined network using the --net=<NETWORK> option
in `docker run` command
```
$ docker run --net=isolated_nw -itd --name=container3 busybox
777344ef4943d34827a3504a802bf15db69327d7abe4af28a05084ca7406f843
$ docker network inspect isolated_nw
{
"name": "isolated_nw",
"id": "8b05faa32aeb43215f67678084a9c51afbdffe64cd91e3f5bb8267475f8bf1a7",
"driver": "bridge",
"containers": {
"777344ef4943d34827a3504a802bf15db69327d7abe4af28a05084ca7406f843": {
"endpoint": "c7f22f8da07fb8ecc687d08377cfcdb80b4dd8624c2a8208b1a4268985e38683",
"mac_address": "02:42:ac:14:00:01",
"ipv4_address": "172.20.0.1/16"
}
}
}
```
# Connecting to Multiple networks
Docker containers can dynamically connect to 1 or more networks with each network backed
by same or different network driver / plugin.
```
$ docker network connect isolated_nw container2
$ docker network inspect isolated_nw
{
"name": "isolated_nw",
"id": "8b05faa32aeb43215f67678084a9c51afbdffe64cd91e3f5bb8267475f8bf1a7",
"driver": "bridge",
"containers": {
"777344ef4943d34827a3504a802bf15db69327d7abe4af28a05084ca7406f843": {
"endpoint": "c7f22f8da07fb8ecc687d08377cfcdb80b4dd8624c2a8208b1a4268985e38683",
"mac_address": "02:42:ac:14:00:01",
"ipv4_address": "172.20.0.1/16"
},
"bda12f8922785d1f160be70736f26c1e331ab8aaf8ed8d56728508f2e2fd4727": {
"endpoint": "2ac11345af68b0750341beeda47cc4cce93bb818d8eb25e61638df7a4997cb1b",
"mac_address": "02:42:ac:14:00:02",
"ipv4_address": "172.20.0.2/16"
}
}
}
```
Lets check the network resources used by container2.
```
$ docker inspect --format='{{.NetworkSettings.Networks}}' container2
[bridge isolated_nw]
$ sudo docker attach container2
/ # ifconfig
eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03
inet addr:172.17.0.3 Bcast:0.0.0.0 Mask:255.255.0.0
inet6 addr: fe80::42:acff:fe11:3/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:21 errors:0 dropped:0 overruns:0 frame:0
TX packets:18 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:1586 (1.5 KiB) TX bytes:1460 (1.4 KiB)
eth1 Link encap:Ethernet HWaddr 02:42:AC:14:00:02
inet addr:172.20.0.2 Bcast:0.0.0.0 Mask:255.255.0.0
inet6 addr: fe80::42:acff:fe14:2/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:8 errors:0 dropped:0 overruns:0 frame:0
TX packets:8 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:648 (648.0 B) TX bytes:648 (648.0 B)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
```
In the example discussed in this section thus far, container3 and container2 are
connected to isolated_nw and can talk to each other.
But container3 and container1 are not in the same network and hence they cannot communicate.
```
$ docker attach container3
/ # ifconfig
eth0 Link encap:Ethernet HWaddr 02:42:AC:14:00:01
inet addr:172.20.0.1 Bcast:0.0.0.0 Mask:255.255.0.0
inet6 addr: fe80::42:acff:fe14:1/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:24 errors:0 dropped:0 overruns:0 frame:0
TX packets:8 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:1944 (1.8 KiB) TX bytes:648 (648.0 B)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
/ # ping container2.isolated_nw
PING container2.isolated_nw (172.20.0.2): 56 data bytes
64 bytes from 172.20.0.2: seq=0 ttl=64 time=0.217 ms
64 bytes from 172.20.0.2: seq=1 ttl=64 time=0.150 ms
64 bytes from 172.20.0.2: seq=2 ttl=64 time=0.188 ms
64 bytes from 172.20.0.2: seq=3 ttl=64 time=0.176 ms
^C
--- container2.isolated_nw ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max = 0.150/0.182/0.217 ms
/ # ping container2
PING container2 (172.20.0.2): 56 data bytes
64 bytes from 172.20.0.2: seq=0 ttl=64 time=0.120 ms
64 bytes from 172.20.0.2: seq=1 ttl=64 time=0.109 ms
^C
--- container2 ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 0.109/0.114/0.120 ms
/ # ping container1
ping: bad address 'container1'
/ # ping 172.17.0.2
PING 172.17.0.2 (172.17.0.2): 56 data bytes
^C
--- 172.17.0.2 ping statistics ---
4 packets transmitted, 0 packets received, 100% packet loss
/ # ping 172.17.0.3
PING 172.17.0.3 (172.17.0.3): 56 data bytes
^C
--- 172.17.0.3 ping statistics ---
4 packets transmitted, 0 packets received, 100% packet loss
```
While container2 is attached to both the networks (bridge and isolated_nw) and hence it
can talk to both container1 and container3
```
$ docker attach container2
/ # cat /etc/hosts
172.17.0.3 bda12f892278
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
172.17.0.2 container1
172.17.0.2 container1.bridge
172.17.0.3 container2
172.17.0.3 container2.bridge
172.20.0.1 container3
172.20.0.1 container3.isolated_nw
172.20.0.2 container2
172.20.0.2 container2.isolated_nw
/ # ping container3
PING container3 (172.20.0.1): 56 data bytes
64 bytes from 172.20.0.1: seq=0 ttl=64 time=0.138 ms
64 bytes from 172.20.0.1: seq=1 ttl=64 time=0.133 ms
64 bytes from 172.20.0.1: seq=2 ttl=64 time=0.133 ms
^C
--- container3 ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 0.133/0.134/0.138 ms
/ # ping container1
PING container1 (172.17.0.2): 56 data bytes
64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.121 ms
64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.250 ms
64 bytes from 172.17.0.2: seq=2 ttl=64 time=0.133 ms
^C
--- container1 ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 0.121/0.168/0.250 ms
/ #
```
Just like it is easy to connect a container to multiple networks, one can
disconnect a container from a network using the `docker network disconnect` command.
```
root@Ubuntu-vm ~$ docker network disconnect isolated_nw container2
$ docker inspect --format='{{.NetworkSettings.Networks}}' container2
[bridge]
root@Ubuntu-vm ~$ docker network inspect isolated_nw
{
"name": "isolated_nw",
"id": "8b05faa32aeb43215f67678084a9c51afbdffe64cd91e3f5bb8267475f8bf1a7",
"driver": "bridge",
"containers": {
"777344ef4943d34827a3504a802bf15db69327d7abe4af28a05084ca7406f843": {
"endpoint": "c7f22f8da07fb8ecc687d08377cfcdb80b4dd8624c2a8208b1a4268985e38683",
"mac_address": "02:42:ac:14:00:01",
"ipv4_address": "172.20.0.1/16"
}
}
}
```
Once a container is disconnected from a network, it cannot communicate with other containers
connected to that network. In this example, container2 cannot talk to container3 any more
in isolated_nw
```
$ sudo docker attach container2
/ # ifconfig
eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03
inet addr:172.17.0.3 Bcast:0.0.0.0 Mask:255.255.0.0
inet6 addr: fe80::42:acff:fe11:3/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:26 errors:0 dropped:0 overruns:0 frame:0
TX packets:23 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:1964 (1.9 KiB) TX bytes:1838 (1.7 KiB)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
/ # ping container3
PING container3 (172.20.0.1): 56 data bytes
^C
--- container3 ping statistics ---
2 packets transmitted, 0 packets received, 100% packet loss
But container2 still has full connectivity to the bridge network
/ # ping container1
PING container1 (172.17.0.2): 56 data bytes
64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.119 ms
64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.174 ms
^C
--- container1 ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 0.119/0.146/0.174 ms
/ #
```
When all the containers in a network stops or disconnected the network can be removed
```
$ docker network inspect isolated_nw
{
"name": "isolated_nw",
"id": "8b05faa32aeb43215f67678084a9c51afbdffe64cd91e3f5bb8267475f8bf1a7",
"driver": "bridge"
}
$ docker network rm isolated_nw
$ docker network ls
NETWORK ID NAME DRIVER
9f904ee27bf5 none null
cf03ee007fb4 host host
7fca4eb8c647 bridge bridge
```
# Native Multi-host networking
With the help of libnetwork and the inbuilt `VXLAN based overlay network driver` docker supports multi-host networking natively out of the box. Technical details are documented under https://github.com/docker/libnetwork/blob/master/docs/overlay.md.
Using the exact same above `docker network` UI, the user can exercise the power of multi-host networking.
In order to create a network using the inbuilt overlay driver,
```
$ docker network create -d overlay multi-host-network
```
Since `network` object is globally significant, this feature requires distributed states provided by `libkv`. Using `libkv`, the user can plug any of the supported Key-Value store (such as consul, etcd or zookeeper).
User can specify the Key-Value store of choice using the `--cluster-store` daemon flag, which takes configuration value of format `PROVIDER://URL`, where
`PROVIDER` is the name of the Key-Value store (such as consul, etcd or zookeeper) and
`URL` is the url to reach the Key-Value store.
Example : `docker daemon --cluster-store=consul://localhost:8500`
# Next step
Now that you know how to link Docker containers together, the next step is
learning how to manage data, volumes and mounts inside your containers.
Go to [Managing Data in Containers](/userguide/dockervolumes.md).

22
docs/userguide/index.md
View file

@ -42,7 +42,7 @@ Go to [Using Docker Hub](/docker-hub).
Docker offers a *container-based* virtualization platform to power your Docker offers a *container-based* virtualization platform to power your
applications. To learn how to Dockerize applications and run them: applications. To learn how to Dockerize applications and run them:
Go to [Dockerizing Applications](/userguide/dockerizing). Go to [Dockerizing Applications](/docs/userguide/dockerizing.md).
## Working with containers ## Working with containers
@ -52,7 +52,7 @@ Once you get a grip on running your applications in Docker containers
we're going to show you how to manage those containers. To find out we're going to show you how to manage those containers. To find out
about how to inspect, monitor and manage containers: about how to inspect, monitor and manage containers:
Go to [Working With Containers](/userguide/usingdocker). Go to [Working With Containers](/docs/userguide/usingdocker.md).
## Working with Docker images ## Working with Docker images
@ -61,7 +61,7 @@ Go to [Working With Containers](/userguide/usingdocker).
Once you've learnt how to use Docker it's time to take the next step and Once you've learnt how to use Docker it's time to take the next step and
learn how to build your own application images with Docker. learn how to build your own application images with Docker.
Go to [Working with Docker Images](/userguide/dockerimages). Go to [Working with Docker Images](/docs/userguide/dockerimages.md).
## Linking containers together ## Linking containers together
@ -69,14 +69,24 @@ Until now we've seen how to build individual applications inside Docker
containers. Now learn how to build whole application stacks with Docker containers. Now learn how to build whole application stacks with Docker
by linking together multiple Docker containers. by linking together multiple Docker containers.
Go to [Linking Containers Together](/userguide/dockerlinks). Go to [Linking Containers Together](/docs/userguide/dockerlinks.md).
## Docker container networking
Links provides a very easy and convenient way to connect the containers.
But, it is very opinionated and doesnt provide a lot of flexibility or
choice to the end-users. Now, lets learn about a flexible way to connect
containers together within a host or across multiple hosts in a cluster
using various networking technologies, with the help of extensible plugins.
Go to [Docker Networking](/docs/userguide/dockernetworks.md).
## Managing data in containers ## Managing data in containers
Now we know how to link Docker containers together the next step is Now we know how to link Docker containers together the next step is
learning how to manage data, volumes and mounts inside our containers. learning how to manage data, volumes and mounts inside our containers.
Go to [Managing Data in Containers](/userguide/dockervolumes). Go to [Managing Data in Containers](/docs/userguide/dockervolumes.md).
## Working with Docker Hub ## Working with Docker Hub
@ -84,7 +94,7 @@ Now we've learned a bit more about how to use Docker we're going to see
how to combine Docker with the services available on Docker Hub including how to combine Docker with the services available on Docker Hub including
Trusted Builds and private repositories. Trusted Builds and private repositories.
Go to [Working with Docker Hub](/userguide/dockerrepos). Go to [Working with Docker Hub](/docs/userguide/dockerrepos.md).
## Docker Compose ## Docker Compose

5
experimental/README.md
View file

@ -71,11 +71,6 @@ to build a Docker binary with the experimental features enabled:
## Current experimental features ## Current experimental features
* [Network plugins](plugins_network.md)
* [Networking and Services UI](networking.md)
* [Native multi-host networking](network_overlay.md)
* [Compose, Swarm and networking integration](compose_swarm_networking.md)
## How to comment on an experimental feature ## How to comment on an experimental feature
Each feature's documentation includes a list of proposal pull requests or PRs associated with the feature. If you want to comment on or suggest a change to a feature, please add it to the existing feature PR. Each feature's documentation includes a list of proposal pull requests or PRs associated with the feature. If you want to comment on or suggest a change to a feature, please add it to the existing feature PR.

238
experimental/compose_swarm_networking.md
View file

@ -1,238 +0,0 @@
# Experimental: Compose, Swarm and Multi-Host Networking
The [experimental build of Docker](https://github.com/docker/docker/tree/master/experimental) has an entirely new networking system, which enables secure communication between containers on multiple hosts. In combination with Docker Swarm and Docker Compose, you can now run multi-container apps on multi-host clusters with the same tooling and configuration format you use to develop them locally.
> Note: This functionality is in the experimental stage, and contains some hacks and workarounds which will be removed as it matures.
## Prerequisites
Before you start, you’ll need to install the experimental build of Docker, and the latest versions of Machine and Compose.
- To install the experimental Docker build on a Linux machine, follow the instructions [here](https://github.com/docker/docker/tree/master/experimental#install-docker-experimental).
- To install the experimental Docker build on a Mac, run these commands:
$ curl -L https://experimental.docker.com/builds/Darwin/x86_64/docker-latest > /usr/local/bin/docker
$ chmod +x /usr/local/bin/docker
- To install Machine, follow the instructions [here](http://docs.docker.com/machine/).
- To install Compose, follow the instructions [here](http://docs.docker.com/compose/install/).
You’ll also need a [Docker Hub](https://hub.docker.com/account/signup/) account and a [Digital Ocean](https://www.digitalocean.com/) account.
It works with the amazonec2 driver as well (by adapting the commands accordingly), except you'll need to manually open the ports 8500 (consul) and 7946 (serf) by editing the inbound rules of the corresponding security group.
## Set up a swarm with multi-host networking
Set the `DIGITALOCEAN_ACCESS_TOKEN` environment variable to a valid Digital Ocean API token, which you can generate in the [API panel](https://cloud.digitalocean.com/settings/applications).
export DIGITALOCEAN_ACCESS_TOKEN=abc12345
Start a consul server:
docker-machine --debug create \
-d digitalocean \
--engine-install-url="https://experimental.docker.com" \
consul
docker $(docker-machine config consul) run -d \
-p "8500:8500" \
-h "consul" \
progrium/consul -server -bootstrap
(In a real world setting you’d set up a distributed consul, but that’s beyond the scope of this guide!)
Create a Swarm token:
export SWARM_TOKEN=$(docker run swarm create)
Next, you create a Swarm master with Machine:
docker-machine --debug create \
-d digitalocean \
--digitalocean-image="ubuntu-14-04-x64" \
--engine-install-url="https://experimental.docker.com" \
--engine-opt="default-network=overlay:multihost" \
--engine-opt="kv-store=consul:$(docker-machine ip consul):8500" \
--engine-label="com.docker.network.driver.overlay.bind_interface=eth0" \
swarm-0
Usually Machine can create Swarms for you, but it doesn't yet fully support multi-host networks yet, so you'll have to start up the Swarm manually:
docker $(docker-machine config swarm-0) run -d \
--restart="always" \
--net="bridge" \
swarm:latest join \
--addr "$(docker-machine ip swarm-0):2376" \
"token://$SWARM_TOKEN"
docker $(docker-machine config swarm-0) run -d \
--restart="always" \
--net="bridge" \
-p "3376:3376" \
-v "/etc/docker:/etc/docker" \
swarm:latest manage \
--tlsverify \
--tlscacert="/etc/docker/ca.pem" \
--tlscert="/etc/docker/server.pem" \
--tlskey="/etc/docker/server-key.pem" \
-H "tcp://0.0.0.0:3376" \
--strategy spread \
"token://$SWARM_TOKEN"
Create a Swarm node:
docker-machine --debug create \
-d digitalocean \
--digitalocean-image="ubuntu-14-10-x64" \
--engine-install-url="https://experimental.docker.com" \
--engine-opt="default-network=overlay:multihost" \
--engine-opt="kv-store=consul:$(docker-machine ip consul):8500" \
--engine-label="com.docker.network.driver.overlay.bind_interface=eth0" \
--engine-label="com.docker.network.driver.overlay.neighbor_ip=$(docker-machine ip swarm-0)" \
swarm-1
docker $(docker-machine config swarm-1) run -d \
--restart="always" \
--net="bridge" \
swarm:latest join \
--addr "$(docker-machine ip swarm-1):2376" \
"token://$SWARM_TOKEN"
You can create more Swarm nodes if you want - it’s best to give them sensible names (swarm-2, swarm-3, etc).
Finally, point Docker at your swarm:
export DOCKER_HOST=tcp://"$(docker-machine ip swarm-0):3376"
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH="$HOME/.docker/machine/machines/swarm-0"
## Run containers and get them communicating
Now that you’ve got a swarm up and running, you can create containers on it just like a single Docker instance:
$ docker run busybox echo hello world
hello world
If you run `docker ps -a`, you can see what node that container was started on by looking at its name (here it’s swarm-3):
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
41f59749737b busybox "echo hello world" 15 seconds ago Exited (0) 13 seconds ago swarm-3/trusting_leakey
As you start more containers, they’ll be placed on different nodes across the cluster, thanks to Swarm’s default “spread” scheduling strategy.
Every container started on this swarm will use the “overlay:multihost” network by default, meaning they can all intercommunicate. Each container gets an IP address on that network, and an `/etc/hosts` file which will be updated on-the-fly with every other container’s IP address and name. That means that if you have a running container named ‘foo’, other containers can access it at the hostname ‘foo’.
Let’s verify that multi-host networking is functioning. Start a long-running container:
$ docker run -d --name long-running busybox top
<container id>
If you start a new container and inspect its /etc/hosts file, you’ll see the long-running container in there:
$ docker run busybox cat /etc/hosts
...
172.21.0.6 long-running
Verify that connectivity works between containers:
$ docker run busybox ping long-running
PING long-running (172.21.0.6): 56 data bytes
64 bytes from 172.21.0.6: seq=0 ttl=64 time=7.975 ms
64 bytes from 172.21.0.6: seq=1 ttl=64 time=1.378 ms
64 bytes from 172.21.0.6: seq=2 ttl=64 time=1.348 ms
^C
--- long-running ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 1.140/2.099/7.975 ms
## Run a Compose application
Here’s an example of a simple Python + Redis app using multi-host networking on a swarm.
Create a directory for the app:
$ mkdir composetest
$ cd composetest
Inside this directory, create 2 files.
First, create `app.py` - a simple web app that uses the Flask framework and increments a value in Redis:
from flask import Flask
from redis import Redis
import os
app = Flask(__name__)
redis = Redis(host='composetest_redis_1', port=6379)
@app.route('/')
def hello():
redis.incr('hits')
return 'Hello World! I have been seen %s times.' % redis.get('hits')
if __name__ == "__main__":
app.run(host="0.0.0.0", debug=True)
Note that we’re connecting to a host called `composetest_redis_1` - this is the name of the Redis container that Compose will start.
Second, create a Dockerfile for the app container:
FROM python:2.7
RUN pip install flask redis
ADD . /code
WORKDIR /code
CMD ["python", "app.py"]
Build the Docker image and push it to the Hub (you’ll need a Hub account). Replace `<username>` with your Docker Hub username:
$ docker build -t <username>/counter .
$ docker push <username>/counter
Next, create a `docker-compose.yml`, which defines the configuration for the web and redis containers. Once again, replace `<username>` with your Hub username:
web:
image: <username>/counter
ports:
- "80:5000"
redis:
image: redis
Now start the app:
$ docker-compose up -d
Pulling web (username/counter:latest)...
swarm-0: Pulling username/counter:latest... : downloaded
swarm-2: Pulling username/counter:latest... : downloaded
swarm-1: Pulling username/counter:latest... : downloaded
swarm-3: Pulling username/counter:latest... : downloaded
swarm-4: Pulling username/counter:latest... : downloaded
Creating composetest_web_1...
Pulling redis (redis:latest)...
swarm-2: Pulling redis:latest... : downloaded
swarm-1: Pulling redis:latest... : downloaded
swarm-3: Pulling redis:latest... : downloaded
swarm-4: Pulling redis:latest... : downloaded
swarm-0: Pulling redis:latest... : downloaded
Creating composetest_redis_1...
Swarm has created containers for both web and redis, and placed them on different nodes, which you can check with `docker ps`:
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
92faad2135c9 redis "/entrypoint.sh redi 43 seconds ago Up 42 seconds swarm-2/composetest_redis_1
adb809e5cdac username/counter "/bin/sh -c 'python 55 seconds ago Up 54 seconds 45.67.8.9:80->5000/tcp swarm-1/composetest_web_1
You can also see that the web container has exposed port 80 on its swarm node. If you curl that IP, you’ll get a response from the container:
$ curl http://45.67.8.9
Hello World! I have been seen 1 times.
If you hit it repeatedly, the counter will increment, demonstrating that the web and redis container are communicating:
$ curl http://45.67.8.9
Hello World! I have been seen 2 times.
$ curl http://45.67.8.9
Hello World! I have been seen 3 times.
$ curl http://45.67.8.9
Hello World! I have been seen 4 times.

14
experimental/network_overlay.md
View file

@ -1,14 +0,0 @@
# Native Multi-host networking
There is a lot to talk about the native multi-host networking and the `overlay` driver that makes it happen. The technical details are documented under https://github.com/docker/libnetwork/blob/master/docs/overlay.md.
Using the above experimental UI `docker network`, `docker service` and `--publish-service`, the user can exercise the power of multi-host networking.
Since `network` and `service` objects are globally significant, this feature requires distributed states provided by the `libkv` project.
Using `libkv`, the user can plug any of the supported Key-Value store (such as consul, etcd or zookeeper).
User can specify the Key-Value store of choice using the `--cluster-store` daemon flag, which takes configuration value of format `PROVIDER:URL`, where
`PROVIDER` is the name of the Key-Value store (such as consul, etcd or zookeeper) and
`URL` is the url to reach the Key-Value store.
Example : `docker daemon --cluster-store=consul://localhost:8500`
Send us feedback and comments on [#14083](https://github.com/docker/docker/issues/14083)
or on the usual Google Groups (docker-user, docker-dev) and IRC channels.

120
experimental/networking.md
View file

@ -1,120 +0,0 @@
# Experimental: Networking and Services
In this feature:
- `network` and `service` become first class objects in the Docker UI
- one can now create networks, publish services on that network and attach containers to the services
- Native multi-host networking
- `network` and `service` objects are globally significant and provides multi-host container connectivity natively
- Inbuilt simple Service Discovery
- With multi-host networking and top-level `service` object, Docker now provides out of the box simple Service Discovery for containers running in a network
- Batteries included but removable
- Docker provides inbuilt native multi-host networking by default & can be swapped by any remote driver provided by external plugins.
This is an experimental feature. For information on installing and using experimental features, see [the experimental feature overview](README.md).
## Using Networks
Usage: docker network [OPTIONS] COMMAND [OPTIONS] [arg...]
Commands:
create Create a network
rm Remove a network
ls List all networks
info Display information of a network
Run 'docker network COMMAND --help' for more information on a command.
--help=false Print usage
The `docker network` command is used to manage Networks.
To create a network, `docker network create foo`. You can also specify a driver
if you have loaded a networking plugin e.g `docker network create -d <plugin_name> foo`
$ docker network create foo
aae601f43744bc1f57c515a16c8c7c4989a2cad577978a32e6910b799a6bccf6
$ docker network create -d overlay bar
d9989793e2f5fe400a58ef77f706d03f668219688ee989ea68ea78b990fa2406
`docker network ls` is used to display the currently configured networks
$ docker network ls
NETWORK ID NAME TYPE
d367e613ff7f none null
bd61375b6993 host host
cc455abccfeb bridge bridge
aae601f43744 foo bridge
d9989793e2f5 bar overlay
To get detailed information on a network, you can use the `docker network info`
command.
$ docker network info foo
Network Id: aae601f43744bc1f57c515a16c8c7c4989a2cad577978a32e6910b799a6bccf6
Name: foo
Type: null
If you no longer have need of a network, you can delete it with `docker network rm`
$ docker network rm bar
bar
$ docker network ls
NETWORK ID NAME TYPE
aae601f43744 foo bridge
d367e613ff7f none null
bd61375b6993 host host
cc455abccfeb bridge bridge
## User-Defined default network
Docker daemon supports a configuration flag `--default-network` which takes configuration value of format `DRIVER:NETWORK`, where,
`DRIVER` represents the in-built drivers such as bridge, overlay, container, host and none. or Remote drivers via Network Plugins.
`NETWORK` is the name of the network created using the `docker network create` command
When a container is created and if the network mode (`--net`) is not specified, then this default network will be used to connect
the container. If `--default-network` is not specified, the default network will be the `bridge` driver.
Example : `docker daemon --default-network=overlay:multihost`
## Using Services
Usage: docker service COMMAND [OPTIONS] [arg...]
Commands:
publish Publish a service
unpublish Remove a service
attach Attach a backend (container) to the service
detach Detach the backend from the service
ls Lists all services
info Display information about a service
Run 'docker service COMMAND --help' for more information on a command.
--help=false Print usage
Assuming we want to publish a service from container `a0ebc12d3e48` on network `foo` as `my-service` we would use the following command:
$ docker service publish my-service.foo
ec56fd74717d00f968c26675c9a77707e49ae64b8e54832ebf78888eb116e428
$ docker service attach a0ebc12d3e48 my-service.foo
This would make the container `a0ebc12d3e48` accessible as `my-service` on network `foo`. Any other container in network `foo` can use DNS to resolve the address of `my-service`
This can also be achieved by using the `--publish-service` flag for `docker run`:
docker run -itd --publish-service db.foo postgres
`db.foo` in this instance means "place the container on network `foo`, and allow other hosts on `foo` to discover it under the name `db`"
We can see the current services using the `docker service ls` command
$ docker service ls
SERVICE ID NAME NETWORK PROVIDER
ec56fd74717d my-service foo a0ebc12d3e48
To remove the a service:
$ docker service detach a0ebc12d3e48 my-service.foo
$ docker service unpublish my-service.foo
Send us feedback and comments on [#14083](https://github.com/docker/docker/issues/14083)
or on the usual Google Groups (docker-user, docker-dev) and IRC channels.

489
experimental/networking_api.md
View file

@ -1,489 +0,0 @@
# Networking API
### List networks
`GET /networks`
List networks
**Example request**:
GET /networks HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"name": "none",
"id": "8e4e55c6863ef4241c548c1c6fc77289045e9e5d5b5e4875401a675326981898",
"type": "null",
"endpoints": []
},
{
"name": "host",
"id": "062b6d9ea7913fde549e2d186ff0402770658f8c4e769958e1b943ff4e675011",
"type": "host",
"endpoints": []
},
{
"name": "bridge",
"id": "a87dd9a9d58f030962df1c15fb3fa142fbd9261339de458bc89be1895cef2c70",
"type": "bridge",
"endpoints": []
}
]
Query Parameters:
- **name** – Filter results with the given name
- **partial-id** – Filter results using the partial network ID
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Create a Network
`POST /networks`
**Example request**
POST /networks HTTP/1.1
Content-Type: application/json
{
"name": "foo",
"network_type": "",
"options": {}
}
**Example Response**
HTTP/1.1 200 OK
"32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653",
Status Codes:
- **200** – no error
- **400** – bad request
- **500** – server error
### Get a network
`GET /networks/<network_id>`
Get a network
**Example request**:
GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653 HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "foo",
"id": "32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653",
"type": "bridge",
"endpoints": []
}
Status Codes:
- **200** – no error
- **404** – not found
- **500** – server error
### List a networks endpoints
`GET /networks/<network_id>/endpoints`
**Example request**
GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints HTTP/1.1
**Example Response**
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": "7e0c116b882ee489a8a5345a2638c0129099aa47f4ba114edde34e75c1e4ae0d",
"name": "/lonely_pasteur",
"network": "foo"
}
]
Query Parameters:
- **name** – Filter results with the given name
- **partial-id** – Filter results using the partial network ID
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Create an endpoint on a network
`POST /networks/<network_id>/endpoints`
**Example request**
POST /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints HTTP/1.1
Content-Type: application/json
{
"name": "baz",
"exposed_ports": [
{
"proto": 6,
"port": 8080
}
],
"port_mapping": null
}
**Example Response**
HTTP/1.1 200 OK
Content-Type: application/json
"b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a"
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Get an endpoint
`GET /networks/<network_id>/endpoints/<endpoint_id>`
**Example request**
GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a HTTP/1.1
**Example Response**
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a",
"name": "baz",
"network": "foo"
}
Status Codes:
- **200** – no error
- **404** - not found
- **500** – server error
### Join an endpoint to a container
`POST /networks/<network_id>/endpoints/<endpoint_id>/containers`
**Example request**
POST /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653//endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a/containers HTTP/1.1
Content-Type: application/json
{
"container_id": "e76f406417031bd24c17aeb9bb2f5968b628b9fb6067da264b234544754bf857",
"host_name": null,
"domain_name": null,
"hosts_path": null,
"resolv_conf_path": null,
"dns": null,
"extra_hosts": null,
"parent_updates": null,
"use_default_sandbox": true
}
**Example response**
HTTP/1.1 200 OK
Content-Type: application/json
"/var/run/docker/netns/e76f40641703"
Status Codes:
- **200** – no error
- **400** – bad parameter
- **404** - not found
- **500** – server error
### Detach an endpoint from a container
`DELETE /networks/<network_id>/endpoints/<endpoint_id>/containers/<container_id>`
**Example request**
DELETE /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a/containers/e76f406417031bd24c17aeb9bb2f5968b628b9fb6067da264b234544754bf857 HTTP/1.1
Content-Type: application/json
**Example response**
HTTP/1.1 200 OK
Status Codes:
- **200** – no error
- **400** – bad parameter
- **404** - not found
- **500** – server error
### Delete an endpoint
`DELETE /networks/<network_id>/endpoints/<endpoint_id>`
**Example request**
DELETE /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a HTTP/1.1
**Example Response**
HTTP/1.1 200 OK
Status Codes:
- **200** – no error
- **404** - not found
- **500** – server error
### Delete a network
`DELETE /networks/<network_id>`
Delete a network
**Example request**:
DELETE /networks/0984d158bd8ae108e4d6bc8fcabedf51da9a174b32cc777026d4a29045654951 HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Status Codes:
- **200** – no error
- **404** – not found
- **500** – server error
# Services API
### Publish a Service
`POST /services`
Publish a service
**Example Request**
POST /services HTTP/1.1
Content-Type: application/json
{
"name": "bar",
"network_name": "foo",
"exposed_ports": null,
"port_mapping": null
}
**Example Response**
HTTP/1.1 200 OK
Content-Type: application/json
"0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff"
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Get a Service
`GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff`
Get a service
**Example Request**:
GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff HTTP/1.1
**Example Response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "bar",
"id": "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff",
"network": "foo"
}
Status Codes:
- **200** – no error
- **400** – bad parameter
- **404** - not found
- **500** – server error
### Attach a backend to a service
`POST /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend`
Attach a backend to a service
**Example Request**:
POST /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend HTTP/1.1
Content-Type: application/json
{
"container_id": "98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547",
"host_name": "",
"domain_name": "",
"hosts_path": "",
"resolv_conf_path": "",
"dns": null,
"extra_hosts": null,
"parent_updates": null,
"use_default_sandbox": false
}
**Example Response**:
HTTP/1.1 200 OK
Content-Type: application/json
"/var/run/docker/netns/98c5241f9475"
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Get Backends for a Service
Get all backends for a given service
**Example Request**
GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend HTTP/1.1
**Example Response**
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": "98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547"
}
]
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
### List Services
`GET /services`
List services
**Example request**:
GET /services HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"name": "/stupefied_stallman",
"id": "c826b26bf736fb4a77db33f83562e59f9a770724e259ab9c3d50d948f8233ae4",
"network": "bridge"
},
{
"name": "bar",
"id": "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff",
"network": "foo"
}
]
Query Parameters:
- **name** – Filter results with the given name
- **partial-id** – Filter results using the partial network ID
- **network** - Filter results by the given network
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Detach a Backend from a Service
`DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend/98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547`
Detach a backend from a service
**Example Request**
DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend/98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547 HTTP/1.1
**Example Response**
HTTP/1.1 200 OK
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Un-Publish a Service
`DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff`
Unpublish a service
**Example Request**
DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff HTTP/1.1
**Example Response**
HTTP/1.1 200 OK
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error