Proposal: Enhance Experimental Networking and Services UI

[dave-tucker]

• Add --net=NETWORK where NETWORK is created via docker network create
• Update --publish-service to use NETWORK:NAME where NETWORK is the namespace under which to publish and NAME is the name of the service

Example

docker network create mynetwork
# publish a service
docker run -itd --publish-service=mynetwork:web nginx
# publish a service (explicit network - it's optional but not required)
docker run -itd --net=mynetwork --publish-service=mynetwork:web
# consume a service only
docker run -itd --net=mynetwork busybox

Failure Cases

# publishing a service on a network to which you don't belong
$ docker run -itd --net=not-mynetwork --publish-service=mynetwork:foo nginx
ERROR: You are not a member of the network "mynetwork"

# attempting to use null values in publish service to join a network, but don't publish a service
$ docker run -itd --publish-service=mynetwork: 
ERROR: You have not provided a service name. If you would like to join a network without publishing a service, please use the --net flag

These changes are motivated by docker/compose#1676 and designed to accomplish the following use cases

We have deliberately ignored attachment to multiple networks at this time as there are concerns about how this is going to be implemented.

Related to: #14143

Developed and discussed with @monadic @bboreham @squaremo @aanand @bfirsh @lxpollitt

[cpuguy83]

So we are assuming that networks can communicate with each other since you can publish a service to a different network?

[dave-tucker]

No you can only publish a service on a network that you are attached to

[cpuguy83]

Oh I see, specifying the network name on --publish-service means to join that nework. I assume --net=<network1>--publish-service=:` would be throw an error?

[shettyg]

docker run -itd --net=frontend --publish-service=frontend:web

Something is wonky in the above command. Does the above create 2 network interfaces attaches to the same network? If not, how do you attach 2 networks to a container?

[dave-tucker]

@cpuguy83 yep, --publish-service=NETWORK:NAME = join me to NETWORK and create a service called NAME. We don't error out on --net=NETWORK --publish-service=NETWORK:NAME providing that you are joining the same network as you are publishing a service on.... It's purely the explicit form of the earlier command.

We would error out on --publish-service=:, as you can just use --net to the same affect - join a network but do not publish a service.

@shettyg per the explanation above, in this case the --net is redundant, it's just here to be explicit and doesn't create a second interface.

Attaching a container to multiple networks is something that we (those in the PR above) decided to defer to tackle later as there are some complexities in the implementation that we aren't quite happy with.

I'm going to set up a networking working group call where we can discuss these kind of things - I'll add details to the libnetwork wiki soon - and would love it if you could join too.

[lxpollitt]

+1 for this proposal from me.

[erikh]

+1

[tomdee]

+1

[ibuildthecloud]

-1

I'm sorry guys. I really am. But there is something still incomplete in my mind. The mere presence of the term "service" means we have a incomplete thought. Those asking for "networks" and those asking for "services" are having two different conversations. We need to separate concerns.

[ibuildthecloud]

I'll do my best to add something productive to this conversation, but still working on a complete thought.

[monadic]

would be good to clarify failure cases (per @shettyg comment above)

[lxpollitt]

@dave-tucker I've just realized the example you gave at the top of this PR may confuse people because of the "frontend" and "backend" network name choices. Some may infer from that they various different network-to-network and cross-network-service-discovery behaviors - which as I understand it are not supported in this initial proposal. Might be better just to replace with "mynetwork" or similar?

[bboreham]

+1

[dave-tucker]

@lxpollitt done.

@ibuildthecloud imo, networking and services are indeed different concerns in this example.

You can create networks and use --net etc... if you don't care about service discovery.
Likewise, if you are using service discovery, you can use --net and/or --publish-service

Anyway, would love to hear your thoughts - feel free to ping me directly if you want to talk it over.

[dave-tucker]

@monadic added failure cases

[monadic]

thanks @dave-tucker

is docker run -itd --net=backend --publish-service=frontend:web an error?
^^^^^^^^ ^^^^^^^^

[dave-tucker]

@monadic I'm assuming so based on the discussions we had re: explicit vs implicit and multiple networks. I'm interpreting the user intent in your example as, attach me to frontend and backend and publish service web on front-end...

• we lose the "implicit" behaviour of publish-service joining a network too, when it's used with --net
• as we are now in "explicit" mode, we have to specify both the networks in --net for this command to be valid

otherwise the only constraint that we are enforcing (at this time) is that you can't have "discoverability" without "reachability" - it makes no sense to find a service when you can't access it. this may change in time as the features mature.

[jainvipin]

+1
@dave-tucker - thanks for being flexible and exposing this UI, all looks good.

Would love to join the mailer list and actively participate as per below:

I'm going to set up a networking working group call where we can discuss these kind of things - I'll add details to the libnetwork wiki soon - and would love it if you could join too.

[shettyg]

I'm going to set up a networking working group call where we can discuss these kind of things - I'll add details to the libnetwork wiki soon - and would love it if you could join too.

Me too, thanks @dave-tucker

[ibuildthecloud]

@dave-tucker I'll probably ping you directly. I've almost got it sorted out in my brain, but still -1. I'll hopefully have a write up of what I'm thinking by Monday.

[thockin]

I really think the conflation of network and service here is wrong.

docker network create mynetwork

OK

docker run -itd --publish-service=mynetwork:web nginx

BAD. If I understood the other thread, you want to publish a service into a scope, not into a network. Are scopes and networks 1:1 ? I don't know that they have to be. Can I define a network with more than one scope?

I think instead you want to disaggregate the ideas:

Simple services:

# make a network
docker network create mynetwork

# make a service scope
docker scope create myscope --net=mynetwork

# publish a service
docker run -itd --publish-service=myscope:web nginx

# consume a service only
docker run -itd --scope=myscope busybox

Ignoring services:

# make a network
docker network create mynetwork

# publish a service
docker run -itd nginx

# consume a service only
docker run -itd --net=mynetwork busybox

[rlane]

+1

I'd written a patch for this before finding this issue: rlane@9be0775

[lxpollitt]

@thockin I think the intention is that initially (i.e. in the increment covered by this PR) networks and scopes are 1:1, but that there is potential for scopes to be defined in the future that are not 1:1 with networks. I think this could do with being more clearly stated since right now the PR talks about publishing a service to a network, when it should probably talk about publishing to network's default scope (or something similar that de-conflates the concepts)?

I believe DNS is the assumed service discovery mechanism for now, so fully flexible scopes become interesting, but not impossible, to spec right so they make sense for the app developer and can be implemented by a broad range of network / service discovery drivers. I think that's a reasonable enough justification for simplifying in the short term and making scopes and networks 1:1. Obviously though there is a huge danger that this short term 1:1 leads to conflation, particularly if not explained and documented clearly.

[dave-tucker]

Closing in favour of what was implemented in #16645