github.com/vincentwoo/docker@v0.7.3-0.20160116130405-82401a4b13c0/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 1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b 309 310 $ docker network inspect isolated_nw 311 [ 312 { 313 "Name": "isolated_nw", 314 "Id": "1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b", 315 "Scope": "local", 316 "Driver": "bridge", 317 "IPAM": { 318 "Driver": "default", 319 "Config": [ 320 { 321 "Subnet": "172.21.0.0/16", 322 "Gateway": "172.21.0.1/16" 323 } 324 ] 325 }, 326 "Containers": {}, 327 "Options": {} 328 } 329 ] 330 331 $ docker network ls 332 NETWORK ID NAME DRIVER 333 9f904ee27bf5 none null 334 cf03ee007fb4 host host 335 7fca4eb8c647 bridge bridge 336 c5ee82f76de3 isolated_nw bridge 337 338 ``` 339 340 After you create the network, you can launch containers on it using the `docker run --net=<NETWORK>` option. 341 342 ``` 343 $ docker run --net=isolated_nw -itd --name=container3 busybox 344 8c1a0a5be480921d669a073393ade66a3fc49933f08bcc5515b37b8144f6d47c 345 346 $ docker network inspect isolated_nw 347 [ 348 { 349 "Name": "isolated_nw", 350 "Id": "1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b", 351 "Scope": "local", 352 "Driver": "bridge", 353 "IPAM": { 354 "Driver": "default", 355 "Config": [ 356 {} 357 ] 358 }, 359 "Containers": { 360 "8c1a0a5be480921d669a073393ade66a3fc49933f08bcc5515b37b8144f6d47c": { 361 "EndpointID": "93b2db4a9b9a997beb912d28bcfc117f7b0eb924ff91d48cfa251d473e6a9b08", 362 "MacAddress": "02:42:ac:15:00:02", 363 "IPv4Address": "172.21.0.2/16", 364 "IPv6Address": "" 365 } 366 }, 367 "Options": {} 368 } 369 ] 370 ``` 371 372 The containers you launch into this network must reside on the same Docker host. 373 Each container in the network can immediately communicate with other containers 374 in the network. Though, the network itself isolates the containers from external 375 networks. 376 377  378 379 Within a user-defined bridge network, linking is not supported. You can 380 expose and publish container ports on containers in this network. This is useful 381 if you want to make a portion of the `bridge` network available to an outside 382 network. 383 384  385 386 A bridge network is useful in cases where you want to run a relatively small 387 network on a single host. You can, however, create significantly larger networks 388 by creating an `overlay` network. 389 390 391 ### An overlay network 392 393 Docker's `overlay` network driver supports multi-host networking natively 394 out-of-the-box. This support is accomplished with the help of `libnetwork`, a 395 built-in VXLAN-based overlay network driver, and Docker's `libkv` library. 396 397 The `overlay` network requires a valid key-value store service. Currently, 398 Docker's `libkv` supports Consul, Etcd, and ZooKeeper (Distributed store). Before 399 creating a network you must install and configure your chosen key-value store 400 service. The Docker hosts that you intend to network and the service must be 401 able to communicate. 402 403  404 405 Each host in the network must run a Docker Engine instance. The easiest way to 406 provision the hosts are with Docker Machine. 407 408  409 410 You should open the following ports between each of your hosts. 411 412 | Protocol | Port | Description | 413 |----------|------|-----------------------| 414 | udp | 4789 | Data plane (VXLAN) | 415 | tcp/udp | 7946 | Control plane | 416 417 Your key-value store service may require additional ports. 418 Check your vendor's documentation and open any required ports. 419 420 Once you have several machines provisioned, you can use Docker Swarm to quickly 421 form them into a swarm which includes a discovery service as well. 422 423 To create an overlay network, you configure options on the `daemon` on each 424 Docker Engine for use with `overlay` network. There are two options to set: 425 426 <table> 427 <thead> 428 <tr> 429 <th>Option</th> 430 <th>Description</th> 431 </tr> 432 </thead> 433 <tbody> 434 <tr> 435 <td><pre>--cluster-store=PROVIDER://URL</pre></td> 436 <td>Describes the location of the KV service.</td> 437 </tr> 438 <tr> 439 <td><pre>--cluster-advertise=HOST_IP|HOST_IFACE:PORT</pre></td> 440 <td>The IP address or interface of the HOST used for clustering.</td> 441 </tr> 442 </tbody> 443 </table> 444 445 Create an `overlay` network on one of the machines in the Swarm. 446 447 $ docker network create --driver overlay my-multi-host-network 448 449 This results in a single network spanning multiple hosts. An `overlay` network 450 provides complete isolation for the containers. 451 452  453 454 Then, on each host, launch containers making sure to specify the network name. 455 456 $ docker run -itd --net=my-multi-host-network busybox 457 458 Once connected, each container has access to all the containers in the network 459 regardless of which Docker host the container was launched on. 460 461  462 463 If you would like to try this for yourself, see the [Getting started for 464 overlay](get-started-overlay.md). 465 466 ### Custom network plugin 467 468 If you like, you can write your own network driver plugin. A network 469 driver plugin makes use of Docker's plugin infrastructure. In this 470 infrastructure, a plugin is a process running on the same Docker host as the 471 Docker `daemon`. 472 473 Network plugins follow the same restrictions and installation rules as other 474 plugins. All plugins make use of the plugin API. They have a lifecycle that 475 encompasses installation, starting, stopping and activation. 476 477 Once you have created and installed a custom network driver, you use it like the 478 built-in network drivers. For example: 479 480 $ docker network create --driver weave mynet 481 482 You can inspect it, add containers too and from it, and so forth. Of course, 483 different plugins may make use of different technologies or frameworks. Custom 484 networks can include features not present in Docker's default networks. For more 485 information on writing plugins, see [Extending Docker](../../extend/index.md) and 486 [Writing a network driver plugin](../../extend/plugins_network.md). 487 488 ## Legacy links 489 490 Before the Docker network feature, you could use the Docker link feature to 491 allow containers to discover each other and securely transfer information about 492 one container to another container. With the introduction of Docker networks, 493 you can still create links but they are only supported on the default `bridge` 494 network named `bridge` and appearing in your network stack as `docker0`. 495 496 While links are still supported in this limited capacity, you should avoid them 497 in preference of Docker networks. The link feature is expected to be deprecated 498 and removed in a future release. 499 500 ## Related information 501 502 - [Work with network commands](work-with-networks.md) 503 - [Get started with multi-host networking](get-started-overlay.md) 504 - [Managing Data in Containers](../dockervolumes.md) 505 - [Docker Machine overview](https://docs.docker.com/machine) 506 - [Docker Swarm overview](https://docs.docker.com/swarm) 507 - [Investigate the LibNetwork project](https://github.com/docker/libnetwork)