Document syntax for using external host network in Docker Compose with Stack/Swarm

[deahtstroke]

Is this a docs issue?

• [x] My issue is about the documentation content or website

Type of issue

I can't find what I'm looking for

Description

The current Docker documentation notes that network_mode: host is unsupported in Docker Stack/Swarm deployments, which is correct. However, it is still possible to connect services to the host network by referencing the host network as an external network as detailed in this discussion and this one as well:

The approach used in both solutions and in my own solution to a problem I had is:

# Declare a top-level network with an external network named `host`
networks:
   outside:
      external:
         name: "host"

# Assigning it to a service in the compose file
services:
   my-service:
      image: my-image
      networks:
         - outside

This approach works in Swarm mode whilst deploying using Docker Stack but is not clearly documented in the official Compose or Swarm networking docs and the syntax feels a little bit unintuitive and I had to discover through much trial and error and community posts.

Location

https://docs.docker.com/reference/compose-file/networks/

Suggestion

Suggested improvement:

Add a small example or note in the Swarm/Stack or even the Compose-file networking section explaining that the host network can be used by declaring it as an external network with a name of 'host'.

Clarify when this is appropriate and what limitations might apply (e.g. only one replica, port conflicts, etc.).

This would help clarify a valid but undocumented pattern for users needing host-level access (e.g. for monitoring agents, proxies, or low-level network apps).

[deahtstroke]

I'd love to take this on if that's okay. This is my first time contributing to open source, so please let me know if there's anything I should be aware of beyond the usual. I've already read through the contributing guidelines=)

[aevesdocker]

Having dug into this a little bit, i think this is a real edge case and not really the intended use of Swarm. Additionally, as noted in the docs already, Swarm is only compatible with the legacy Compose file v3 and Docker Compose v1 - the docs document the Compose Spec and Docker Compose v2, so any docs contributions on this are not relevant and unsupported, so I'm closing this issue and the corresponding PR by @deahtstroke