github.com/walkingsparrow/docker@v1.4.2-0.20151218153551-b708a2249bfa/docs/userguide/networking/dockernetworks.md (about) 1 <!--[metadata]> 2 +++ 3 title = "Docker container networking" 4 description = "How do we connect docker containers within and across hosts ?" 5 keywords = ["Examples, Usage, network, docker, documentation, user guide, multihost, cluster"] 6 [menu.main] 7 parent = "smn_networking" 8 weight = -5 9 +++ 10 <![end-metadata]--> 11 12 # Understand Docker container networks 13 14 To build web applications that act in concert but do so securely, use the Docker 15 networks feature. Networks, by definition, provide complete isolation for 16 containers. So, it is important to have control over the networks your 17 applications run on. Docker container networks give you that control. 18 19 This section provides an overview of the default networking behavior that Docker 20 Engine delivers natively. It describes the type of networks created by default 21 and how to create your own, user--defined networks. It also describes the 22 resources required to create networks on a single host or across a cluster of 23 hosts. 24 25 ## Default Networks 26 27 When you install Docker, it creates three networks automatically. You can list 28 these networks using the `docker network ls` command: 29 30 ``` 31 $ docker network ls 32 NETWORK ID NAME DRIVER 33 7fca4eb8c647 bridge bridge 34 9f904ee27bf5 none null 35 cf03ee007fb4 host host 36 ``` 37 38 Historically, these three networks are part of Docker's implementation. When 39 you run a container you can use the `--net` flag to specify which network you 40 want to run a container on. These three networks are still available to you. 41 42 The `bridge` network represents the `docker0` network present in all Docker 43 installations. Unless you specify otherwise with the `docker run 44 --net=<NETWORK>` option, the Docker daemon connects containers to this network 45 by default. You can see this bridge as part of a host's network stack by using 46 the `ifconfig` command on the host. 47 48 ``` 49 ubuntu@ip-172-31-36-118:~$ ifconfig 50 docker0 Link encap:Ethernet HWaddr 02:42:47:bc:3a:eb 51 inet addr:172.17.0.1 Bcast:0.0.0.0 Mask:255.255.0.0 52 inet6 addr: fe80::42:47ff:febc:3aeb/64 Scope:Link 53 UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1 54 RX packets:17 errors:0 dropped:0 overruns:0 frame:0 55 TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 56 collisions:0 txqueuelen:0 57 RX bytes:1100 (1.1 KB) TX bytes:648 (648.0 B) 58 ``` 59 60 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 it's stack you see this: 61 62 ``` 63 ubuntu@ip-172-31-36-118:~$ docker attach nonenetcontainer 64 65 / # cat /etc/hosts 66 127.0.0.1 localhost 67 ::1 localhost ip6-localhost ip6-loopback 68 fe00::0 ip6-localnet 69 ff00::0 ip6-mcastprefix 70 ff02::1 ip6-allnodes 71 ff02::2 ip6-allrouters 72 / # ifconfig 73 lo Link encap:Local Loopback 74 inet addr:127.0.0.1 Mask:255.0.0.0 75 inet6 addr: ::1/128 Scope:Host 76 UP LOOPBACK RUNNING MTU:65536 Metric:1 77 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 78 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 79 collisions:0 txqueuelen:0 80 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) 81 82 / # 83 ``` 84 >**Note**: You can detach from the container and leave it running with `CTRL-p CTRL-q`. 85 86 The `host` network adds a container on the hosts network stack. You'll find the 87 network configuration inside the container is identical to the host. 88 89 With the exception of the the `bridge` network, you really don't need to 90 interact with these default networks. While you can list and inspect them, you 91 cannot remove them. They are required by your Docker installation. However, you 92 can add your own user-defined networks and these you can remove when you no 93 longer need them. Before you learn more about creating your own networks, it is 94 worth looking at the `default` network a bit. 95 96 97 ### The default bridge network in detail 98 The default bridge network is present on all Docker hosts. The `docker network inspect` 99 100 ``` 101 $ docker network inspect bridge 102 [ 103 { 104 "Name": "bridge", 105 "Id": "f7ab26d71dbd6f557852c7156ae0574bbf62c42f539b50c8ebde0f728a253b6f", 106 "Scope": "local", 107 "Driver": "bridge", 108 "IPAM": { 109 "Driver": "default", 110 "Config": [ 111 { 112 "Subnet": "172.17.0.1/16", 113 "Gateway": "172.17.0.1" 114 } 115 ] 116 }, 117 "Containers": {}, 118 "Options": { 119 "com.docker.network.bridge.default_bridge": "true", 120 "com.docker.network.bridge.enable_icc": "true", 121 "com.docker.network.bridge.enable_ip_masquerade": "true", 122 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 123 "com.docker.network.bridge.name": "docker0", 124 "com.docker.network.driver.mtu": "9001" 125 } 126 } 127 ] 128 ``` 129 The Engine automatically creates a `Subnet` and `Gateway` to the network. 130 The `docker run` command automatically adds new containers to this network. 131 132 ``` 133 $ docker run -itd --name=container1 busybox 134 3386a527aa08b37ea9232cbcace2d2458d49f44bb05a6b775fba7ddd40d8f92c 135 136 $ docker run -itd --name=container2 busybox 137 94447ca479852d29aeddca75c28f7104df3c3196d7b6d83061879e339946805c 138 ``` 139 140 Inspecting the `bridge` network again after starting two containers shows both newly launched containers in the network. Their ids show up in the container 141 142 ``` 143 $ docker network inspect bridge 144 {[ 145 { 146 "Name": "bridge", 147 "Id": "f7ab26d71dbd6f557852c7156ae0574bbf62c42f539b50c8ebde0f728a253b6f", 148 "Scope": "local", 149 "Driver": "bridge", 150 "IPAM": { 151 "Driver": "default", 152 "Config": [ 153 { 154 "Subnet": "172.17.0.1/16", 155 "Gateway": "172.17.0.1" 156 } 157 ] 158 }, 159 "Containers": { 160 "3386a527aa08b37ea9232cbcace2d2458d49f44bb05a6b775fba7ddd40d8f92c": { 161 "EndpointID": "647c12443e91faf0fd508b6edfe59c30b642abb60dfab890b4bdccee38750bc1", 162 "MacAddress": "02:42:ac:11:00:02", 163 "IPv4Address": "172.17.0.2/16", 164 "IPv6Address": "" 165 }, 166 "94447ca479852d29aeddca75c28f7104df3c3196d7b6d83061879e339946805c": { 167 "EndpointID": "b047d090f446ac49747d3c37d63e4307be745876db7f0ceef7b311cbba615f48", 168 "MacAddress": "02:42:ac:11:00:03", 169 "IPv4Address": "172.17.0.3/16", 170 "IPv6Address": "" 171 } 172 }, 173 "Options": { 174 "com.docker.network.bridge.default_bridge": "true", 175 "com.docker.network.bridge.enable_icc": "true", 176 "com.docker.network.bridge.enable_ip_masquerade": "true", 177 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 178 "com.docker.network.bridge.name": "docker0", 179 "com.docker.network.driver.mtu": "9001" 180 } 181 } 182 ] 183 ``` 184 185 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. 186 187 You can `attach` to a running `container` and investigate its configuration: 188 189 ``` 190 $ docker attach container1 191 192 / # ifconfig 193 ifconfig 194 eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:02 195 inet addr:172.17.0.2 Bcast:0.0.0.0 Mask:255.255.0.0 196 inet6 addr: fe80::42:acff:fe11:2/64 Scope:Link 197 UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1 198 RX packets:16 errors:0 dropped:0 overruns:0 frame:0 199 TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 200 collisions:0 txqueuelen:0 201 RX bytes:1296 (1.2 KiB) TX bytes:648 (648.0 B) 202 203 lo Link encap:Local Loopback 204 inet addr:127.0.0.1 Mask:255.0.0.0 205 inet6 addr: ::1/128 Scope:Host 206 UP LOOPBACK RUNNING MTU:65536 Metric:1 207 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 208 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 209 collisions:0 txqueuelen:0 210 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) 211 ``` 212 213 Then use `ping` for about 3 seconds to test the connectivity of the containers on this `bridge` network. 214 215 ``` 216 / # ping -w3 172.17.0.3 217 PING 172.17.0.3 (172.17.0.3): 56 data bytes 218 64 bytes from 172.17.0.3: seq=0 ttl=64 time=0.096 ms 219 64 bytes from 172.17.0.3: seq=1 ttl=64 time=0.080 ms 220 64 bytes from 172.17.0.3: seq=2 ttl=64 time=0.074 ms 221 222 --- 172.17.0.3 ping statistics --- 223 3 packets transmitted, 3 packets received, 0% packet loss 224 round-trip min/avg/max = 0.074/0.083/0.096 ms 225 ``` 226 227 Finally, use the `cat` command to check the `container1` network configuration: 228 229 ``` 230 / # cat /etc/hosts 231 172.17.0.2 3386a527aa08 232 127.0.0.1 localhost 233 ::1 localhost ip6-localhost ip6-loopback 234 fe00::0 ip6-localnet 235 ff00::0 ip6-mcastprefix 236 ff02::1 ip6-allnodes 237 ff02::2 ip6-allrouters 238 ``` 239 To detach from a `container1` and leave it running use `CTRL-p CTRL-q`.Then, attach to `container2` and repeat these three commands. 240 241 ``` 242 $ docker attach container2 243 244 / # ifconfig 245 eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03 246 inet addr:172.17.0.3 Bcast:0.0.0.0 Mask:255.255.0.0 247 inet6 addr: fe80::42:acff:fe11:3/64 Scope:Link 248 UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1 249 RX packets:15 errors:0 dropped:0 overruns:0 frame:0 250 TX packets:13 errors:0 dropped:0 overruns:0 carrier:0 251 collisions:0 txqueuelen:0 252 RX bytes:1166 (1.1 KiB) TX bytes:1026 (1.0 KiB) 253 254 lo Link encap:Local Loopback 255 inet addr:127.0.0.1 Mask:255.0.0.0 256 inet6 addr: ::1/128 Scope:Host 257 UP LOOPBACK RUNNING MTU:65536 Metric:1 258 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 259 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 260 collisions:0 txqueuelen:0 261 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) 262 263 / # ping -w3 172.17.0.2 264 PING 172.17.0.2 (172.17.0.2): 56 data bytes 265 64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.067 ms 266 64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.075 ms 267 64 bytes from 172.17.0.2: seq=2 ttl=64 time=0.072 ms 268 269 --- 172.17.0.2 ping statistics --- 270 3 packets transmitted, 3 packets received, 0% packet loss 271 round-trip min/avg/max = 0.067/0.071/0.075 ms 272 / # cat /etc/hosts 273 172.17.0.3 94447ca47985 274 127.0.0.1 localhost 275 ::1 localhost ip6-localhost ip6-loopback 276 fe00::0 ip6-localnet 277 ff00::0 ip6-mcastprefix 278 ff02::1 ip6-allnodes 279 ff02::2 ip6-allrouters 280 ``` 281 282 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. 283 284 ## User-defined networks 285 286 You can create your own user-defined networks that better isolate containers. 287 Docker provides some default **network drivers** for use creating these 288 networks. You can create a new **bridge network** or **overlay network**. You 289 can also create a **network plugin** or **remote network** written to your own 290 specifications. 291 292 You can create multiple networks. You can add containers to more than one 293 network. Containers can only communicate within networks but not across 294 networks. A container attached to two networks can communicate with member 295 containers in either network. 296 297 The next few sections describe each of Docker's built-in network drivers in 298 greater detail. 299 300 ### A bridge network 301 302 The easiest user-defined network to create is a `bridge` network. This network 303 is similar to the historical, default `docker0` network. There are some added 304 features and some old features that aren't available. 305 306 ``` 307 $ docker network create --driver bridge isolated_nw 308 c5ee82f76de30319c75554a57164c682e7372d2c694fec41e42ac3b77e570f6b 309 310 $ docker network inspect isolated_nw 311 [ 312 { 313 "Name": "isolated_nw", 314 "Id": "c5ee82f76de30319c75554a57164c682e7372d2c694fec41e42ac3b77e570f6b", 315 "Scope": "local", 316 "Driver": "bridge", 317 "IPAM": { 318 "Driver": "default", 319 "Config": [ 320 {} 321 ] 322 }, 323 "Containers": {}, 324 "Options": {} 325 } 326 ] 327 328 $ docker network ls 329 NETWORK ID NAME DRIVER 330 9f904ee27bf5 none null 331 cf03ee007fb4 host host 332 7fca4eb8c647 bridge bridge 333 c5ee82f76de3 isolated_nw bridge 334 335 ``` 336 337 After you create the network, you can launch containers on it using the `docker run --net=<NETWORK>` option. 338 339 ``` 340 $ docker run --net=isolated_nw -itd --name=container3 busybox 341 885b7b4f792bae534416c95caa35ba272f201fa181e18e59beba0c80d7d77c1d 342 343 $ docker network inspect isolated_nw 344 [ 345 { 346 "Name": "isolated_nw", 347 "Id": "c5ee82f76de30319c75554a57164c682e7372d2c694fec41e42ac3b77e570f6b", 348 "Scope": "local", 349 "Driver": "bridge", 350 "IPAM": { 351 "Driver": "default", 352 "Config": [ 353 {} 354 ] 355 }, 356 "Containers": { 357 "885b7b4f792bae534416c95caa35ba272f201fa181e18e59beba0c80d7d77c1d": { 358 "EndpointID": "514e1b419074397ea92bcfaa6698d17feb62db49d1320a27393b853ec65319c3", 359 "MacAddress": "02:42:ac:15:00:02", 360 "IPv4Address": "172.21.0.2/16", 361 "IPv6Address": "" 362 } 363 }, 364 "Options": {} 365 } 366 ] 367 ``` 368 369 The containers you launch into this network must reside on the same Docker host. 370 Each container in the network can immediately communicate with other containers 371 in the network. Though, the network itself isolates the containers from external 372 networks. 373 374  375 376 Within a user-defined bridge network, linking is not supported. You can 377 expose and publish container ports on containers in this network. This is useful 378 if you want to make a portion of the `bridge` network available to an outside 379 network. 380 381  382 383 A bridge network is useful in cases where you want to run a relatively small 384 network on a single host. You can, however, create significantly larger networks 385 by creating an `overlay` network. 386 387 388 ### An overlay network 389 390 Docker's `overlay` network driver supports multi-host networking natively 391 out-of-the-box. This support is accomplished with the help of `libnetwork`, a 392 built-in VXLAN-based overlay network driver, and Docker's `libkv` library. 393 394 The `overlay` network requires a valid key-value store service. Currently, 395 Docker's `libkv` supports Consul, Etcd, and ZooKeeper (Distributed store). Before 396 creating a network you must install and configure your chosen key-value store 397 service. The Docker hosts that you intend to network and the service must be 398 able to communicate. 399 400  401 402 Each host in the network must run a Docker Engine instance. The easiest way to 403 provision the hosts are with Docker Machine. 404 405  406 407 You should open the following ports between each of your hosts. 408 409 | Protocol | Port | Description | 410 |----------|------|-----------------------| 411 | udp | 4789 | Data plane (VXLAN) | 412 | tcp/udp | 7946 | Control plane | 413 414 Your key-value store service may require additional ports. 415 Check your vendor's documentation and open any required ports. 416 417 Once you have several machines provisioned, you can use Docker Swarm to quickly 418 form them into a swarm which includes a discovery service as well. 419 420 To create an overlay network, you configure options on the `daemon` on each 421 Docker Engine for use with `overlay` network. There are two options to set: 422 423 <table> 424 <thead> 425 <tr> 426 <th>Option</th> 427 <th>Description</th> 428 </tr> 429 </thead> 430 <tbody> 431 <tr> 432 <td><pre>--cluster-store=PROVIDER://URL</pre></td> 433 <td>Describes the location of the KV service.</td> 434 </tr> 435 <tr> 436 <td><pre>--cluster-advertise=HOST_IP|HOST_IFACE:PORT</pre></td> 437 <td>The IP address or interface of the HOST used for clustering.</td> 438 </tr> 439 </tbody> 440 </table> 441 442 Create an `overlay` network on one of the machines in the Swarm. 443 444 $ docker network create --driver overlay my-multi-host-network 445 446 This results in a single network spanning multiple hosts. An `overlay` network 447 provides complete isolation for the containers. 448 449  450 451 Then, on each host, launch containers making sure to specify the network name. 452 453 $ docker run -itd --net=my-multi-host-network busybox 454 455 Once connected, each container has access to all the containers in the network 456 regardless of which Docker host the container was launched on. 457 458  459 460 If you would like to try this for yourself, see the [Getting started for 461 overlay](get-started-overlay.md). 462 463 ### Custom network plugin 464 465 If you like, you can write your own network driver plugin. A network 466 driver plugin makes use of Docker's plugin infrastructure. In this 467 infrastructure, a plugin is a process running on the same Docker host as the 468 Docker `daemon`. 469 470 Network plugins follow the same restrictions and installation rules as other 471 plugins. All plugins make use of the plugin API. They have a lifecycle that 472 encompasses installation, starting, stopping and activation. 473 474 Once you have created and installed a custom network driver, you use it like the 475 built-in network drivers. For example: 476 477 $ docker network create --driver weave mynet 478 479 You can inspect it, add containers too and from it, and so forth. Of course, 480 different plugins may make use of different technologies or frameworks. Custom 481 networks can include features not present in Docker's default networks. For more 482 information on writing plugins, see [Extending Docker](../../extend/index.md) and 483 [Writing a network driver plugin](../../extend/plugins_network.md). 484 485 ## Legacy links 486 487 Before the Docker network feature, you could use the Docker link feature to 488 allow containers to discover each other and securely transfer information about 489 one container to another container. With the introduction of Docker networks, 490 you can still create links but they are only supported on the default `bridge` 491 network named `bridge` and appearing in your network stack as `docker0`. 492 493 While links are still supported in this limited capacity, you should avoid them 494 in preference of Docker networks. The link feature is expected to be deprecated 495 and removed in a future release. 496 497 ## Related information 498 499 - [Work with network commands](work-with-networks.md) 500 - [Get started with multi-host networking](get-started-overlay.md) 501 - [Managing Data in Containers](../dockervolumes.md) 502 - [Docker Machine overview](https://docs.docker.com/machine) 503 - [Docker Swarm overview](https://docs.docker.com/swarm) 504 - [Investigate the LibNetwork project](https://github.com/docker/libnetwork)