Merge pull request #4399 from dvdksn/docs/host-gateway

docs: document special host-gateway value for add-host

Author: thaJeztah

docs/reference/commandline/build.md

@@ -458,7 +458,17 @@ You can add other hosts into a container's `/etc/hosts` file by using one or
 more `--add-host` flags. This example adds a static address for a host named
 `docker`:
 
-    $ docker build --add-host=docker:10.180.0.1 .
+```console
+$ docker build --add-host docker:10.180.0.1 .
+```
+
+If you need your build to connect to services running on the host, you can use
+the special `host-gateway` value for `--add-host`. In the following example,
+build containers resolve `host.docker.internal` to the host's gateway IP.
+
+```console
+$ docker build --add-host host.docker.internal:host-gateway .
+```
 
 ### <a name="target"></a> Specifying target build stage (--target)
 

docs/reference/commandline/dockerd.md

@@ -833,6 +833,25 @@ the host.
 For details about how to use this feature, as well as limitations, see
 [Isolate containers with a user namespace](https://docs.docker.com/engine/security/userns-remap/).
 
+### Configure host gateway IP
+
+The Docker daemon supports a special `host-gateway` value for the `--add-host`
+flag for the `docker run` and `docker build` commands. This value resolves to
+the host's gateway IP and lets containers connect to services running on the
+host.
+
+By default, `host-gateway` resolves to the IP address of the default bridge.
+You can configure this to resolve to a different IP using the `--host-gateway-ip`
+flag for the dockerd command line interface, or the `host-gateway-ip` key in
+the daemon configuration file.
+
+```console
+$ dockerd --host-gateway-ip 192.0.2.0
+$ docker run -it --add-host host.docker.internal:host-gateway \
+  busybox ping host.docker.internal 
+PING host.docker.internal (192.0.2.0): 56 data bytes
+```
+
 ### Miscellaneous options
 
 IP masquerading uses address translation to allow containers without a public

docs/reference/commandline/run.md

@@ -760,24 +760,28 @@ PING docker (93.184.216.34): 56 data bytes
 round-trip min/avg/max = 92.209/92.495/93.052 ms
 ```
 
-Sometimes you need to connect to the Docker host from within your
-container. To enable this, pass the Docker host's IP address to
-the container using the `--add-host` flag. To find the host's address,
-use the `ip addr show` command.
+The `--add-host` flag supports a special `host-gateway` value that resolves to
+the internal IP address of the host. This is useful when you want containers to
+connect to services running on the host machine.
 
-The flags you pass to `ip addr show` depend on whether you are
-using IPv4 or IPv6 networking in your containers. Use the following
-flags for IPv4 address retrieval for a network device named `eth0`:
+It's conventional to use `host.docker.internal` as the hostname referring to
+`host-gateway`. Docker Desktop automatically resolves this hostname, see
+[Explore networking features](https://docs.docker.com/desktop/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host).
+
+The following example shows how the special `host-gateway` value works. The
+example runs an HTTP server that serves a file from host to container over the
+`host.docker.internal` hostname, which resolves to the host's internal IP.
 
 ```console
-$ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print $2}' | cut -d / -f 1 | sed -n 1p`
-$ docker run  --add-host=docker:${HOSTIP} --rm -it debian
+$ echo "hello from host!" > ./hello
+$ python3 -m http.server 8000
+Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+$ docker run \
+  --add-host host.docker.internal:host-gateway \
+  curlimages/curl -s host.docker.internal:8000/hello
+hello from host!
 ```
 
-For IPv6 use the `-6` flag instead of the `-4` flag. For other network
-devices, replace `eth0` with the correct device name (for example `docker0`
-for the bridge device).
-
 ### <a name="ulimit"></a> Set ulimits in container (--ulimit)
 
 Since setting `ulimit` settings in a container requires extra privileges not