Skip to content

Commit 3520fa2

Browse files
robmryrobmry
authored
Updates for moby 28.0 networking (#21612)
## Description Updates for moby 28.0 networking. ## Related issues or tickets Series of commits ... - Fix description of 'inhibit_ipv4' - Not changed in moby 28.0, updated to clarify difference from (new) IPv6-only networks. - Updates to default bridge address config - moby/moby#48319 - Describe IPv6-only network config - moby/moby#48271 - docker/cli#5599 - Update description of gateway modes - moby/moby#48594 - moby/moby#48596 - moby/moby#48597 - Describe gateway selection in the networking overview. - docker/cli#5664 - Describe gateway mode `isolated` - moby/moby#49262 ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: Rob Murray <[email protected]>
1 parent f4f7a49 commit 3520fa2

File tree

3 files changed

+160
-37
lines changed

3 files changed

+160
-37
lines changed

‎content/manuals/engine/network/_index.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,41 @@ networking functionality:
6464
For more information about the different drivers, see [Network drivers
6565
overview](./drivers/_index.md).
6666

67+
### Connecting to multiple networks
68+
69+
A container can be connected to multiple networks.
70+
71+
For example, a frontend container may be connected to a bridge network
72+
with external access, and a
73+
[`--internal`](/reference/cli/docker/network/create/#internal) network
74+
to communicate with containers running backend services that do not need
75+
external network access.
76+
77+
A container may also be connected to different types of network. For example,
78+
an `ipvlan` network to provide internet access, and a `bridge` network for
79+
access to local services.
80+
81+
When sending packets, if the destination is an address in a directly connected
82+
network, packets are sent to that network. Otherwise, packets are sent to
83+
a default gateway for routing to their destination. In the example above,
84+
the `ipvlan` network's gateway must be the default gateway.
85+
86+
The default gateway is selected by Docker, and may change whenever a
87+
container's network connections change.
88+
To make Docker choose a specific default gateway when creating the container
89+
or connecting a new network, set a gateway priority. See option `gw-priority`
90+
for the [`docker run`](/reference/cli/docker/container/run.md) and
91+
[`docker network connect`](/reference/cli/docker/network/connect.md) commands.
92+
93+
The default `gw-priority` is `0` and the gateway in the network with the
94+
highest priority is the default gateway. So, when a network should always
95+
be the default gateway, it is enough to set its `gw-priority` to `1`.
96+
97+
```console
98+
$ docker run --network name=gwnet,gw-priority=1 --network anet1 --name myctr myimage
99+
$ docker network connect anet2 myctr
100+
```
101+
67102
## Container networks
68103

69104
In addition to user-defined networks, you can attach a container to another
@@ -145,6 +180,14 @@ direct routing to containers, see
145180
146181
## IP address and hostname
147182
183+
When creating a network, IPv4 address allocation is enabled by default, it
184+
can be disabled using `--ipv4=false`. IPv6 address allocation can be enabled
185+
using `--ipv6`.
186+
187+
```console
188+
$ docker network create --ipv6 --ipv4=false v6net
189+
```
190+
148191
By default, the container gets an IP address for every Docker network it attaches to.
149192
A container receives an IP address out of the IP subnet of the network.
150193
The Docker daemon performs dynamic subnetting and IP address allocation for containers.

‎content/manuals/engine/network/drivers/bridge.md‎

Lines changed: 57 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -105,16 +105,16 @@ flag.
105105
The following table describes the driver-specific options that you can pass to
106106
`--opt` when creating a custom network using the `bridge` driver.
107107

108-
| Option | Default | Description |
109-
|-------------------------------------------------------------------------------------------------|-----------------------------|------------------------------------------------------------------------------------------------|
110-
| `com.docker.network.bridge.name` | | Interface name to use when creating the Linux bridge. |
111-
| `com.docker.network.bridge.enable_ip_masquerade` | `true` | Enable IP masquerading. |
112-
| `com.docker.network.bridge.gateway_mode_ipv4`<br/>`com.docker.network.bridge.gateway_mode_ipv6` | `nat` | Enable NAT and masquerading (`nat`), or only allow direct routing to the container (`routed`). |
113-
| `com.docker.network.bridge.enable_icc` | `true` | Enable or Disable inter-container connectivity. |
114-
| `com.docker.network.bridge.host_binding_ipv4` | all IPv4 and IPv6 addresses | Default IP when binding container ports. |
115-
| `com.docker.network.driver.mtu` | `0` (no limit) | Set the containers network Maximum Transmission Unit (MTU). |
116-
| `com.docker.network.container_iface_prefix` | `eth` | Set a custom prefix for container interfaces. |
117-
| `com.docker.network.bridge.inhibit_ipv4` | `false` | Prevent Docker from [assigning an IP address](#skip-ip-address-configuration) to the network. |
108+
| Option | Default | Description |
109+
|-------------------------------------------------------------------------------------------------|-----------------------------|-----------------------------------------------------------------------------------------------------|
110+
| `com.docker.network.bridge.name` | | Interface name to use when creating the Linux bridge. |
111+
| `com.docker.network.bridge.enable_ip_masquerade` | `true` | Enable IP masquerading. |
112+
| `com.docker.network.bridge.gateway_mode_ipv4`<br/>`com.docker.network.bridge.gateway_mode_ipv6` | `nat` | Control external connectivity. See [Packet filtering and firewalls](packet-filtering-firewalls.md). |
113+
| `com.docker.network.bridge.enable_icc` | `true` | Enable or Disable inter-container connectivity. |
114+
| `com.docker.network.bridge.host_binding_ipv4` | all IPv4 and IPv6 addresses | Default IP when binding container ports. |
115+
| `com.docker.network.driver.mtu` | `0` (no limit) | Set the containers network Maximum Transmission Unit (MTU). |
116+
| `com.docker.network.container_iface_prefix` | `eth` | Set a custom prefix for container interfaces. |
117+
| `com.docker.network.bridge.inhibit_ipv4` | `false` | Prevent Docker from [assigning an IP address](#skip-bridge-ip-address-configuration) to the bridge. |
118118

119119
Some of these options are also available as flags to the `dockerd` CLI, and you
120120
can use them to configure the default `docker0` bridge when starting the Docker
@@ -229,6 +229,20 @@ When you create your network, you can specify the `--ipv6` flag to enable IPv6.
229229
$ docker network create --ipv6 --subnet 2001:db8:1234::/64 my-net
230230
```
231231

232+
If you do not provide a `--subnet` option, a Unique Local Address (ULA) prefix
233+
will be chosen automatically.
234+
235+
## IPv6-only bridge networks
236+
237+
To skip IPv4 address configuration on the bridge and in its containers, create
238+
the network with option `--ipv4=false`, and enable IPv6 using `--ipv6`.
239+
240+
```console
241+
$ docker network create --ipv6 --ipv4=false v6net
242+
```
243+
244+
IPv4 address configuration cannot be disabled in the default bridge network.
245+
232246
## Use the default bridge network
233247

234248
The default `bridge` network is considered a legacy detail of Docker and is not
@@ -259,7 +273,12 @@ the settings you need to customize.
259273
}
260274
```
261275

262-
Restart Docker for the changes to take effect.
276+
In this example:
277+
278+
- The bridge's address is "192.168.1.1/24" (from `bip`).
279+
- The bridge network's subnet is "192.168.1.0/24" (from `bip`).
280+
- Container addresses will be allocated from "192.168.1.0/25" (from `fixed-cidr`).
281+
263282

264283
### Use IPv6 with the default bridge network
265284

@@ -270,22 +289,34 @@ These three options only affect the default bridge, they are not used by
270289
user-defined networks. The addresses in below are examples from the
271290
IPv6 documentation range.
272291

273-
- Option `ipv6` is required
274-
- Option `fixed-cidr-v6` is required, it specifies the network prefix to be used.
292+
- Option `ipv6` is required.
293+
- Option `bip6` is optional, it specifies the address of the default bridge, which
294+
will be used as the default gateway by containers. It also specifies the subnet
295+
for the bridge network.
296+
- Option `fixed-cidr-v6` is optional, it specifies the address range Docker may
297+
automatically allocate to containers.
275298
- The prefix should normally be `/64` or shorter.
276299
- For experimentation on a local network, it is better to use a Unique Local
277-
prefix (matching `fd00::/8`) than a Link Local prefix (matching `fe80::/10`).
300+
Address (ULA) prefix (matching `fd00::/8`) than a Link Local prefix (matching
301+
`fe80::/10`).
278302
- Option `default-gateway-v6` is optional. If unspecified, the default is the first
279303
address in the `fixed-cidr-v6` subnet.
280304

281305
```json
282306
{
283307
"ipv6": true,
308+
"bip6": "2001:db8::1111/64",
284309
"fixed-cidr-v6": "2001:db8::/64",
285310
"default-gateway-v6": "2001:db8:abcd::89"
286311
}
287312
```
288313

314+
If no `bip6` is specified, `fixed-cidr-v6` defines the subnet for the bridge
315+
network. If no `bip6` or `fixed-cidr-v6` is specified, a ULA prefix will be
316+
chosen.
317+
318+
Restart Docker for changes to take effect.
319+
289320
## Connection limit for bridge networks
290321

291322
Due to limitations set by the Linux kernel, bridge networks become unstable and
@@ -295,20 +326,22 @@ to a single network.
295326
For more information about this limitation, see
296327
[moby/moby#44973](https://github.com/moby/moby/issues/44973#issuecomment-1543747718).
297328

298-
## Skip IP address configuration
329+
## Skip Bridge IP address configuration
330+
331+
The bridge is normally assigned the network's `--gateway` address, which is
332+
used as the default route from the bridge network to other networks.
299333

300334
The `com.docker.network.bridge.inhibit_ipv4` option lets you create a network
301-
that uses an existing bridge and have Docker skip configuring the IPv4 address
302-
on the bridge. This is useful if you want to configure the IP address for the
303-
bridge manually. For instance if you add a physical interface to your bridge,
304-
and need to move its IP address to the bridge interface.
335+
without the IPv4 gateway address being assigned to the bridge. This is useful
336+
if you want to configure the gateway IP address for the bridge manually. For
337+
instance if you add a physical interface to your bridge, and need it to have
338+
the gateway address.
305339

306-
To use this option, you should first configure the Docker daemon to use a
307-
self-managed bridge, using the `bridge` option in the `daemon.json` or the
308-
`dockerd --bridge` flag.
340+
With this configuration, north-south traffic (to and from the bridge network)
341+
won't work unless you've manually configured the gateway address on the bridge,
342+
or a device attached to it.
309343

310-
With this configuration, north-south traffic won't work unless you've manually
311-
configured the IP address for the bridge.
344+
This option can only be used with user-defined bridge networks.
312345

313346
## Next steps
314347

‎content/manuals/engine/network/packet-filtering-firewalls.md‎

Lines changed: 60 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -129,31 +129,78 @@ clients. No routes are normally set up in the host's network for container
129129
addresses that exist within a host.
130130

131131
But, particularly with IPv6 you may prefer to avoid using NAT and instead
132-
arrange for external routing to container addresses.
132+
arrange for external routing to container addresses ("direct routing").
133133

134134
To access containers on a bridge network from outside the Docker host,
135135
you must set up routing to the bridge network via an address on the Docker
136136
host. This can be achieved using static routes, Border Gateway Protocol
137137
(BGP), or any other means appropriate for your network.
138138

139-
The bridge network driver has options
140-
`com.docker.network.bridge.gateway_mode_ipv6=<nat|routed>` and
141-
`com.docker.network.bridge.gateway_mode_ipv4=<nat|routed>`.
139+
Within a local layer 2 network, remote hosts can set up static routes
140+
to a container network using the Docker daemon host's address on the local
141+
network. Those hosts can access containers directly. For remote hosts
142+
outside the local network, direct access to containers requires router
143+
configuration to enable the necessary routing.
144+
145+
#### Gateway modes
146+
147+
The bridge network driver has the following options:
148+
- `com.docker.network.bridge.gateway_mode_ipv6`
149+
- `com.docker.network.bridge.gateway_mode_ipv4`
150+
151+
Each of these can be set to one of the gateway modes:
152+
- `nat`
153+
- `nat-unprotected`
154+
- `routed`
155+
- `isolated`
142156

143157
The default is `nat`, NAT and masquerading rules are set up for each
144-
published container port. With mode `routed`, no NAT or masquerading rules
145-
are set up, but `iptables` are still set up so that only published container
146-
ports are accessible.
158+
published container port. Packets leaving the host will use a host address.
159+
160+
With mode `routed`, no NAT or masquerading rules are set up, but `iptables`
161+
are still set up so that only published container ports are accessible.
162+
Outgoing packets from the container will use the container's address,
163+
not a host address.
164+
165+
In `nat` mode, when a port is published to a specific host address, that
166+
port is only accessible via the host interface with that address. So,
167+
for example, publishing a port to an address on the loopback interface
168+
means remote hosts cannot access it.
169+
170+
However, using direct routing, published container ports are always
171+
accessible from remote hosts, unless the Docker host's firewall has
172+
additional restrictions. Hosts on the local layer-2 network can set up
173+
direct routing without needing any additional network configuration.
174+
Hosts outside the local network can only use direct routing to the
175+
container if the network's routers are configured to enable it.
176+
177+
In `nat-unprotected` mode, unpublished container ports are also
178+
accessible using direct routing, no port filtering rules are set up.
179+
This mode is included for compatibility with legacy default behaviour.
180+
181+
The gateway mode also affects communication between containers that
182+
are connected to different Docker networks on the same host.
183+
- In `nat` and `nat-unprotected` modes, containers in other bridge
184+
networks can only access published ports via the host addresses they
185+
are published to. Direct routing from other networks is not allowed.
186+
- In `routed` mode containers in other networks can use direct
187+
routing to access ports, without going via a host address.
147188

148189
In `routed` mode, a host port in a `-p` or `--publish` port mapping is
149190
not used, and the host address is only used to decide whether to apply
150191
the mapping to IPv4 or IPv6. So, when a mapping only applies to `routed`
151-
mode, only addresses `0.0.0.0` or `::1` are allowed, and a host port
152-
must not be given.
153-
154-
Mapped container ports, in `nat` or `routed` mode, are accessible from
155-
any remote address, if routing is set up in the network, unless the
156-
Docker host's firewall has additional restrictions.
192+
mode, only addresses `0.0.0.0` or `::` should be used, and a host port
193+
should not be given. If a specific address or port is given, it will
194+
have no effect on the published port and a warning message will be
195+
logged.
196+
197+
Mode `isolated` can only be used when the network is also created with
198+
CLI flag `--internal`, or equivalent. An address is normally assigned to the
199+
bridge device in an `internal` network. So, processes on the docker host can
200+
access the network, and containers in the network can access host services
201+
listening on that bridge address (including services listening on "any" host
202+
address, `0.0.0.0` or `::`). No address is assigned to the bridge when the
203+
network is created with gateway mode `isolated`.
157204

158205
#### Example
159206

0 commit comments

Comments
 (0)