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
---
This section provides an overview of the default networking behavior that Docker
Engine delivers natively. It describes the type of networks created by default
and how to create your own, user-defined networks. It also describes the
resources required to create networks on a single host or across a cluster of
hosts.
This section provides an overview of Docker's default networking behavior,
including the type of networks created by default and how to create your own
user-defined networks. It also describes the resources required to create
networks on a single host or across a cluster of hosts.
## Default Networks
@ -27,9 +26,9 @@ NETWORK ID NAME DRIVER
cf03ee007fb4 host host
```
Historically, these three networks are part of Docker's implementation. When
you run a container you can use the `--network` flag to specify which network you
want to run a container on. These three networks are still available to you.
These three networks are built into Docker. When
you run a container, you can use the `--network` flag to specify which networks
your container should connect to.
The `bridge` network represents the `docker0` network present in all Docker
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
the `ifconfig` command on the host.
```
```bash
$ ifconfig
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)
```
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
root@0cb243cd1293:/# cat /etc/hosts
@ -74,24 +75,29 @@ lo Link encap:Local Loopback
root@0cb243cd1293:/#
```
>**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
network configuration inside the container is identical to the host.
The `host` network adds a container on the host's network stack. As far as the
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
interact with these default networks. While you can list and inspect them, you
cannot remove them. They are required by your Docker installation. However, you
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 `none` and `host` networks are not directly configurable in Docker.
However, you can configure the default `bridge` network, as well as your own
user-defined bridge networks.
### The default bridge network in detail
The default `bridge` network is present on all Docker hosts. The `docker network inspect`
command returns information about a network:
### The default bridge 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
[
@ -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
3386a527aa08b37ea9232cbcace2d2458d49f44bb05a6b775fba7ddd40d8f92c
@ -135,9 +142,12 @@ $ docker run -itd --name=container2 busybox
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
{[
@ -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
root@0cb243cd1293:/# 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
@ -209,10 +227,10 @@ lo Link encap:Local Loopback
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
containers on this `bridge` network.
From inside the container, use the `ping` command to test the network connection
to the IP address of the other container.
```
```none
root@0cb243cd1293:/# ping -w3 172.17.0.3
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
```
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
@ -238,78 +257,44 @@ ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
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.
```
$ docker attach container2
To detach from the `container1` container and leave it running, use the keyboard
sequence **CTRL-p CTRL-q**. If you wish, attach to `container2` and repeat the
commands above.
root@0cb243cd1293:/# 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: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.
The default `docker0` bridge network supports the use of port mapping and
`docker run --link` to allow communications among containers in the `docker0`
network. This approach is not recommended. Where possible, you should use
[user-defined bridge networks](#user-defined-networks) instead.
## User-defined networks
You can create your own user-defined networks that better isolate containers.
Docker provides some default **network drivers** for creating these networks.
You can create a new **bridge network**, **overlay network** or **MACVLAN
network**. You can also create a **network plugin** or **remote network**
written to your own specifications.
It is recommended to use user-defined bridge networks to control which
containers can communicate with each other, and also to enable automatic DNS
resolution of container names to IP addresses. Docker provides default **network
drivers** for creating these networks. You can create a new **bridge network**,
**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
network. Containers can only communicate within networks but not across
networks. A container attached to two networks can communicate with member
containers in either network. When a container is connected to multiple
networks, its external connectivity is provided via the first non-internal
network, in lexical order.
You can create as many networks as you need, and you can connect a container to
zero or more of these networks at any given time. In addition, you can connect
and disconnect running containers from networks without restarting the
container. When a container is connected to multiple networks, its external
connectivity is provided via the first non-internal network, in lexical order.
The next few sections describe each of Docker's built-in network drivers in
greater detail.
### A bridge network
### Bridge networks
The easiest user-defined network to create is a `bridge` network. This network
is similar to the historical, default `docker0` network. There are some added
features and some old features that aren't available.
A `bridge` network is the most common type of network used in Docker. Bridge
networks are similar to the default `bridge` network, but add some new features
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
1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b
$ 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
8c1a0a5be480921d669a073393ade66a3fc49933f08bcc5515b37b8144f6d47c
@ -387,9 +373,9 @@ networks.
![An isolated network](images/bridge_network.png)
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
if you want to make a portion of the `bridge` network available to an outside
network.
[expose and publish container ports](#exposing-and-publishing-ports) on
containers in this network. This is useful if you want to make a portion of the
`bridge` network available to an outside network.
![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.
### 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
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
[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
# Create an overlay network `my-multi-host-network`.
```bash.
$ docker network create \
--driver overlay \
--subnet 10.0.9.0/24 \
@ -444,144 +430,125 @@ $ docker network create \
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
716thylsndqma81j6kkkb5aus
```
Overlay networks for a swarm are not available to containers started with
`docker run` that don't run as part of a swarm mode service. For more
information refer to [Docker swarm mode overlay network security model](overlay-security-model.md).
Only swarm services can connect to overlay networks, not standalone containers.
For more information about swarms, see
[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 with an external key-value store
### An overlay network without swarm mode
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,
Etcd, and ZooKeeper (Distributed store). Before creating a network on this
version of the Engine, you must install and configure your chosen key-value
store service. The Docker hosts that you intend to network and the service must
be able to communicate.
Etcd, and ZooKeeper (Distributed store). Before creating a network in this way,
you must install and configure your chosen key-value store service. The Docker
hosts that you intend to network and the service must be able to communicate.
>**Note**: Docker Engine running in swarm mode is not compatible with networking
with an external key-value store.
> **Note**: Docker Engine running in swarm mode is not compatible with networking
> 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
provision the hosts is with Docker Machine.
### Custom network plugins
![Engine on each host](images/engine_on_net.png)
You should open the following ports between each of your hosts.
| 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`.
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.
The plugin will run as a separate process on the host which runs the Docker
daemon. Using network plugins is an advanced topic.
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
encompasses installation, starting, stopping and activation.
plugins. All plugins use the plugin API, and have a lifecycle that encompasses
installation, starting, stopping and activation.
Once you have created and installed a custom network driver, you use it like the
built-in network drivers. For example:
Once you have created and installed a custom network driver, you can create
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,
different plugins may make use of different technologies or frameworks. Custom
networks can include features not present in Docker's default networks. For more
information on writing plugins, see [Extending Docker](../../extend/legacy_plugins.md) and
You can inspect the network, connect and disconnect containers from it, and
remove it. A specific plugin may have specific requirements in order to be
used. Check that plugin's documentation for specific information. For more
information on writing plugins, see
[Extending Docker](../../extend/legacy_plugins.md) and
[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
for containers connected to user defined networks. Name resolution requests from
the containers are handled first by the embedded DNS server. If the embedded DNS
server is unable to resolve the request it will be forwarded to any external DNS
servers configured for the container. To facilitate this when the container is
created, only the embedded DNS server reachable at `127.0.0.11` will be listed
in the container's `resolv.conf` file. 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)
Docker daemon runs an embedded DNS server which provides DNS resolution among
containers connected to the same user-defined network, so that these containers
can resolve container names to IP addresses. If the embedded DNS server is
unable to resolve the request, it will be forwarded to any external DNS servers
configured for the container. To facilitate this when the container is created,
only the embedded DNS server reachable at `127.0.0.11` will be listed in the
container's `resolv.conf` file. For more information on embedded DNS server on
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
Before the Docker network feature, you could use the Docker link feature to
allow containers to discover each other. With the introduction of Docker networks,
containers can be discovered by its name automatically. But you can still create
links but they behave differently when used in the default `docker0` bridge network
compared to user-defined networks. For more information, please refer to
[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.
Before Docker included user-defined networks, you could use the Docker `--link`
feature to allow a container to resolve another container's name to an IP
address, and also give it access to the linked container's environment variables.
Where possible, you should avoid using the legacy `--link` flag.
When you create links, they behave differently when you use the default `bridge`
network or when you use user-defined bridge networks. For more information,
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