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

Update several aspects of the networking intro (#2882)

This commit is contained in:
Misty Stanley-Jones 2017-04-18 19:29:43 -05:00 committed by GitHub
parent 6f0f24f1bf
commit e7d06e2d65
1 changed files with 184 additions and 217 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

401
engine/userguide/networking/index.md
View File

@ -7,11 +7,10 @@ redirect_from:
title: Docker container networking title: Docker container networking
--- ---
This section provides an overview of the default networking behavior that Docker This section provides an overview of Docker's default networking behavior,
Engine delivers natively. It describes the type of networks created by default including the type of networks created by default and how to create your own
and how to create your own, user-defined networks. It also describes the user-defined networks. It also describes the resources required to create
resources required to create networks on a single host or across a cluster of networks on a single host or across a cluster of hosts.
hosts.
## Default Networks ## Default Networks
@ -27,9 +26,9 @@ NETWORK ID NAME DRIVER
cf03ee007fb4 host host cf03ee007fb4 host host
``` ```
Historically, these three networks are part of Docker's implementation. When These three networks are built into Docker. When
you run a container you can use the `--network` flag to specify which network you you run a container, you can use the `--network` flag to specify which networks
want to run a container on. These three networks are still available to you. your container should connect to.
The `bridge` network represents the `docker0` network present in all Docker The `bridge` network represents the `docker0` network present in all Docker
installations. Unless you specify otherwise with the `docker run installations. Unless you specify otherwise with the `docker run
@ -37,7 +36,7 @@ installations. Unless you specify otherwise with the `docker run
by default. You can see this bridge as part of a host's network stack by using by default. You can see this bridge as part of a host's network stack by using
the `ifconfig` command on the host. the `ifconfig` command on the host.
``` ```bash
$ ifconfig $ ifconfig
docker0 Link encap:Ethernet HWaddr 02:42:47:bc:3a:eb docker0 Link encap:Ethernet HWaddr 02:42:47:bc:3a:eb
@ -50,9 +49,11 @@ docker0 Link encap:Ethernet HWaddr 02:42:47:bc:3a:eb
RX bytes:1100 (1.1 KB) TX bytes:648 (648.0 B) RX bytes:1100 (1.1 KB) TX bytes:648 (648.0 B)
``` ```
The `none` network adds a container to a container-specific network stack. That container lacks a network interface. Attaching to such a container and looking at its stack you see this: The `none` network adds a container to a container-specific network stack. That
container lacks a network interface. Attaching to such a container and looking
at its stack you see this:
``` ```bash
$ docker attach nonenetcontainer $ docker attach nonenetcontainer
root@0cb243cd1293:/# cat /etc/hosts root@0cb243cd1293:/# cat /etc/hosts
@ -74,24 +75,29 @@ lo Link encap:Local Loopback
root@0cb243cd1293:/# root@0cb243cd1293:/#
``` ```
>**Note**: You can detach from the container and leave it running with `CTRL-p CTRL-q`. >**Note**: You can detach from the container and leave it running with `CTRL-p CTRL-q`.
The `host` network adds a container on the hosts network stack. You'll find the The `host` network adds a container on the host's network stack. As far as the
network configuration inside the container is identical to the host. network is concerned, there is no isolation between the host machine and the
container. For instance, if you run a container that runs a web server on port
80 using host networking, the web server is available on port 80 of the host
machine.
With the exception of the `bridge` network, you really don't need to The `none` and `host` networks are not directly configurable in Docker.
interact with these default networks. While you can list and inspect them, you However, you can configure the default `bridge` network, as well as your own
cannot remove them. They are required by your Docker installation. However, you user-defined bridge networks.
can add your own user-defined networks and these you can remove when you no
longer need them. Before you learn more about creating your own networks, it is
worth looking at the default `bridge` network a bit.
### The default bridge network in detail ### The default bridge network
The default `bridge` network is present on all Docker hosts. The `docker network inspect`
command returns information about a network:
``` The default `bridge` network is present on all Docker hosts. If you do not
specify a different network, new containers are automatically connected to the
default `bridge` network.
The `docker network inspect` command returns information about a network:
```none
$ docker network inspect bridge $ docker network inspect bridge
[ [
@ -122,10 +128,11 @@ $ docker network inspect bridge
} }
] ]
``` ```
The Engine automatically creates a `Subnet` and `Gateway` to the network.
The `docker run` command automatically adds new containers to this network.
``` Run the following two commands to start two `busybox` containers, which are each
connected to the default `bridge` network.
```bash
$ docker run -itd --name=container1 busybox $ docker run -itd --name=container1 busybox
3386a527aa08b37ea9232cbcace2d2458d49f44bb05a6b775fba7ddd40d8f92c 3386a527aa08b37ea9232cbcace2d2458d49f44bb05a6b775fba7ddd40d8f92c
@ -135,9 +142,12 @@ $ docker run -itd --name=container2 busybox
94447ca479852d29aeddca75c28f7104df3c3196d7b6d83061879e339946805c 94447ca479852d29aeddca75c28f7104df3c3196d7b6d83061879e339946805c
``` ```
Inspecting the `bridge` network again after starting two containers shows both newly launched containers in the network. Their ids show up in the "Containers" section of `docker network inspect`: Inspect the `bridge` network again after starting two containers. Both of the
`busybox` containers are connected to the network. Make note of their IP
addresses, which will be different on your host machine than in the example
below.
``` ```none
$ docker network inspect bridge $ docker network inspect bridge
{[ {[
@ -182,14 +192,22 @@ $ docker network inspect bridge
] ]
``` ```
The `docker network inspect` command above shows all the connected containers and their network resources on a given network. Containers in this default network are able to communicate with each other using IP addresses. Docker does not support automatic service discovery on the default bridge network. If you want to communicate with container names in this default bridge network, you must connect the containers via the legacy `docker run --link` option. Containers connected to the default `bridge` network can communicate with each
other by IP address. Docker does not support automatic service discovery on the
default bridge network. If you want containers to be able to resolve IP addresses
by container name, you should use user-defined networks instead. You can link
two containers together using the legacy `docker run --link` option, but this
is not recommended in most cases.
You can `attach` to a running `container` and investigate its configuration: You can `attach` to a running `container` to see how the network looks from
inside the container. You are connected as `root`, so your command prompt is
a `#` character.
``` ```none
$ docker attach container1 $ docker attach container1
root@0cb243cd1293:/# ifconfig root@0cb243cd1293:/# ifconfig
eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:02 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 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 inet6 addr: fe80::42:acff:fe11:2/64 Scope:Link
@ -209,10 +227,10 @@ lo Link encap:Local Loopback
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
``` ```
Then use `ping` to send three ICMP requests and test the connectivity of the From inside the container, use the `ping` command to test the network connection
containers on this `bridge` network. to the IP address of the other container.
``` ```none
root@0cb243cd1293:/# ping -w3 172.17.0.3 root@0cb243cd1293:/# ping -w3 172.17.0.3
PING 172.17.0.3 (172.17.0.3): 56 data bytes PING 172.17.0.3 (172.17.0.3): 56 data bytes
@ -225,7 +243,8 @@ PING 172.17.0.3 (172.17.0.3): 56 data bytes
round-trip min/avg/max = 0.074/0.083/0.096 ms round-trip min/avg/max = 0.074/0.083/0.096 ms
``` ```
Finally, use the `cat` command to check the `container1` network configuration: Use the `cat` command to view the `/etc/hosts` file on the container. This shows
the hostnames and IP addresses the container recognizes.
``` ```
root@0cb243cd1293:/# cat /etc/hosts root@0cb243cd1293:/# cat /etc/hosts
@ -238,78 +257,44 @@ ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes ff02::1 ip6-allnodes
ff02::2 ip6-allrouters ff02::2 ip6-allrouters
``` ```
To detach from a `container1` and leave it running use `CTRL-p CTRL-q`. Then, attach to `container2` and repeat these three commands.
``` To detach from the `container1` container and leave it running, use the keyboard
$ docker attach container2 sequence **CTRL-p CTRL-q**. If you wish, attach to `container2` and repeat the
commands above.
root@0cb243cd1293:/# ifconfig The default `docker0` bridge network supports the use of port mapping and
eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03 `docker run --link` to allow communications among containers in the `docker0`
inet addr:172.17.0.3 Bcast:0.0.0.0 Mask:255.255.0.0 network. This approach is not recommended. Where possible, you should use
inet6 addr: fe80::42:acff:fe11:3/64 Scope:Link [user-defined bridge networks](#user-defined-networks) instead.
UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1
RX packets:15 errors:0 dropped:0 overruns:0 frame:0
TX packets:13 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:1166 (1.1 KiB) TX bytes:1026 (1.0 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)
root@0cb243cd1293:/# ping -w3 172.17.0.2
PING 172.17.0.2 (172.17.0.2): 56 data bytes
64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.067 ms
64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.075 ms
64 bytes from 172.17.0.2: seq=2 ttl=64 time=0.072 ms
--- 172.17.0.2 ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 0.067/0.071/0.075 ms
/ # cat /etc/hosts
172.17.0.3 94447ca47985
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
```
The default `docker0` bridge network supports the use of port mapping and `docker run --link` to allow communications between containers in the `docker0` network. These techniques are cumbersome to set up and prone to error. While they are still available to you as techniques, it is better to avoid them and define your own bridge networks instead.
## User-defined networks ## User-defined networks
You can create your own user-defined networks that better isolate containers. It is recommended to use user-defined bridge networks to control which
Docker provides some default **network drivers** for creating these networks. containers can communicate with each other, and also to enable automatic DNS
You can create a new **bridge network**, **overlay network** or **MACVLAN resolution of container names to IP addresses. Docker provides default **network
network**. You can also create a **network plugin** or **remote network** drivers** for creating these networks. You can create a new **bridge network**,
written to your own specifications. **overlay network** or **MACVLAN network**. You can also create a **network
plugin** or **remote network** for complete customization and control.
You can create multiple networks. You can add containers to more than one You can create as many networks as you need, and you can connect a container to
network. Containers can only communicate within networks but not across zero or more of these networks at any given time. In addition, you can connect
networks. A container attached to two networks can communicate with member and disconnect running containers from networks without restarting the
containers in either network. When a container is connected to multiple container. When a container is connected to multiple networks, its external
networks, its external connectivity is provided via the first non-internal connectivity is provided via the first non-internal network, in lexical order.
network, in lexical order.
The next few sections describe each of Docker's built-in network drivers in The next few sections describe each of Docker's built-in network drivers in
greater detail. greater detail.
### A bridge network ### Bridge networks
The easiest user-defined network to create is a `bridge` network. This network A `bridge` network is the most common type of network used in Docker. Bridge
is similar to the historical, default `docker0` network. There are some added networks are similar to the default `bridge` network, but add some new features
features and some old features that aren't available. and remove some old abilities. The following examples create some bridge
networks and perform some experiments on containers on these networks.
``` ```none
$ docker network create --driver bridge isolated_nw $ docker network create --driver bridge isolated_nw
1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b 1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b
$ docker network inspect isolated_nw $ docker network inspect isolated_nw
@ -345,9 +330,10 @@ c5ee82f76de3 isolated_nw bridge
``` ```
After you create the network, you can launch containers on it using the `docker run --network=<NETWORK>` option. After you create the network, you can launch containers on it using the
`docker run --network=<NETWORK>` option.
``` ```none
$ docker run --network=isolated_nw -itd --name=container3 busybox $ docker run --network=isolated_nw -itd --name=container3 busybox
8c1a0a5be480921d669a073393ade66a3fc49933f08bcc5515b37b8144f6d47c 8c1a0a5be480921d669a073393ade66a3fc49933f08bcc5515b37b8144f6d47c
@ -387,9 +373,9 @@ networks.
![An isolated network](images/bridge_network.png) ![An isolated network](images/bridge_network.png)
Within a user-defined bridge network, linking is not supported. You can Within a user-defined bridge network, linking is not supported. You can
expose and publish container ports on containers in this network. This is useful [expose and publish container ports](#exposing-and-publishing-ports) on
if you want to make a portion of the `bridge` network available to an outside containers in this network. This is useful if you want to make a portion of the
network. `bridge` network available to an outside network.
![Bridge network](images/network_access.png) ![Bridge network](images/network_access.png)
@ -422,7 +408,7 @@ $ docker network create --subnet 172.30.0.0/16 \
The `docker_gwbridge` network is always present when you use `overlay` networks. The `docker_gwbridge` network is always present when you use `overlay` networks.
### An overlay network with Docker Engine swarm mode ### Overlay networks in swarm mode
You can create an overlay network on a manager node running in swarm mode You can create an overlay network on a manager node running in swarm mode
without an external key-value store. The swarm makes the overlay network without an external key-value store. The swarm makes the overlay network
@ -433,10 +419,10 @@ extends the overlay network to nodes that run service tasks.
To learn more about running Docker Engine in swarm mode, refer to the To learn more about running Docker Engine in swarm mode, refer to the
[Swarm mode overview](../../swarm/index.md). [Swarm mode overview](../../swarm/index.md).
The example below shows how to create a network and use it for a service from a manager node in the swarm: The example below shows how to create a network and use it for a service from a
manager node in the swarm:
```bash ```bash.
# Create an overlay network `my-multi-host-network`.
$ docker network create \ $ docker network create \
--driver overlay \ --driver overlay \
--subnet 10.0.9.0/24 \ --subnet 10.0.9.0/24 \
@ -444,144 +430,125 @@ $ docker network create \
400g6bwzd68jizzdx5pgyoe95 400g6bwzd68jizzdx5pgyoe95
# Create an nginx service and extend the my-multi-host-network to nodes where
# the service's tasks run.
$ docker service create --replicas 2 --network my-multi-host-network --name my-web nginx $ docker service create --replicas 2 --network my-multi-host-network --name my-web nginx
716thylsndqma81j6kkkb5aus 716thylsndqma81j6kkkb5aus
``` ```
Overlay networks for a swarm are not available to containers started with Only swarm services can connect to overlay networks, not standalone containers.
`docker run` that don't run as part of a swarm mode service. For more For more information about swarms, see
information refer to [Docker swarm mode overlay network security model](overlay-security-model.md). [Docker swarm mode overlay network security model](overlay-security-model.md) and
[Attach services to an overlay network](../../swarm/networking.md).
See also [Attach services to an overlay network](../../swarm/networking.md). ### An overlay network without swarm mode
### An overlay network with an external key-value store
If you are not using Docker Engine in swarm mode, the `overlay` network requires If you are not using Docker Engine in swarm mode, the `overlay` network requires
a valid key-value store service. Supported key-value stores include Consul, a valid key-value store service. Supported key-value stores include Consul,
Etcd, and ZooKeeper (Distributed store). Before creating a network on this Etcd, and ZooKeeper (Distributed store). Before creating a network in this way,
version of the Engine, you must install and configure your chosen key-value you must install and configure your chosen key-value store service. The Docker
store service. The Docker hosts that you intend to network and the service must hosts that you intend to network and the service must be able to communicate.
be able to communicate.
>**Note**: Docker Engine running in swarm mode is not compatible with networking > **Note**: Docker Engine running in swarm mode is not compatible with networking
with an external key-value store. > with an external key-value store.
![Key-value store](images/key_value.png) This way of using overlay networks is not recommended for most Docker users. It
can be used with standalone swarms and may be useful to system developers
building solutions on top of Docker. It may be deprecated in the future. If you
think you may need to use overlay networks in this way, see
[this guide](get-started-overlay.md).
Each host in the network must run a Docker Engine instance. The easiest way to ### Custom network plugins
provision the hosts is with Docker Machine.
![Engine on each host](images/engine_on_net.png) If your needs are not addressed by any of the above network mechanisms, you can
write your own network driver plugin, using Docker's plugin infrastructure.
You should open the following ports between each of your hosts. The plugin will run as a separate process on the host which runs the Docker
daemon. Using network plugins is an advanced topic.
| Protocol | Port | Description |
|----------|------|-----------------------|
| udp | 4789 | Data plane (VXLAN) |
| tcp/udp | 7946 | Control plane |
Your key-value store service may require additional ports.
Check your vendor's documentation and open any required ports.
If you are planning on creating an overlay network with encryption (`--opt encrypted`),
you will also need to ensure protocol 50 (ESP) traffic is allowed.
Once you have several machines provisioned, you can use Docker Swarm to quickly
form them into a swarm which includes a discovery service as well.
To create an overlay network, you configure options on the `daemon` on each
Docker Engine for use with `overlay` network. There are three options to set:
<table>
<thead>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><pre>--cluster-store=PROVIDER://URL</pre></td>
<td>Describes the location of the KV service.</td>
</tr>
<tr>
<td><pre>--cluster-advertise=HOST_IP|HOST_IFACE:PORT</pre></td>
<td>The IP address or interface of the HOST used for clustering.</td>
</tr>
<tr>
<td><pre>--cluster-store-opt=KEY-VALUE OPTIONS</pre></td>
<td>Options such as TLS certificate or tuning discovery Timers</td>
</tr>
</tbody>
</table>
Create an `overlay` network on one of the machines in the swarm.
$ docker network create --driver overlay my-multi-host-network
This results in a single network spanning multiple hosts. An `overlay` network
provides complete isolation for the containers.
![An overlay network](images/overlay_network.png)
Then, on each host, launch containers making sure to specify the network name.
$ docker run -itd --network=my-multi-host-network busybox
Once connected, each container has access to all the containers in the network
regardless of which Docker host the container was launched on.
![Published port](images/overlay-network-final.png)
If you would like to try this for yourself, see the [Getting started for
overlay](get-started-overlay.md).
### Custom network plugin
If you like, you can write your own network driver plugin. A network
driver plugin makes use of Docker's plugin infrastructure. In this
infrastructure, a plugin is a process running on the same Docker host as the
Docker `daemon`.
Network plugins follow the same restrictions and installation rules as other Network plugins follow the same restrictions and installation rules as other
plugins. All plugins make use of the plugin API. They have a lifecycle that plugins. All plugins use the plugin API, and have a lifecycle that encompasses
encompasses installation, starting, stopping and activation. installation, starting, stopping and activation.
Once you have created and installed a custom network driver, you use it like the Once you have created and installed a custom network driver, you can create
built-in network drivers. For example: a network which uses that driver with the `--driver` flag.
$ docker network create --driver weave mynet ```bash
$ docker network create --driver weave mynet
```
You can inspect it, add containers to and delete from it, and so forth. Of course, You can inspect the network, connect and disconnect containers from it, and
different plugins may make use of different technologies or frameworks. Custom remove it. A specific plugin may have specific requirements in order to be
networks can include features not present in Docker's default networks. For more used. Check that plugin's documentation for specific information. For more
information on writing plugins, see [Extending Docker](../../extend/legacy_plugins.md) and information on writing plugins, see
[Extending Docker](../../extend/legacy_plugins.md) and
[Writing a network driver plugin](../../extend/plugins_network.md). [Writing a network driver plugin](../../extend/plugins_network.md).
### Docker embedded DNS server ### Embedded DNS server
Docker daemon runs an embedded DNS server to provide automatic service discovery Docker daemon runs an embedded DNS server which provides DNS resolution among
for containers connected to user defined networks. Name resolution requests from containers connected to the same user-defined network, so that these containers
the containers are handled first by the embedded DNS server. If the embedded DNS can resolve container names to IP addresses. If the embedded DNS server is
server is unable to resolve the request it will be forwarded to any external DNS unable to resolve the request, it will be forwarded to any external DNS servers
servers configured for the container. To facilitate this when the container is configured for the container. To facilitate this when the container is created,
created, only the embedded DNS server reachable at `127.0.0.11` will be listed only the embedded DNS server reachable at `127.0.0.11` will be listed in the
in the container's `resolv.conf` file. More information on embedded DNS server on container's `resolv.conf` file. For more information on embedded DNS server on
user-defined networks can be found in the [embedded DNS server in user-defined networks](configure-dns.md) user-defined networks, see
[embedded DNS server in user-defined networks](configure-dns.md)
## Exposing and publishing ports
In Docker networking, there are two different mechanisms that directly involve
network ports: exposing and publishing ports. This applies to the default bridge
network and user-defined bridge networks.
- You expose ports using the `EXPOSE` keyword in the Dockerfile or the
`--expose` flag to `docker run`. Exposing ports is a way of documenting which
ports are used, but does not actually map or open any ports. Exposing ports
is optional.
- You publish ports using the `PUBLISH` keyword in the Dockerfile or the
`--publish` flag to `docker run`. This tells Docker which ports to open on the
container's network interface. When a port is published, it is mapped to an
available high-order port (higher than `30000`) on the host machine, unless
you specify the port to map to on the host machine at runtime. You cannot
specify the port to map to on the host machine in the Dockerfile, because
there is no way to guarantee that the port will be available on the host
machine where you run the image.
This example publishes port 80 in the container to a random high
port (in this case, `32768`) on the host machine.
```bash
$ docker run -it -p 80 nginx
$ docker ps
64879472feea nginx "nginx -g 'daemon ..." 43 hours ago Up About a minute 443/tcp, 0.0.0.0:32768->80/tcp blissful_mclean
```
The next example specifies that port 80 should be mapped to port 8080 on the
host machine. It will fail if port 8080 is not available.
```bash
$ docker run -it -p 80:8080 nginx
$ docker ps
b9788c7adca3 nginx "nginx -g 'daemon ..." 43 hours ago Up 3 seconds 80/tcp, 443/tcp, 0.0.0.0:80->8080/tcp goofy_brahmagupta
```
## Links ## Links
Before the Docker network feature, you could use the Docker link feature to Before Docker included user-defined networks, you could use the Docker `--link`
allow containers to discover each other. With the introduction of Docker networks, feature to allow a container to resolve another container's name to an IP
containers can be discovered by its name automatically. But you can still create address, and also give it access to the linked container's environment variables.
links but they behave differently when used in the default `docker0` bridge network Where possible, you should avoid using the legacy `--link` flag.
compared to user-defined networks. For more information, please refer to
[Legacy Links](default_network/dockerlinks.md) for link feature in default `bridge` network When you create links, they behave differently when you use the default `bridge`
and the [linking containers in user-defined networks](work-with-networks.md#linking-containers-in-user-defined-networks) for links network or when you use user-defined bridge networks. For more information,
functionality in user-defined networks. see [Legacy Links](default_network/dockerlinks.md) for link feature
in default `bridge` network and the
[linking containers in user-defined networks](work-with-networks.md#linking-containers-in-user-defined-networks)
for links functionality in user-defined networks.
## Related information ## Related information