Note: this design is already partly being discussed on #27638, but creating this issue for tracking, and wider discussion.

docker run and docker service create currently don't support adding a container or service to multiple networks. The reason for this is that there is a number of options that can be set per network (for example, network-scoped aliases through --network-alias, a fixed IP-address on a network through --ip / --ip6).

The current situation severely limits networking options for services, as it's currently not possible to;

• Attach/detach services to a network
• Modify networking configuration for a service (docker service update) after a service is created
• Set network-aliases for services through the CLI (the API supports this, as does docker stack deploy)

The advanced "csv" syntax (as is used for docker service create --mount) solves this limitation by grouping options in a single flag, allowing options to be set per mount. The same can be done for networks.

Proposed change

I want to propose adding the same syntax to --network and solve this limitation. The advanced syntax should support all network-related options that can be set currently on docker run and docker network connect, for example;

docker service create
  --network name=my-network,alias=foo,alias=foo.bar.com,ip=172.30.100.104,ip6=2001:db8::33

Suggested options;

In addition, advanced networking options (as are proposed in #27638) can be passed, for example;

• ipam-opt (options for the IPAM plugin/driver)
• opt (driver-specific options for the network)

Possibly this would also allow options, such as bandwidth limitation per-network for a container/service (see #20794, #27809, #26767, #27846)

To be discussed - per-task/container options

For services, some options can be ambiguous, for example, an alias, or IP-address can apply to a service as a whole, or per task / container. Some thoughts if we want options to be applied to individual tasks;

• provide separate options for attributes that apply to individual containers/tasks (e.g. container-ip, container-alias)
• support templating (container-alias={{.Service}}.{{.Slot}}.foobar)
• support numerators in templating? (container-ip=172.30.100.x) - haven't given this one much thought, perhaps that's an IPAM option.

To be discussed - auto-creation

Do we want the --network flag to create networks if they don't exist, or keep the current behavior, and require the network to be created up front?

Personally, I think requiring a network to exist is a cleaner approach (better separation of concerns).

Related issues;

• [epic] add more options to service create / service update ([epic] add more options to service create / service update #25303)
• [UX] Guidelines for short/long syntax flags ([UX] Guidelines for short/long syntax flags #28527)
• Adding static IP option (--ip and --ip6) for Docker Services (Adding static IP option (--ip and --ip6) for Docker Services #29816, Static/Reserved IP addresses for swarm services #24170)
• --network-alias option missing on docker service create --network-alias option missing on docker service create (as well as corresponding options on docker service update) #24787
• multiple networks on docker run (Is it possible to bind a container to multi networks? #17750, Allow containers to be connected to networks before it is started #17289, Add support multiple network mode on docker create/run #17796)
• Add "--network-opt" option as a way to pass arbitrary options to network drivers (Add "--network-opt" option as a way to pass arbitrary options to network drivers #27638)

ping @docker/core-engine-maintainers @docker/core-libnetwork-maintainers