From a0fde8b83ff6084e4b79d2d327dc00a185d48f5a Mon Sep 17 00:00:00 2001 From: Brennan Kinney <5098581+polarathene@users.noreply.github.com> Date: Fri, 21 Jul 2023 09:05:19 +1200 Subject: [PATCH] docs: IPv6 config examples with content tabs (#3436) For added clarity, a user requested we document the example config snippets instead of only linking external references to them. Revised section and adjusted to presenting via the content tabs feature. --- docs/content/config/advanced/ipv6.md | 112 +++++++++++++++++++++------ 1 file changed, 88 insertions(+), 24 deletions(-) diff --git a/docs/content/config/advanced/ipv6.md b/docs/content/config/advanced/ipv6.md index 2afd1d7d..4a45d168 100644 --- a/docs/content/config/advanced/ipv6.md +++ b/docs/content/config/advanced/ipv6.md @@ -64,34 +64,96 @@ Enable `ip6tables` support so that Docker will manage IPv6 networking rules as w Now restart the daemon if it's running: `systemctl restart docker`. -Next, configure a network for your container with any of these: +Next, configure a network with an IPv6 subnet for your container with any of these examples: -- [User-defined networks via `docker network create` or `compose.yaml`][docker-docs-ipv6-create-custom] -- [Default docker bridge][docker-docs-ipv6-create-default] (_docker CLI only, not helpful for `compose.yaml`_) -- [Default network for a `compose.yaml`][ipv6-config-example] (_`/etc/docker/daemon.json` settings for default bridge do not apply, instead override the generated `default` network_) +???+ example "Create an IPv6 ULA subnet" + + ??? info "About these examples" + + These examples are focused on a [IPv6 ULA subnet][wikipedia-ipv6-ula] which is suitable for most users as described in the next section. + + - You may prefer a subnet size smaller than `/64` (eg: `/112`, which still provides over 65k IPv6 addresses), especially if instead configuring for an IPv6 GUA subnet. + - The network will also implicitly be assigned an IPv4 subnet (_from the Docker daemon config `default-address-pools`_). + + === "User-defined Network" + + The preferred approach is with [user-defined networks][docker-docs-ipv6-create-custom] via `compose.yaml` (recommended) or CLI with `docker network create`: + + === "Compose" + + Create the network in `compose.yaml` and attach a service to it: + + ```yaml title="compose.yaml" + services: + mailserver: + networks: + - dms-ipv6 + + networks: + dms-ipv6: + enable_ipv6: true + subnet: fd00:cafe:face:feed::/64 + ``` + + ??? tip "Override the implicit `default` network" + + You can optionally avoid the service assignment by [overriding the `default` user-defined network that Docker Compose generates](docker-docs-network-compose-default). Just replace `dms-ipv6` with `default`. + + The Docker Compose `default` bridge is not affected by settings for the default `bridge` (aka `docker0`) in `/etc/docker/daemon.json`. + + ??? tip "Using the network outside of this `compose.yaml`" + + To reference this network externally (_from other compose files or `docker run`_), assign the [networks `name` key in `compose.yaml`][docker-docs-network-external]. + + === "CLI" + + Create the network via a CLI command (_which can then be used with `docker run --network dms-ipv6`_): + + ```bash + docker network create --ipv6 --subnet fd00:cafe:face:feed::/64 dms-ipv6 + ``` + + Optionally reference it from one or more `compose.yaml` files: + + ```yaml title="compose.yaml" + services: + mailserver: + networks: + - dms-ipv6 + + networks: + dms-ipv6: + external: true + ``` + + === "Default Bridge (daemon)" + + !!! warning "This approach is discouraged" + + The [`bridge` network is considered legacy][docker-docs-network-bridge-legacy]. + + Add these two extra IPv6 settings to your daemon config. They only apply to the [default `bridge` docker network][docker-docs-ipv6-create-default] aka `docker0` (_which containers are attached to by default when using `docker run`_). + + ```json title="/etc/docker/daemon.json" + { + "ipv6": true, + "fixed-cidr-v6": "fd00:cafe:face:feed::/64", + } + ``` + + Compose projects can also use this network via `network_mode`: + + ```yaml title="compose.yaml" + services: + mailserver: + network_mode: bridge + ``` !!! danger "Do not use `2001:db8:1::/64` for your private subnet" - The `2001:db8` address prefix is [reserved for documentation][wikipedia-ipv6-reserved]. Avoid using a subnet with this prefix. + The `2001:db8` address prefix is [reserved for documentation][wikipedia-ipv6-reserved]. Avoid creating a subnet with this prefix. -!!! example "User-defined IPv6 ULA subnet" - - - Either of these should work well. You can use a smaller subnet size like `/112` if you prefer. - - The network will also include an IPv4 subnet assigned implicitly. - - ```bash - # CLI - docker network create --ipv6 --subnet fd00:cafe:face:feed::/64 dms-ipv6 - ``` - - ```yaml - # compose.yaml - networks: - # Overrides the `default` compose generated network, avoids needing to attach to each service: - default: - enable_ipv6: true - subnet: fd00:cafe:face:feed::/64 - ``` + Presently this is used in examples for Dockers IPv6 docs as a placeholder, while mixed in with private IPv4 addresses which can be misleading. ### Configuring an IPv6 subnet @@ -132,8 +194,10 @@ curl --max-time 5 http://[2001:db8::1]:80 [docker-docs-ipv6-create-custom]: https://docs.docker.com/config/daemon/ipv6/#create-an-ipv6-network [docker-docs-ipv6-create-default]: https://docs.docker.com/config/daemon/ipv6/#use-ipv6-for-the-default-bridge-network [docker-docs-ipv6-supernets]: https://docs.docker.com/config/daemon/ipv6/#dynamic-ipv6-subnet-allocation +[docker-docs-network-external]: https://docs.docker.com/compose/compose-file/06-networks/#name +[docker-docs-network-compose-default]: https://docs.docker.com/compose/networking/#configure-the-default-network +[docker-docs-network-bridge-legacy]: https://docs.docker.com/network/drivers/bridge/#use-the-default-bridge-network -[ipv6-config-example]: https://github.com/nginx-proxy/nginx-proxy/issues/133#issuecomment-1368745843 [wikipedia-ipv6-reserved]: https://en.wikipedia.org/wiki/IPv6_address#Documentation [wikipedia-ipv4-private]: https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses [wikipedia-ipv6-ula]: https://en.wikipedia.org/wiki/Unique_local_address