(Not in docs review yet, but a heads-up to prevent having to rewrite twice :))

Is this planned to be part of the 1.7 release? If not, the API docs will have to be moved to the v1.20 version, once created.

Also, the new end points will need to be added to the "what's new" section of the API docs

@thaJeztah Yes, this is planned to be part of 1.7 and I believe @dave-tucker is working with @moxiegirl on this.

@mavenugo alright, thanks for checking. I'll add it to the milestone as well then, to better keep track.

I will have to test this out tomorrow, but this looks really sweet.
Is this going to be experimental?

@cpuguy83 Thanks. the basic network command is not experimental. But the network service endpoint is already tagged as experimental in libnetwork.
If you build docker with the newly introduced experimental tag, you can already see the service appearing as experimental.

@mavenugo just saw this issue; #11247 wondering if that's a scenario that's possible with these new features?

@thaJeztah There is a long answer and a short one. Let me get geeky and give the longer answer ;-).
As you are aware, libnetwork provides the flexibility to the end-users through network drivers. These drivers provide an implementation for the network plumbing requirements. These drivers are not global in nature. But we can have 1 specific driver for a specific network that is created. Also we support labels for the CNM objects (network & endpoints) to let the user provide any configuration parameters to the network driver of choice for that particular deployment.
With the above constructs, anything is possible and it depends on the network driver and the feature it supports. Docker doesn't restrict any such implementation & the only requirement for the driver is to honor the CNM apis defined in libnetwork.

So, the short answer to the question is it depends on the driver that the user choose for their particular need. in this case it is #11247.

This approach also helps docker not to be overloaded with unlimited deployment scenarios and let the ecosystem provide solutions for a variety of user needs.

@mavenugo thanks, sounds really good! I'll add that to my answer on the linked issue.

@mavenugo couple of things:

1. network is not listed in the help of docker --help

2. We should support using name and ID for network interchangeably. This is really for ubiquity with current docker commands - so that a workflow like this is still possible.

mynet=$(docker network create foo)
docker run -itd --net=$mynet busybox

We could also go one step further and make name an optional parameter in docker network create. This would default to using docker's name generator for network names.

@dave-tucker Good suggestions. will fix them.

We originally designed the network name as optional parameter in create using --name option (just like container), but later decided to make it mandatory. Applying the pets vs cattle analogy, Network / Service are like pets which the users might want to name them. whereas containers are like cattle & hence it can live with ids. But if you have a strong opinion, we can certainly make this change.

PLEASE DO NOT MERGE UNTIL WE COMPLETE THE UI DISCUSSION.

We have not yet resolved whether we want the user-facing terms to be "networks" or "services". Feel free to discuss here. But please do not railroad. Thx.

Here is a strawman for a UI.

# Print the current service discovery scope
$ docker service scope
work-dev

# Print available service discovery scopes
$ docker service scopes
work-prod
work-staging
* work-dev
work-weekly-demo
weekend-project

# List published services in the active scope (here work-dev)
$ docker service list
db
frontend
backend

# List published services in an explicit scope
$ docker service list --scope work-prod
db
db_slave_1
db_slave_2
ssl_gateway
frontend
backend

# Export the service discovery data from the active scope as a "/etc/hosts" resolver config file
$ docker service export --format=etchosts
10.0.0.1  db
10.0.0.2  db_slave_1
10.0.0.3 db_slave_2
10.0.0.4 ssl_gateway
10.0.0.5 frontend
10.0.0.6 backend

# Publish a new service in a specific scope.
# If the service is already published, it is updated to point to the new backend.
# This can be used to orchestrate sophisticated update strategies.
$ docker service publish db --backend $CONTAINER_ID --replace=true --scope work-dev

# As a convenience, when running a new container, automatically publish it as a service
# Here "db.work-dev" means "service name db in the scope work-dev".
$ docker run --publish-service db.work-dev

Here the concept of "active scope" should be a client-side one, I think. No need to burden the daemon with this. In other words, the Remote API should always require an explicit scope name.

A possible variation is to not use the --scope flag, but instead require the NAME.SCOPE syntax everywhere.

Variation 1: docker service publish db --scope work-dev
Variation 2: docker service publish db.work-dev

Another possible variation: in publish, make the ID of the backend container mandatory, instead of supporting the --backend flag. This would make commands less verbose.

Variation A:
docker service publish db --backend 8d0114b6027e --scope work-dev

Variation B:
docker service publish 8d0114b6027e db --scope work-dev

Variation B combined with variation 2 above for maximum conciseness:
docker service publish 8d0114b6027e db.work-dev

@shykes thanks for sharing your thoughts on this important service construct.

I would like to put forward a couple of alternative suggestions to consider :

1. Move the entire network UI & API as experimental for 1.7.0 & let folks play with it knowing well that the UI will be consolidated under the service construct down the line ?
2. Split this PR into consumable & practical chunks as described below :

Will it help if we modify this PR into a more simplified version that supports just the docker run UI as you suggested and open a different enhancement to introduce the top-level docker service & give it the attention & time it rightly deserve ?

$ docker run --publish-service db.work-dev

This UI along with maybe an experimental --network-driver will make it consistent with the experimental --volume-driver for 1.7.0.

Since the back-end can have multiple endpoints attached to it on different scopes, it would make this run option as a list : docker run --publish-service db.work-dev --publish-service demo.work-weekly-demo

one other aspect is the swappability requirement of the container back-end with the service endpoint. We might have to introduce another option to have the user control if it allows service updates.

Ofcourse, I feel there is lot more to the docker service than this simplified option pack as described above. But we can use it as a start & maybe experimental for 1.7.

Please share your opinion.

May I point out that users do not necessarily want to use docker's idea of services to provide networking. In particular, if they are using docker with other tools. So while I appreciate the urge to provide an expressive user interface, I would be very wary of obscuring networking with a service abstraction -- i.e., making service commands (and --publish-service) the only way to get networking set up.

@ibuildthecloud if am not wrong there is one scheduled. @dave-tucker.
But lets not make this PR a planning session for that meeting :-)

I think an IRL discussion would be way better than hashing it out here. We
can circle back with a summary of the discussion and (hopefully) decisions.

Maybe you (Madhu) can pick a timeslot and a meeting place and let the
relevant parties know?

On Tue, Jun 16, 2015 at 6:12 PM, Madhu Venugopal notifications@github.com
wrote:

@ibuildthecloud https://github.com/ibuildthecloud if am not wrong there
is one scheduled. @dave-tucker https://github.com/dave-tucker.
But lets not make this PR a planning session for that meeting :-)

—
Reply to this email directly or view it on GitHub
#13441 (comment).

@mavenugo I'm confused by PR #13977. Does this mean that docker networks/--net will go forward independent of this services discussion? Basically we could have both docker networks/--net and services?

@ibuildthecloud no. PR #13977 was opened just to continue the specific discussion brought up on reusing --net to supply the user-defined network name. This is in addition to the --publish-service construct that is defined using this PR. Since it is a well-defined problem statement, we can continue to discuss and hash it out using #13977 without overloading this PR.

We introduced the CNM model more than a month ago and we are unable to make use of it due to this UI discussion. I feel that the current balance that we have with network and service UI along with --publish-service satisfies the requirements that @shykes brought up & I think is a good one.
Since these are defined under experimental, I think we should move on with this approach and get feedback from the users. Also with the help of #13977, we will get more inputs and we can continue to evolve this UI and I think that is the exact purpose of having experimental channel.

@mavenugo Sorry, this is not really constructive, but this whole discussion confuses me quite a bit. But if I understand correctly we are choosing between networks or services. We are also saying that the CNM may be nullified?

@ibuildthecloud please go over the docs commit : mavenugo@31bfd53 and that should clear up the latest status of this PR. After reviewing the docs, if you can give give it a hands on trial, I think that will answer your own question.

Given the debate, I think separating networks and services into different
PRs makes a lot of sense.

On Tue, Jun 16, 2015 at 10:03 PM, Madhu Venugopal notifications@github.com
wrote:

@ibuildthecloud https://github.com/ibuildthecloud please go over the
docs commit : mavenugo/docker@31bfd53
mavenugo@31bfd53
and that should clear up the latest status of this PR. After reviewing the
docs, if you can give give it a hands on trial, that would answer your own
question.

—
Reply to this email directly or view it on GitHub
#13441 (comment).

@mavenugo Thanks, that helped a lot.

Services is an abstraction above containers but from what I read from those docs it's basically one-to-one. How do we envision this services concept evolving. In the current form in this PR, it does not seem to be the proper use of the term service because effectively a service is just an IP and DNS name for a container. So basically an endpoint in the CNM.

Something seems off too me. The problem I see is that people looking to implement network drivers will most definitely come from a networking background (duh). So I imagine we will see VXLAN, VLAN, OVS, NSX, etc. All of these technologies give you a virtual L2 network. Service is very high level concept. Publishing and discovering services is an even higher level concept.

By saying you publish a service to a network seems like we are mixing layers. I have this very high level concept that will in practice be tied to a L2 boundary. Frankly, I lean much more towards not even exposing the concept of a network to the user. Just talk about services and their relationship. Networking can be implied from service relationships.

@ibuildthecloud I think there may have been some conflating of the layers, which is why separating the services and networks PRs seems like a sensible way forward. It is disappointing that it looks like there is little chance of getting this resolved (and anything implemented) in time for 1.7. But at least DockerCon will give those of us who can make it a chance to discuss face to face, which should help reach a shared understanding faster.

I'm part of the Calico team, and therefore "from a networking background", but our philosophy is that developers should not need to worry about low level networking constructs such as L2 segments. They should just be able to express their connectivity requirements in high-level intents, such as "containers of type A need to talk to containers of type B with constraints C" (where a constraint might be only allowing access to a particular port, or a bandwidth constraint, or whatever). We believe the networking layer should sort out how to map that intent into the underlying networking primitives specific to that particular network driver implementation.

Having said that, a common use case which we hear from customers, is to be able to support dev, test and prod "networks", that are isolated from each other, without the need to change container or app or service definitions between the networks. If you consider a "network" in this context, then saying a service exists within a network makes a fair amount of sense I think.

Anyway, I think I'm falling into the trap of lengthy comments here, when face to face might progress faster. @ibuildthecloud - will you be at DockerCon? It would be great to sync up with you then. I suspect that our thinking may be very similar on most of this once we unpick it!

I think the concept of --publish-service is valid and we should let that feature happen via this PR (which also introduces the services concept). This will help us separate the concerns and move forward without mixing the concepts and blocked on each other.

If we are going to separate the concerns, wouldn't it make sense to put the (clearly more controversial) services aspect elsewhere, rather than stepping on the bit that seemingly everyone agrees we should have?

To reiterate what @squaremo said a few days ago: "I don't see what was the problem with keeping networking and service discovery distinct (and supporting, say, docker --net=foo ..). It doesn't make sense to hide networking under service discovery, since users may not always want the latter."

@mavenugo In this proposal the concepts are focused on publishing services. What about consumption of services. If I publish db.foo does web need to publish web.foo to consume db in foo?

First part of this, the network UI, has been merged here: #14023

Are we having a meeting Next week? When and where?

On Tue, Jun 16, 2015 at 10:08 PM, Tim Hockin thockin@google.com wrote:

Given the debate, I think separating networks and services into different
PRs makes a lot of sense.

On Tue, Jun 16, 2015 at 10:03 PM, Madhu Venugopal <
notifications@github.com> wrote:

@ibuildthecloud https://github.com/ibuildthecloud please go over the
docs commit : mavenugo/docker@31bfd53
mavenugo@31bfd53
and that should clear up the latest status of this PR. After reviewing the
docs, if you can give give it a hands on trial, that would answer your own
question.

—
Reply to this email directly or view it on GitHub
#13441 (comment).

there is a BoF on Tuesday @thockin

Thanks for all the comments and good discussion around this PR.
Based on the popular demand, we split this into 2 independent PRs #14023, #14051.
Closing this PR.

Based on the popular demand, we split this into 2 independent PRs #14023, #14051.

I don't think you can appeal to popular demand here -- you've just done the thing people found objectionable in two steps instead of one.

What I was asking for is a general purpose networks (and endpoints) UI, before jumping into services. I don't think you can close this until at least #13977 or its near equivalent is addressed.

As @thockin said,

networking and services, while often coupled, are not the same problem. I think that functionality like this deserves to be exposed as a series of principled layers that each build on the previous.

@squaremo the purpose of this PR is to bring in the UI components and that is addressed. Hence it is closed. #13977 is opened to discuss on the very specific topic that you are interested. Hence lets use that PR for that purpose.