From a82dff55421c251354d52251ae7e35fbcb04b633 Mon Sep 17 00:00:00 2001 From: Cesar Talledo Date: Wed, 26 Feb 2025 02:14:14 -0800 Subject: [PATCH 1/3] kubernetes: add section comparing kubeadm and kind provisioners (#22104) ## Description In the Kubernetes docs, add a section comparing the `kubeadm` and `kind` provisioners. Why? because the existing text was insufficient and did not provide a proper comparison to our users. ## Reviews - [ ] Technical review - [X] Editorial review - [ ] Product review --------- Signed-off-by: Cesar Talledo Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> --- .../manuals/desktop/features/kubernetes.md | 36 +++++++++++++++++-- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/content/manuals/desktop/features/kubernetes.md b/content/manuals/desktop/features/kubernetes.md index 52f379593462..ffc45ea71eb4 100644 --- a/content/manuals/desktop/features/kubernetes.md +++ b/content/manuals/desktop/features/kubernetes.md @@ -34,10 +34,10 @@ Turning the Kubernetes server on or off in Docker Desktop does not affect your o 1. Open the Docker Desktop Dashboard and navigate to **Settings**. 2. Select the **Kubernetes** tab. 3. Toggle on **Enable Kubernetes**. -4. Choose your cluster provisioning method. You can choose either **Kubeadm** or **kind** if you are signed in and are using Docker Desktop version 4.38 or later. +4. Choose your [cluster provisioning method](#cluster-provisioning-method). +5. Select **Apply & Restart** to save the settings. - If you select **kind** you can also choose the Kubernetes version and the number of nodes. -5. Select **Apply & Restart** to save the settings. This sets up the images required to run the Kubernetes server as containers, and installs the `kubectl` command-line tool on your system at `/usr/local/bin/kubectl` (Mac) or `C:\Program Files\Docker\Docker\Resources\bin\kubectl.exe` (Windows). +This sets up the images required to run the Kubernetes server as containers, and installs the `kubectl` command-line tool on your system at `/usr/local/bin/kubectl` (Mac) or `C:\Program Files\Docker\Docker\Resources\bin\kubectl.exe` (Windows). > [!NOTE] > @@ -51,6 +51,36 @@ You can check which version of Kubernetes you're on with: $ kubectl version ``` +### Cluster provisioning method + +Docker Desktop Kubernetes can be provisioned with either the `kubeadm` or `kind` +provisioners. + +`kubeadm` is the older provisioner. It supports a single-node cluster, you can't select the kubernetes +version, it's slower to provision than `kind`, and it's not supported by [Enhanced Container Isolation](/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/index.md) (ECI), +meaning that if ECI is enabled the cluster works but it's not protected by ECI. + +`kind` is the newer provisioner, and it's available if you are signed in and are +using Docker Desktop version 4.38 or later. It supports multi-node clusters (for +a more realistic Kubernetes setup), you can choose the Kubernetes version, it's +faster to provision than `kubeadm`, and it's supported by ECI (i.e., when ECI is +enabled, the Kubernetes cluster runs in unprivileged Docker containers, thus +making it more secure). Note however that `kind` requires that Docker Desktop be +configured to use the [containerd image store](containerd.md) (the default image +store in Docker Desktop 4.34 and later). + +The following table summarizes this comparison. + +| Feature | `kubeadm` | `kind` | +| :------ | :-----: | :--: | +| Availability | Docker Desktop 4.0+ | Docker Desktop 4.38+ (requires sign in) | +| Multi-node cluster support | No | Yes | +| Kubernetes version selector | No | Yes | +| Speed to provision | ~1 min | ~30 seconds | +| Supported by ECI | No | Yes | +| Works with containerd image store | Yes | Yes | +| Works with Docker image store | Yes | No | + ### Additional settings #### Kubernetes dashboard From 426401185697f5754d225ed61322658780f8cd4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Gronowski?= Date: Wed, 26 Feb 2025 14:08:49 +0000 Subject: [PATCH 2/3] engine: 28.0.1 release notes (#22108) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description ## Related issues or tickets ## Reviews - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: Paweł Gronowski Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> --- content/manuals/engine/release-notes/28.md | 45 +++++++++++++++++++ data/engine-cli/docker_container_restart.yaml | 2 +- data/engine-cli/docker_container_run.yaml | 20 +++++++++ data/engine-cli/docker_network_ls.yaml | 3 ++ data/engine-cli/docker_swarm_join-token.yaml | 6 ++- data/engine-cli/docker_swarm_join.yaml | 15 ++++--- data/engine-cli/docker_swarm_unlock-key.yaml | 6 ++- hugo.yaml | 4 +- 8 files changed, 89 insertions(+), 12 deletions(-) diff --git a/content/manuals/engine/release-notes/28.md b/content/manuals/engine/release-notes/28.md index 57f44ba1563e..bcd3db7d9dac 100644 --- a/content/manuals/engine/release-notes/28.md +++ b/content/manuals/engine/release-notes/28.md @@ -22,6 +22,51 @@ For more information about: - Deprecated and removed features, see [Deprecated Engine Features](../deprecated.md). - Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history.md). +## 28.0.1 + +{{< release-date date="2025-02-26" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 28.0.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.0.1) +- [moby/moby, 28.0.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.0.1) + +### Networking + +- Remove dependency on kernel modules `ip_set`, `ip_set_hash_net` and `netfilter_xt_set`. + * The dependency was introduced in release 28.0.0 but proved too disruptive. The iptables rules using these modules have been replaced. [moby/moby#49530](https://github.com/moby/moby/pull/49530) +- Allow daemon startup on a host with IPv6 disabled without requiring `--ip6tables=false`. [moby/moby#49525](https://github.com/moby/moby/pull/49525) +- Fix a bug that was causing containers with `--restart=always` and a published port already in use to restart in a tight loop. [moby/moby#49507](https://github.com/moby/moby/pull/49507) +- Fix an issue with Swarm ingress, caused by incorrect ordering of iptables rules. [moby/moby#49538](https://github.com/moby/moby/pull/49538) +- Fix creation of a swarm-scoped network from a `--config-only` network. [moby/moby#49521](https://github.com/moby/moby/pull/49521) +- Fix `docker network inspect` reporting an IPv6 gateway with CIDR suffix for a newly created network with no specific IPAM config, until a daemon restart. [moby/moby#49520](https://github.com/moby/moby/pull/49520) +- Improve the error reported when kernel modules `ip_set`, `ip_set_hash_net` and `netilter_xt_set` are not available. [moby/moby#49524](https://github.com/moby/moby/pull/49524) +- Move most of Docker's iptables rules out of the filter-FORWARD chain, so that other applications are free to append rules that must follow Docker's rules. [moby/moby#49518](https://github.com/moby/moby/pull/49518) +- Update `--help` output and man page lo state which options only apply to the default bridge network. [moby/moby#49522](https://github.com/moby/moby/pull/49522) + + +### Bug fixes and enhancements + +- Fix `docker context create` always returning an error when using the `"skip-tls-verify"` option. [docker/cli#5850](https://github.com/docker/cli/pull/5850) +- Fix shell completion suggesting IDs instead of names for services and nodes. [docker/cli#5848](https://github.com/docker/cli/pull/5848) +- Fix unintentionally printing exit status to standard error output when `docker exec/run` returns a non-zero status. [docker/cli#5854](https://github.com/docker/cli/pull/5854) +- Fix regression `protocol "tcp" is not supported by the RootlessKit port driver "slirp4netns"`. [moby/moby#49514](https://github.com/moby/moby/pull/49514) +- containerd image store: Fix `docker inspect` not being able to show multi-platform images with missing layers for all platforms. [moby/moby#49533](https://github.com/moby/moby/pull/49533) +- containerd image store: Fix `docker images --tree` reporting wrong content size. [moby/moby#49535](https://github.com/moby/moby/pull/49535) +- Fix compilation on i386 [moby/moby#49526](https://github.com/moby/moby/pull/49526) + +### Packaging updates + +- Update `github.com/go-jose/go-jose/v4` to v4.0.5 to address [GHSA-c6gw-w398-hv78](https://github.com/go-jose/go-jose/security/advisories/GHSA-c6gw-w398-hv78) / [CVE-2025-27144](https://www.cve.org/CVERecord?id=CVE-2025-27144). [docker/cli#5867](https://github.com/docker/cli/pull/5867) +- Update Buildx to [v0.21.1](https://github.com/docker/buildx/releases/tag/v0.21.1). [docker/docker-ce-packaging#1167](https://github.com/docker/docker-ce-packaging/pull/1167) +- Update Compose to [v2.33.1](https://github.com/docker/compose/releases/tag/v2.33.1). [docker/docker-ce-packaging#1168](https://github.com/docker/docker-ce-packaging/pull/1168) + +### API + +- containerd image store: Fix `GET /images/json?manifests=1` not filling `Manifests` for index-only images [moby/moby#49533](https://github.com/moby/moby/pull/49533) +- containerd image store: Fix `GET /images/json and /images//json` `Size.Content` field including the size of content that's not available locally [moby/moby#49535](https://github.com/moby/moby/pull/49535) + + ## 28.0.0 {{< release-date date="2025-02-19" >}} diff --git a/data/engine-cli/docker_container_restart.yaml b/data/engine-cli/docker_container_restart.yaml index dcb858d7ff1f..ab621abde102 100644 --- a/data/engine-cli/docker_container_restart.yaml +++ b/data/engine-cli/docker_container_restart.yaml @@ -75,7 +75,7 @@ examples: |- ### Stop container with timeout (-t, --timeout) {#timeout} The `--timeout` flag sets the number of seconds to wait for the container - to stop after sending the pre-defined (see [`--signal`]{#signal)) system call signal. + to stop after sending the pre-defined (see [`--signal`](#signal)) system call signal. If the container does not exit after the timeout elapses, it's forcibly killed with a `SIGKILL` signal. diff --git a/data/engine-cli/docker_container_run.yaml b/data/engine-cli/docker_container_run.yaml index 05e8cdf22610..913e4978f3d9 100644 --- a/data/engine-cli/docker_container_run.yaml +++ b/data/engine-cli/docker_container_run.yaml @@ -2318,6 +2318,26 @@ examples: |- > $ docker run -it --ulimit as=1024 fedora /bin/bash > ``` + #### Supported options for `--ulimit`: + + | Option | Description | + |:-------------|:----------------------------------------------------------| + | `core` | Maximum size of core files created (`RLIMIT_CORE`) | + | `cpu` | CPU time limit in seconds (`RLIMIT_CPU`) | + | `data` | Maximum data segment size (`RLIMIT_DATA`) | + | `fsize` | Maximum file size (`RLIMIT_FSIZE`) | + | `locks` | Maximum number of file locks (`RLIMIT_LOCKS`) | + | `memlock` | Maximum locked-in-memory address space (`RLIMIT_MEMLOCK`) | + | `msgqueue` | Maximum bytes in POSIX message queues (`RLIMIT_MSGQUEUE`) | + | `nice` | Maximum nice priority adjustment (`RLIMIT_NICE`) | + | `nofile` | Maximum number of open file descriptors (`RLIMIT_NOFILE`) | + | `nproc` | Maximum number of processes available (`RLIMIT_NPROC`) | + | `rss` | Maximum resident set size (`RLIMIT_RSS`) | + | `rtprio` | Maximum real-time scheduling priority (`RLIMIT_RTPRIO`) | + | `rttime` | Maximum real-time execution time (`RLIMIT_RTTIME`) | + | `sigpending` | Maximum number of pending signals (`RLIMIT_SIGPENDING`) | + | `stack` | Maximum stack size (`RLIMIT_STACK`) | + Docker sends the values to the appropriate OS `syscall` and doesn't perform any byte conversion. Take this into account when setting the values. diff --git a/data/engine-cli/docker_network_ls.yaml b/data/engine-cli/docker_network_ls.yaml index d6ba1e68bf35..1b3b702d092e 100644 --- a/data/engine-cli/docker_network_ls.yaml +++ b/data/engine-cli/docker_network_ls.yaml @@ -39,6 +39,7 @@ options: value_type: bool default_value: "false" description: Do not truncate the output + details_url: '#no-trunc' deprecated: false hidden: false experimental: false @@ -79,6 +80,8 @@ examples: |- 78b03ee04fc4 multi-host overlay swarm ``` + ### List networks without truncating the ID column (--no-trun) {#no-trunc} + Use the `--no-trunc` option to display the full network id: ```console diff --git a/data/engine-cli/docker_swarm_join-token.yaml b/data/engine-cli/docker_swarm_join-token.yaml index ccab60a619f0..69a69bb5cab2 100644 --- a/data/engine-cli/docker_swarm_join-token.yaml +++ b/data/engine-cli/docker_swarm_join-token.yaml @@ -21,6 +21,7 @@ options: value_type: bool default_value: "false" description: Only display token + details_url: '#quiet' deprecated: false hidden: false experimental: false @@ -31,6 +32,7 @@ options: value_type: bool default_value: "false" description: Rotate join token + details_url: '#rotate' deprecated: false hidden: false experimental: false @@ -97,7 +99,7 @@ examples: |- SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7mel7t ``` - ### `--rotate` + ### `--rotate` {#rotate} Because tokens allow new nodes to join the swarm, you should keep them secret. Be particularly careful with manager tokens since they allow new manager nodes @@ -116,7 +118,7 @@ examples: |- using the old token. Rotation does not affect existing nodes in the swarm because the join token is only used for authorizing new nodes joining the swarm. - ### `--quiet` + ### `--quiet` {#quiet} Only print the token. Do not print a complete command for joining. deprecated: false diff --git a/data/engine-cli/docker_swarm_join.yaml b/data/engine-cli/docker_swarm_join.yaml index ee2b43ac3739..cab96ffe3db1 100644 --- a/data/engine-cli/docker_swarm_join.yaml +++ b/data/engine-cli/docker_swarm_join.yaml @@ -11,6 +11,7 @@ options: - option: advertise-addr value_type: string description: 'Advertised address (format: `[:port]`)' + details_url: '#advertise-addr' deprecated: false hidden: false experimental: false @@ -21,6 +22,7 @@ options: value_type: string default_value: active description: Availability of the node (`active`, `pause`, `drain`) + details_url: '#availability' deprecated: false hidden: false experimental: false @@ -31,6 +33,7 @@ options: value_type: string description: | Address or interface to use for data path traffic (format: ``) + details_url: '#data-path-addr' deprecated: false hidden: false min_api_version: "1.31" @@ -42,6 +45,7 @@ options: value_type: node-addr default_value: 0.0.0.0:2377 description: 'Listen address (format: `[:port]`)' + details_url: '#listen-addr' deprecated: false hidden: false experimental: false @@ -51,6 +55,7 @@ options: - option: token value_type: string description: Token for entry into the swarm + details_url: '#token' deprecated: false hidden: false experimental: false @@ -102,7 +107,7 @@ examples: |- dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader ``` - ### `--listen-addr value` + ### `--listen-addr value` {#listen-addr} If the node is a manager, it will listen for inbound swarm manager traffic on this address. The default is to listen on 0.0.0.0:2377. It is also possible to specify a @@ -113,7 +118,7 @@ examples: |- This flag is generally not necessary when joining an existing swarm. - ### `--advertise-addr value` + ### `--advertise-addr value` {#advertise-addr} This flag specifies the address that will be advertised to other members of the swarm for API access. If unspecified, Docker will check if the system has a @@ -133,7 +138,7 @@ examples: |- ensure the node advertises its IP address and not the IP address of the load balancer. - ### `--data-path-addr` + ### `--data-path-addr` {#data-path-addr} This flag specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. @@ -142,11 +147,11 @@ examples: |- If unspecified, Docker will use the same IP address or interface that is used for the advertise address. - ### `--token string` + ### `--token string` {#token} Secret value required for nodes to join the swarm - ### `--availability` + ### `--availability` {#availability} This flag specifies the availability of the node at the time the node joins a master. Possible availability values are `active`, `pause`, or `drain`. diff --git a/data/engine-cli/docker_swarm_unlock-key.yaml b/data/engine-cli/docker_swarm_unlock-key.yaml index d7d8fb202036..93ab3496fa47 100644 --- a/data/engine-cli/docker_swarm_unlock-key.yaml +++ b/data/engine-cli/docker_swarm_unlock-key.yaml @@ -22,6 +22,7 @@ options: value_type: bool default_value: "false" description: Only display token + details_url: '#quiet' deprecated: false hidden: false experimental: false @@ -32,6 +33,7 @@ options: value_type: bool default_value: "false" description: Rotate unlock key + details_url: '#rotate' deprecated: false hidden: false experimental: false @@ -87,12 +89,12 @@ examples: |- SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8 ``` - ### `--rotate` + ### `--rotate` {#rotate} This flag rotates the unlock key, replacing it with a new randomly-generated key. The old unlock key will no longer be accepted. - ### `--quiet` + ### `--quiet` {#quiet} Only print the unlock key, without instructions. deprecated: false diff --git a/hugo.yaml b/hugo.yaml index 64ae1a4bbd59..9d4bf29e46df 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -113,10 +113,10 @@ params: # Latest version of the Docker Engine API latest_engine_api_version: "1.48" # Latest version of Docker Engine - docker_ce_version: "28.0.0" + docker_ce_version: "28.0.1" # Previous version of the Docker Engine # (Used to show e.g., "latest" and "latest"-1 in engine install examples - docker_ce_version_prev: "27.5.1" + docker_ce_version_prev: "28.0.0" # Latest Docker Compose version compose_version: "v2.33.1" # Latest BuildKit version From 2090e5bcbbdf38fa1004caa0488e555497ae8a39 Mon Sep 17 00:00:00 2001 From: Rob Murray <148866618+robmry@users.noreply.github.com> Date: Wed, 26 Feb 2025 14:10:18 +0000 Subject: [PATCH 3/3] Updates for moby 28.0.1 (#22086) ## Description - Describe new iptables chain `DOCKER-FORWARD`, which splits Docker's rules out of the main `FORWARD` chain where they were being antisocial - related to https://github.com/moby/moby/pull/49518 - Update notes about IP Forwarding and the default DROP policy - Only engine < 28.0.0 allows remote access to ports published to the localhost address ## Related issues or tickets ## Reviews - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: Rob Murray --- .../network/packet-filtering-firewalls.md | 49 ++++++++++++++----- 1 file changed, 38 insertions(+), 11 deletions(-) diff --git a/content/manuals/engine/network/packet-filtering-firewalls.md b/content/manuals/engine/network/packet-filtering-firewalls.md index 9e15276a38a5..2ca6cea12a1d 100644 --- a/content/manuals/engine/network/packet-filtering-firewalls.md +++ b/content/manuals/engine/network/packet-filtering-firewalls.md @@ -32,17 +32,22 @@ following custom `iptables` chains: * `DOCKER-USER` * A placeholder for user-defined rules that will be processed before rules - in the `DOCKER` chain. + in the `DOCKER-FORWARD` and `DOCKER` chains. +* `DOCKER-FORWARD` + * The first stage of processing for Docker's networks. Rules that pass packets + that are not related to established connections to the other Docker chains, + as well as rules to accept packets that are part of established connections. * `DOCKER` * Rules that determine whether a packet that is not part of an established connection should be accepted, based on the port forwarding configuration of running containers. * `DOCKER-ISOLATION-STAGE-1` and `DOCKER-ISOLATION-STAGE-2` * Rules to isolate Docker networks from each other. +* `DOCKER-INGRESS` + * Rules related to Swarm networking. -In the `FORWARD` chain, Docker adds rules that pass packets that are not related -to established connections to these custom chains, as well as rules to accept -packets that are part of established connections. +In the `FORWARD` chain, Docker adds rules that unconditionally jump to the +`DOCKER-USER`, `DOCKER-FORWARD` and `DOCKER-INGRESS` chains. In the `nat` table, Docker creates chain `DOCKER` and adds rules to implement masquerading and port-mapping. @@ -53,6 +58,8 @@ Packets that get accepted or rejected by rules in these custom chains will not be seen by user-defined rules appended to the `FORWARD` chain. So, to add additional rules to filter these packets, use the `DOCKER-USER` chain. +Rules appended to the `FORWARD` chain will be processed after Docker's rules. + ### Match the original IP and ports for requests When packets arrive to the `DOCKER-USER` chain, they have already passed through @@ -261,9 +268,9 @@ configure the daemon to use the loopback address (`127.0.0.1`) instead. > [!WARNING] > -> Hosts within the same L2 segment (for example, hosts connected to the same -> network switch) can reach ports published to localhost. -> For more information, see +> In releases older than 28.0.0, hosts within the same L2 segment (for example, +> hosts connected to the same network switch) can reach ports published to +> localhost. For more information, see > [moby/moby#45610](https://github.com/moby/moby/issues/45610) To configure this setting for user-defined bridge networks, use @@ -301,16 +308,36 @@ Alternatively, you can use the `dockerd --ip` flag when starting the daemon. ## Docker on a router -Docker sets the policy for the `FORWARD` chain to `DROP`. This will prevent -your Docker host from acting as a router. +On Linux, Docker needs "IP Forwarding" enabled on the host. So, it enables +the `sysctl` settings `net.ipv4.ip_forward` and `net.ipv6.conf.all.forwarding` +it they are not already enabled when it starts. When it does that, it also +sets the policy of the iptables `FORWARD` chain to `DROP`. + +If Docker sets the policy for the `FORWARD` chain to `DROP`. This will prevent +your Docker host from acting as a router, it is the recommended setting when +IP Forwarding is enabled. -If you want your system to function as a router, you must add explicit -`ACCEPT` rules to the `DOCKER-USER` chain. For example: +To stop Docker from setting the `FORWARD` chain's policy to `DROP`, include +`"ip-forward-no-drop": true` in `/etc/docker/daemon.json`, or add option +`--ip-forward-no-drop` to the `dockerd` command line. + +Alternatively, you may add `ACCEPT` rules to the `DOCKER-USER` chain for the +packets you want to forward. For example: ```console $ iptables -I DOCKER-USER -i src_if -o dst_if -j ACCEPT ``` +> [!WARNING] +> +> In releases older than 28.0.0, Docker always set the default policy of the +> IPv6 `FORWARD` chain to `DROP`. In release 28.0.0 and newer, it will only +> set that policy if it enables IPv6 forwarding itself. This has always been +> the behaviour for IPv4 forwarding. +> +> If IPv6 forwarding is enabled on your host before Docker starts, check your +> host's configuration to make sure it is still secure. + ## Prevent Docker from manipulating iptables It is possible to set the `iptables` or `ip6tables` keys to `false` in