Topic: Find a good and non-confusing home for the remaining monolith

I’m +1 for container-engine as well

Related to this (even though not a responsibility for the Moby project); would there be a way to override this name? Thinking how this would be dealt with in the Docker CE build/packaging

Yes that’s part of the plan.

For now, Docker can simply rename the container-engine binary to dockerd, and if usage output is a concern, we could use $0 there if it’s not already the case.

As far as the other binaries are concerned:

  • docker-containerd* -> containerd*
  • docker-runc -> runc
  • docker-init -> tini
  • docker-proxy -> $SOMETHING-proxy where $SOMETHING could be libnetwork, userland, nat, or anything you prefer.

These would keep their current name in docker releases.

LGTM, seems like a doable plan.

+1, this looks good!

Here are my criteria:

  1. The PROJECT name must clarify its relationship to Moby. Specifically it’s a sub-project of Moby, but distinct from Moby itself.

  2. The PROJECT name must clarify its relationship to Docker. Specifically that it’s not Docker, and it’s not a feature or product if Docker.

  3. The PROJECT name must clarify its function as a standardized starting point for a Moby assembly. 80% of Moby developers should probably start from this project instead of from scratch.

  4. It should be assumed that the PROJECT is permanent. It may change in architecture over time, but its function as a standardized starting point for 80% of Moby developers will always be needed.

  5. The PROJECT name should optimize for clarity and simplicity for the entire Docker community, not just for experienced contributors and maintainers.

  6. If possible the PROJECT name should optimize for familiarity. For example well-known words are better than obscure ones. For well-known words, well-understood definitions are preferred to unusual ones

  7. The REPOSITORY name must be consistent with the project name.

  8. The REPOSITORY name must make sense standalone, without the full github URL. A good test for this is whether it causes unnecessary name collisions and confusion when cloned locally.

  9. The BINARY names must share a common prefix, like docker binaries today.

  10. The BINARY names must not require renaming in downstream distros. Specifically Docker CE should ship the binaries under the same names. This means there will be no “dockerd” in Docker CE.

  11. The BINARY names should allow for individual binaries to appear or disappear from one version to the next. In other words binary names should be considered implementation details of the project.

  12. The PROJECT VERSIONING should be distinct from Docker, both in schema and cadence.

I reserve the right to add criteria as I think lf them :slight_smile:

Based on these criteria, I think the following suggestions DO NOT FIT THE CRITERIA:

  • “MCE”
  • “Engine”
  • “Container Engine”
  • “MobyOS”

Here is a new plan below. To move things forward I am pre-emptively declaring this plan “plan A”. Unless I am convinced by a counter-proposal this week, we will go with plan A next week.

@vieux please can you get the checklist ready so that we can execute the change ON MONDAY JULY 24. That is our deadline. We have delayed long enough, the community needs clarity.

Plan A is this:

  • project name: Moby Core
  • project short description: a modular base for the Moby Project
  • project longer description: Moby Core is a standard, modular base which Moby developers can adapt and extend to create custom container platforms with minimal effort. It aims to support 80% of use cases for Moby.
  • repo name: moby/moby-core
  • binary names: moby-core-server , moby-core-init, moby-core-containerd, moby-core-proxy
  • versioning: start at 2.0, follow postgres versioning convention. Release early and often.
  • API name: “the Moby Core API” replaces “the Docker engine API”. Preserve the same API versioning.
3 Likes

Thank you a lot for planning this.
Moby Core SGTM :+1:

  • Dockerfile will be still Dockerfile, right? (And which repo will contain Dockerfile parser?)
  • Will Docker CE rename /var/run/docker.sock? (If so, compatibility will be broken)
  • Can we consider starting Moby Core API from version 2.0 as well?
  • nit: why not “moby-core-daemon”? :smiling_imp:

I think this list of requirements helps, thanks.

This means there will be no “dockerd” in Docker CE.

This seems like a problem. Today people run dockerd to start the daemon. If there is nothing called dockerd we will break a bunch of installations. Should Docker CE provide a symlink for backwards compatibility?

a modular base for the Moby Project

Extrapolating from this description it sounds like the future of this repo is to retain roughly the same scope of features, but the architecture will change to be more modular. Does that sound right?

Moby Core aims to remove all dependencies on Docker products and Docker trademark. This is important for criteria 1: clarify the relationship to Docker. That includes removing terms like Dockerfile and docker-compose.yml from the Moby Core API and its specification.

This would have to be done gradually, and in a way that provides continuity for current API users. It would probably involve deprecating the current /build API endpoint (which badly needs an overhaul anyway) and either replacing it with something more flexible, or taking it out of scope entirely and leave it to the higher layers to implement build. This is the path that Kubernetes has chosen for example. There are several active projects implementing higher-level container build primitives decoupled from the underlying execution engine.

To be clear we should work on this in parallel to the project renaming. Consider this call for volunteers to propose a transition plan for Moby Core build features.

Similar to the Dockerfile topic: Moby Core should plan to get rid of /var/run/docker.sock to clarify thast Moby Core is not Docker.

Of course this should be done gradually, and managed carefully to provide continuity to users.

Consider this a call for volunteers to propose a docker.sock transition plan.

I think that would be confusing, because it will give the impression that we are breaking the API, when in fact we are only renaming the API but preserving backwards compatibility.

However, when we implement our Dockerfile transition plan or docker.sock transition plan, that transition might require changes to the Moby Core API. If those are breaking changes (for example deprecating the /build endpoint) then that would justify a major version bump.

Basically, we should stick to semver, and optimize for least surprise for API users.

I don’t have a strong opinion, as long as we allow the binary names to change easily from one version to the next.

I think it’s strictly a packaging issue. Upstream developers should avoid doing anything clever, and just assume that packagers are capable of handling a binary renames between versions - a pretty common packaging scenario. Maybe packagers will choose to create a symlink, or maybe they won’t. But we should let them deal with it.

My personal recommendation to packagers: don’t provide a symlink. It only kicks the can down the road since there will soon no longer be a single master daemon anyway. Any system installation that breaks when a daemon binary is renamed is way too brittle and should be fixed at the packaging or sysadmin level.

On the topic of modularity: yes, the architecture will change to be more modular, that is an explicit goal.

On the topic of scope: let’s not define a fixed scope of features for Moby Core right now. Instead, let’s define principles that maintainers can apply whenever they need to decide on scope. That way we can protect the project from bloat without crippling it.

I propose the following principles for determining whether a feature is in scope:

  • Principle 1: PURPOSE. Maintainers should only add features that contribute to the purpose of Moby Core, which is to help Moby developers create custom container platforms with minimal effort.

  • Principle 2: 80%. Moby Core aims to support 80% of the use cases for Moby. Therefore, it a feature helps at least 80% of Moby developers create custom container platforms with minimal effort, then it should be included, even if it doesn’t help the other 20%.

  • Principle 3: MODULARITY. Moby Core takes the form of a modular base to be extended adapted and extended. Therefore, all other things being equal, maintainers should err on the side of modularity.

    For example, if maintainers cannot decide between A) a full implementation of a feature, or B) extension points which allow third-party modules to implement the feature; then they should default to option B.

  • Principle 4: INDEPENDENCE. Moby Core is independent of its downstream products. Therefore, maintainers should ignore downstream product priorities when deciding on feature scope.

    For example, this clarifies that the Docker product roadmap does not influence the scope of Moby Core. This is important because the issue of influence by the Docker product roadmap (whether real or perceived) has often poisoned discussions of scope in the past.

One other question - given that /var/run/docker.sock needs renaming - I presume that the moby project also needs to register its own IANA ports ?

I guess its an opportunity to drop support for unencrypted TCP :slight_smile:

Could you please consider allowing use the trademark for compatibility reason?

For instances, Fedora/CentOS contains /etc/redhat-release, Linux supports AF_UNIX sockets, Iceweasel reports itself to be “Firefox”, Wine/ReactOS reports itself to be “Microsoft Windows”.(And now even Windows reports itself to be “GNU/Linux”.:penguin:)

I understand you might concern that Moby maintainers may modify Dockerfile specification without approval from Docker, Inc. and may harm the trademark.

So WDYT about this plan:

  • Docker, Inc. declares definition of “Dockerfile specification v17.05”, and that the “Dockerfile specification” is solely maintained by Docker, Inc. employees but can be implemented by anyone without explicit approval from Docker, Inc.

  • 3rd parties may fork “Dockerfile specification” and add new build instructions, but forked specs SHOULD NOT use “Dockerfile” as the file name. Forked specs may still support the “Dockerfile” file name for compatibility, but forked specs SHOULD NOT allow using their own instructions in Dockerfile-compatible mode.

  • moby-core-daemon implements “Dockerfile specification v17.05”. For a while, it means we just keep maintaining the current daemon code base. When BuildKit ( GitHub - moby/buildkit: concurrent, cache-efficient, and Dockerfile-agnostic builder toolkit ) gets matured, moby-core-daemon is expected to translate Dockerfile to BuildKit LLB, and send it to buildd (the BuildKit daemon). moby-core-daemon also exposes raw LLB endpoint.

  • Docker, Inc. may implement Dockerfile → LLB translater in docker/cli when BuildKit gets matured. When Docker. Inc. updates “Dockerfile specification”, Docker, Inc. may update docker/cli implementation as well, but neither Docker, Inc. nor Moby maintainers are responsible for updating the moby-core-daemon-side implementation.

Can the daemon listen on both docker.sock and moby-core-daemon.sock for compatibility?

Thanks Solomon on thinking through various aspects of this difficult transition.
In order to track and execute, shall we use Splitting Moby & Docker · GitHub and track all of the identified next steps ? Consolidating and listing the items here. I can open issues for each of the items tracked by milestones and deadlines in the above project directly.

We also need a place in the repo to clearly articulate these Principles prominently

Yes that would be great, thank you.

Hi all, the 7/24 deadline is tomorrow. Are there any outstanding blockers to execute “plan A”?

If yes, what are they?

If not, @vieux @mavenugo can you point us to the launch checklish and start assigning tasks?

Thanks all

Apologies for the late reply.
Here’s a summary of the main concerns expressed by maintainers at Docker:

  1. We need to find a URL we’re comfortable advertizing for packages like the API client library (possibly the most used one)

Solutions:
A) github.com/docker/docker/client
B) github.com/moby/moby-core/client
C) go.docker.io/docker-ce/v17.06/client
D) go.mobyproject.org/moby-core/client
E) Other?

Why is this important before making the repo change?
Even though the repository was renamed to github.com/moby/moby, the import paths were not rewritten to moby/moby.
This is not an issue for contributors developing on the engine since it is done in a container with correct import paths.
However, it is an issue for developers importing our Go packages into their own projects, because they need to know to still use the old github.com/docker/docker URLs, which is not obvious. We can still enforce any import path we want with canonical import paths (Go feature). If we were to execute on the repo rename without solving this issue, it will not have cleared confusion.

  1. Renaming the Docker API to Moby Core API.

This is somewhat linked to the previous issue.

a) Today, there is an ecosystem around the Docker API, and there is a technical issue
since Docker 17.06 for vendoring docker-ce’s API client library: https://github.com/moby/moby/issues/33989
The point is, there are people who want to interact with the API as it is exposed by
the docker product.

Given that, and if we rename the Docker API to Moby Core API, it seems that we’d need
to ensure, that a released version of the Moby Core API client is compatible with
a released version of Docker. IOW, if there is a bugfix needed in the API types, or client library,
Moby Core maintainers will have to issue a bugfix source release (simply git tag)
before the Docker release can proceed. Otherwise, the API in docker’s product will differ from
the API in Moby Core.

Another possibility is to fork the API, which would bring a lot of confusion and questions
(such as when to use which).

We could also, consider moving the API out again and do git tag releases there.
This caused some pain in the past that could be alleviated with frequent (automated?) vendoring.

In the meantime, a docker.io URL could be used as a smart git proxy for the docker-ce repo (Brian is working on this)

b) There may be a risk of confusing users who look for the Docker API and are given an API called “Moby Core” in search results. Would we move all the API docs from docs.docker.com to a mobyproject URL ?

  1. Grace period needed to heavily inform the developers

Once we have a plan for the URLs we want to advertize, we should use all our communication tools to spread the word on the
new URLs. If we decide to use canonical import paths (Go feature), the new URLs can be enforced by Go too (it would error out if it’s imported using the wrong URLs).

These are the 3 main blockers. The first two being blockers for even a blogpost.

FWIW, the PR to rename the binaries to moby-core-* was opened https://github.com/moby/moby/pull/34226 and reviews are welcome.

No, because that would conflict with Docker’s use of docker.sock.

I’m a bit confused by the scope of these changes. I agree on moving the moby/moby repository to moby/moby-core.

I agree this is something to be resolved, but given that the Moby project is an upstream to the Docker products, I feel that having an URL where people can get the exact version that’s used in the Docker products is something to be resolved outside of the Moby project.

Docker cherry-picks changes into their releases; all this is done outside of the Moby project; providing an URL for those packages would be a responsibiility of Docker.

If the Moby API switches to using SemVer, every change made to the API should result in a Major, Minor, or Patch version bump; Docker releases can pick a specific version (“compatible with Moby API x.y.z”). I don’t think we can always prevent cherry-picks to be needed in Docker’s releases (and not a responsibility of the Moby project); unless the Moby project plans on having a branch for each version of Moby’s API component, and do backports of bugfixes to those branches.

TL;DR for that is that it may not be just Docker using Moby as an upstream, other products may use Moby as an upstream as well, and we won’t be maintaining branches and stable URL’s for each product that uses Moby components (i.e. Moby project cannot keep track of exactly which patches/cherry-picks downstreams have). I think this is what’s described by:

There’s one thing I’m not sure about, and that’s naming the dependencies (moby-core-init, moby-core-runc, moby-core-containerd). The reason these binaries are currently prefixed is that Docker’s products sometimes cherry-pick changes into those binaries, thus they’re not vanilla upstreams. Without prefixing, the binaries could conflict with a vanilla version of those binaries installed on the same host. There’s two important parts here;

  • If Moby-code won’t do releases (I don’t think this was decided yet), it won’t ship binaries, so naming is not important yet; the binaries will only be used in CI and during development.
  • Unless Moby core is planning to fork these upstreams; is there actually a reason to have different names for these binaries (and not just containerd, runc, tini)?

To be clear, this is not a matter of trademark enforcement. It’s a matter of engineering and user experience. It’s our responsibility to make the difference very clear between Moby Core and Docker; otherwise, users will be confused and have a bad experience.

This is equally important for Moby Core users and Docker users. Nobody wants “Dockerfile” to mean different things in different contexts. That would be catastrophically confusing.

I understand the rationale for this proposal, but I disagree with it, because it doesn’t resolve the tight coupling between the build feature in Moby Core and the Docker UX. Therefore it doesn’t resolve the confusion between Docker and Moby Core.

Let’s take things one step at a time, and do the following:

  1. First things first, let’s finalize the split to Moby Core with the code we have today. Then the following statement will be true: “Docker implements a build feature tied to a Dockerfile specification. The Dockerfile specification is controlled by Docker, but the build feature is currently implemented in Moby Core for historical reasons. This creates a tight coupling between Moby Core and the Docker UX, which is against the goals of the Moby project. In the future, this tight coupling will be removed, but the docker build feature will be preserved.”

  2. Once the split is finalized, Moby Core will gradually remove the dependency on the Docker-controlled Dockerfile spec. My recommendation is to deprecate build in Moby Core altogether, and let higher-level layers implement it the way they want. This would make Moby Core more ecosystem-friendly. Docker would be one of the options for build, but other implementations would become first-class citizens, and would be free to be as compatible or incompatible with docker build as they wish. But this will require a debate with the other maintainers.

  3. In parallel, Docker will gradually refactor its docker build implementation to no longer require the /build endpoint in Moby Core. This will free Moby Core to remove its dependency on Dockerfile without breaking continuity for Docker users. Note that this helps us respect the Independence Principle: Moby Core should not have its hands tied by the expectations of Docker users when deciding what to do with its build feature.

@vieux @mavenugo could you add these to the split checklist please, even tentatively? I want to make sure we don’t drop this.

You are assuming a solution, which is to fork the API (even if slightly, for release purposes).
In that case we have to make it clear when to use which URLs. I understand your concern about separating project and product, hence why the decision is not easy. For instance, one could look at the REST API as being Docker-specific and we could experiment with new grpc APIs on Moby Core. This assumes NOT renaming Docker API to Moby Core API (contrary to plan A). One interesting note is, that deciding the latter does not mean that moving the API out of moby-core is a blocker. All we’d need to do is set up the docker.io URL Brian started and advertize that.

This and the VERSION number (some would prefer 0.x instead of 2.0), I did not consider them blockers. I agree with you on using upstream names without “moby-core” prefix but I realized that we can always change soon after, if we think that’s the right thing. Trying to avoid bikeshedding on names whenever possible.

It is planned for moby-core to do releases, except it’s simply a git tag in the source repo, and not a binary release.
Also, I’m assuming it is not needed to make a moby-core release for the repo name change, so figuring out all the details of a release is not a blocker either. My 2¢: I’m fine with 2.0.0 source releases, no binary releases, and I’m suggesting a flexible timed release (monthly) pretty much like in the early days of Docker.

Thanks Tibor.

For now, I will focus on this point which I will call Docker API vs Moby Core API. Once we resolve that, the other two points will be much easier to address.

1. Definitions

Before anything, let’s agree on a few definitions:

  • Docker Engine is an open-source daemon and client formerly hosted at github.com/docker/docker. It is being split between a daemon called Moby Core and a client called Docker Client or just docker. As a result of this split, the name Docker Engine is being deprecated.

  • The Docker Engine API allows applications to interface with the Docker Engine daemon. It is being replaced by the Moby Core API.

  • Moby Core is the direct successor to the Docker Engine daemon, with a reduced scope (providing a modular base for other platforms to adapt and extend), open governance and emphasis on stability and modularity.

  • The Moby Core API allows applications to interface with the Moby Core daemon. It is the successor to the Docker Engine API.

  • The Docker API allows applications to interface with the entire Docker platform. For historical reasons, it is fragmented in several different APIs, including:

    • the Docker Engine API (sometimes confusingly referred to as “The Docker API”)
    • the Docker Registry API
    • the Docker Hub API
    • the Docker Cloud API
    • the Docker Store API
    • the DTR API
    • the UCP API
    • the Notary API
    • the containerd API
    • the SwarmKit API
    • the Docker Compose Specification
    • the Dockerfile specification
    • etc.

    Because of this fragmentation, the Docker API is often confused with the Docker Engine API. However, they are very different. The Docker Engine API is defined by the scope of a single component, the Docker Engine. The Docker API is defined by the complete scope of the Docker platform.

2. Actions

Based on these definitions, I propose the following:

  1. As part of the split of Docker Engine into Moby Core and Docker Client, let’s introduce the Moby Core API, and make it a well-documented, well-managed successor to the Docker Engine API. Let’s make sure to do this independently of Docker.

  2. Let’s not maintain any API clients in Moby Core. Instead, let’s invest in making it very easy to generate Moby Core API clients from the Moby Core source code. We already use Swagger so we have a solid foundation to start from.

  3. On the Docker side, let’s introduce a standalone Docker Devkit alongside each Docker CE release, with everything needed to develop against that version of Docker all in one place:

    • An aggregate API documentation with sections for each component API in the release: Moby Core API, containerd API, Registry API, etc.
    • A Go SDK with client libraries for each component API in the release. The SDK must be exposed at a URL that is stable, location-independent, and developer-friendly.
    • SDKs in other languages as we add support for them.
    • Other resources like development tools and code examples, tested against the release.

    In particular, since Moby Core is a component of Docker CE, each release of the Docker Devkit will include:

    • In the API documentation, a section for the Moby Core API, at the version included in the release.
    • In the Go SDK, a client library for the Moby Core API that supports (at least) the version included in the release.
  4. Let’s communicate clearly the following:

    • To the Moby community, that they can now target the Moby Core API in their downstream products without depending on Docker.

    • To the Docker community, that they can now target the Docker API more easily, and in a less fragmented way, thanks to the brand new Docker Devkit.

    • To developers importing Go libraries in github.com/docker/docker:

      • If they’re specifically importing our Go client library for the Docker Engine API, they can now find it in the Docker SDK at a stable address. It will require a one-time change, but we will be careful to give them a smooth transition.
      • If they’re importing any other library under github.com/docker/docker, their application will soon break because of the repository change, and might break again later at any time because they are depending on a private interface of Moby Core. If they are comfortable with the risk, they should import the equivalent library in github.com/moby/moby-core. If they are not, they should consider contributing the work necessary to make the interface public. The Moby Core maintainers will be happy to assist them.

3. Testing against your questions

Let’s try to answer your questions based on the definitions and actions I propose above:

Here’s what we know about the library and its URL, step by step:

  • It will be part of the Docker Devkit, so its URL will be Docker-specific
  • A new devkit is released with each Docker release, so the URL schema will include the Docker version
  • SDKs must be exposed at a stable and location-independent URL, so it should not include implementation details such as github.com
  • SDKs must be exposed at a developer-friendly URL, so it should be short and intuitive
  • At the moment the Docker API is really just a collection of component APIs: Moby Core API is the component we are concerned with here, but it will be just one component among others. The URL hierarchy should reflect that.
  • My preference would be to optimize the URL

With that in mind, I think the answer is E) other. Here’s a strawman which I’m sure will cause strong bikeshedding reactions:

dockerdevkit.com/17.06-ce/gosdk/docker
dockerdevkit.com/17.06-ce/gosdk/docker/mobycore
dockerdevkit.com/17.06-ce/gosdk/docker/registry
dockerdevkit.com/17.06-ce/gosdk/docker/containerd
dockerdevkit.com/17.06-ce/gosdk/docker/hub
dockerdevkit.com/17.06-ce/gosdk/docker/cloud

I think this is solved by introducing Docker Devkit, and with my proposed communication to developers importing github.com/docker/docker.

Note: @thaJeztah is correct that the responsibility to provide developers with the right client libraries for the rigth Docker release is with Docker, not with Moby Core. Here we are discussing actions needed on both sides to complete the split.

[

I think this is solved by introducing Docker Devkit, and with my proposed communication to Docker developers.

Yes, once we agree precisely on what to communicate, we need to communicate clearly, loudly and consistently. That is an essential part of the plan.