RFC: add advanced "csv" syntax for "--net" / "--network"

[thaJeztah]

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;

Name	Type	Corresponds with	Description
name	string	--network	Name of the network to attach to
alias	string[]	--network-alias	Network-scoped alias for the container / service
ip	string	--ip	IPv4 address for the container / service
ip6	string	--ip6	IPv6 address for the container / service
link	string	--link	Container/service-scoped alias for another container/service (t.b.d.)
link-local-ip	string[]	--link-local-ip	Link-local address(es) for the container

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

[mavenugo]

👍 on the idea.

The discussion on task specific options and templating to go with it requires more discussions. There are cases where even such an option may be limiting especially when the task specific option is completely localized to the node where it is being scheduled.

So, in order to keep this proposal manageable , let us try and address the existing limitation and options and accomodate it with the new CSV format.

[yuyi]

LGTM

[stevvooe]

@thaJeztah The proposal looks good.

A few things to watch out for:

1. Templating is mostly done in the worker, whereas as network allocation happens in the orchestrator. Some of the template context may be unavailable.
2. It would be good to be able to support updating aliases without replacing the full network. I am not sure how we can support that in this syntax, but we should consider addition.

👍 👍 👍 🎸

[deadbeef84]

I would love to see the container-alias option, especially together with swarm/stacks. My understanding is that the only DNS name available right now is the service name itself. Also, being able to assign multiple aliases would be awesome, for instance to allow accessing a service on a specific node:

• container-alias={{.Slot}}.{{.Service}}.{{.Node}}
• container-alias={{.Service}}.{{.Node}}

Any chance of this happening?

Edit: I guess there's more than one DNS name, for stacks we have {name}, {stack}_{name} and {stack}_{name}.{slot}.{task}. Are there any other? Also, where are these documented?

[EliSnow]

#33130 provides name and alias through the CSV syntax. Unfortunately it is undocumented.

I would really like to see container-alias with templating support.

[thaJeztah]

Yes, #33130 / docker/cli#62 adds initial options for services; docker/cli#843 is addressing the missing documentation

[thaJeztah]

CLI implementation for docker run / docker create is worked on in docker/cli#317