Problem statement

Docker 1.12.0 and 1.13.0 introduce new syntaxes for:

• Mount specifications (docker run --mount and docker service create --mount)
• Port specifications (docker service create --port)
• Secret specifications (docker service create --secret)

This raises several questions regarding consistency:

1. What are the guidelines in terms of short syntax ("porcelain") versus long syntax ("plumbing")?
2. How many flags should be exposed: one for porcelain and one for plumbing, or a single one with two possible syntaxes?
3. Where those flags overlap, do they use the same naming scheme for long syntax option names?

Current state

What we can see from the table above is that:

• Some areas have a same flag support the short and long syntax.
• Some areas have overlapping named options, but not necessarily the same short versions.
• Some areas have overlapping named options, but not necessarily the same semantic (to be verified).

Proposal

The proposal is to burn it all homogenize according to well defined guidelines that we can reuse in the future for every feature with the same requirement. What follows is an attempt at defining such guidelines.

All features which require both a rich way to express complex things in a non-ambiguous manner, while preserving a nice "porcelain" syntax for the 80% use case should:

1. Use the same flag for both the short and long syntax.
2. The long syntax should be a comma separated list of arg=value specifications (e.g., arg1=val1,arg2=val2).
3. The short syntax should be a separated list of values (NOTE: separator TBD, although --publish and --volume use : today), which defines positional arguments that map directly to an expanded long term equivalent. For example, given the order arg1, arg2, arg3, the short syntax val1:val2 is equivalent to the long form arg1=val1,arg2=val2. This is inspired by the way Python function invocation syntax deals with optional and keyword-only arguments.
4. Wherever possible, consistency of named arguments in the long form across different features should be enforced, including in any short term aliases that those named arguments can take.

What it means for 1.13.0

If we agree to move forward with this, then we need to review the current set of flags and act accordingly:

• The newly introduced --port flag should likely disappear in favor of --publish, ensuring that the short form maps cleanly to the long form. Remove --port and update --publish for services to support syntaxes #28943
• We know that the -v syntax is likely already too overloaded to map cleanly to the long-syntax equivalent introduced by mount, and we might need to drop support for --mount in run until we can figure this out.
• We need to reconcile named arguments in secrets with those in mounts (especially with regard to the aliases that source supports in mounts).

References

• cli: add --mount to docker run #26825 - Add --mount flag to docker create and docker run
• Secret Management #27794 - Add secret management
• Add support for host mode port PublishMode in services #27917 - Add support for host port PublishMode in services using the --port option in docker service create

Ping @joaofnfernandes @aluzzardi @thaJeztah @mstanleyjones @vieux @dhiltgen @ehazlett @dnephin 🌵