The design was reviewed under moby/swarmkit#1645 . moving to code-review.

I put it back to design, I'm a bit confused; we now have three flags (6 if we look at docker service update) to expose a port.

I can see that being very confusing for users, and wonder if we can find a better approach

@thaJeztah ok. do you have any suggestions ? Lets start from there.

Current options in --publish on docker run (not service create) to see what
things we may expect

Some feature requests;

• named ports (Feature request: add names to exposed ports #21322)
• Assigning service published ports to IP (Assigning service published ports to IP #26696)
• restrict port access to specific IP-addresses (Unnable to filter bound ports to only some source IPs #14105)
• Support multiple network interfaces in Swarm (Support multiple network interfaces in Swarm #24317)
• swarm mode services: no ability to partition ingress network / constrain --publish to certain nodes only (swarm mode services: no ability to partition ingress network / constrain --publish to certain nodes only #25257)
• Swarm/service feature request: only publish ports on hosts meeting constraints (Swarm/service feature request: only publish ports on hosts meeting constraints #28105)

So, my concerns are that (first of all) we tried the -p / --publish flag to be consistent with docker run so that it's easier for people to find themselve "at home" when using docker service create. By "deprecating" / renaming the --publish flag, that's going to be confusing.

Also, more features will be added in future, and we end up with even more flags. I'm not sure if the current -p syntax will make that easy to use. My initial thought was to use a syntax similar to --mount for publishing, as it's extendable, and non ambiguous (albeit verbose), something like

--new-publish-flag target-port=80,published-port=8080,mode=host

In future we can add "porcelain" flags for easier use, if requested.

@thaJeztah I like this idea which helps with the issue of "grouping" related flags together at the CLI level (which is ofcourse already possible in engine-API & protobuf structures). I wish we make this a consistent pattern and introduce such a "grouping" concept that can be used for more such use-cases.

LGTM

@icecrime @cpuguy83 @aluzzardi can you please add your comments / opinion on the UX as proposed by this PR vs @thaJeztah's proposal ?

Given the code-freeze is round the corner, it will be great to have an answer soon so that we can also do integration-testing with WS2016 as well.

The --mount style syntax is ok for me.

Sebastiaan's proposal makes sense to me. Yes it's verbose, but it's maybe better to get the fundamentals right (as in: non-ambiguous, and future-proof).

Same as @cpuguy83 and @icecrime, I think it makes sense 👼

thanks @icecrime @cpuguy83 @vdemeester.

@thaJeztah @mrjana shall we reuse --publish flag and overload it with both the formats ?
I think the text parsing is mutually exclusive and we already have sane defaults for the older format.

For example,

-p 80 -> -p target-port=80,mode=ingress
-p 1234:80 -> -p target-port=80,published-port=1234,mode=ingress

etc...

If we can do it "technically", I am not against reusing the flag

One thing we should look at is how "removing" a published port will work in docker service update (see also #25860). Probably just document that the "target" port needs to be used (and protocol?)

ping @dnephin. Can you please chime in on the port publication format that is being discussed here? This will override the micro format specification that has been used so far.

Oh, I see the proposal for having the new flags use a different format. I think that makes sense. We need a way to expose more information, and following the mount syntax sounds correct.

I think we should deprecate the old --publush flag at the same time. Deprecating it will hide it, but still allow it to be used for now.

Rebased

Linking #28463 (comment) which should be documented as part of the documentation changes for this PR

@mavenugo @thaJeztah I use this command it works.
docker service create --port mode=host,target=80,published=8080,protocol=tcp nginx:1.9
How many mode can I use?
I want to use my own bridge network "mynet", how can I specify it within service?

@rootsongjc no, currently only "host" or "ingress".

Be aware that after UX reviews, the --port and --publish flags will be combined in 1.13 GA, see the discussion on #28527 (comment) and implemented in #28943

Here was the original UX proposal:

moby/swarmkit#1645 (comment)

For mount, the syntax complexity made sense due the use of volume options and arbitrary filesystem paths. Ports are much, much simpler and forcing people to navigate this morass for simple port definition isn't great.

I am not sure I understood the main impetus behind using the csv-style syntax.

Oh no, this seems to make things more complex.

does this mean there is no straight --publish [port:]port syntax defaulting to the ingress network any more? Is there any documentation on how this affects DNS resolution and any differences between networking for the two modes. I guess this helps to fix external connections to services like kafka, and removes a potential routing hop if you are using nginx.

Is that the rational behind this?

I also dont see the documentation for this in https://github.com/docker/docker/blob/master/docs/reference/commandline/service_create.md
what was the syntax you eventually went with?

@Richard-Mathie no worries, the "simple" syntax will stay as well; see #28943, and the discussion on #28527

Documentation is added here; https://github.com/docker/docker.github.io/blob/2248f78dabc2b0e5092fd550ad0aa3c15d41e2b0/engine/swarm/services.md#publish-ports, but we should add it to the command line reference as well