Can we add these flags to --mount (opts/mount.go) as well?

@AkihiroSuda: a1649ef

Design LGTM

While I definitely appreciate the goal of making osxfs faster (directly affects me!) this does not seem right.
This is adding an API only change and nothing in Docker would even be using it.

Additionally it seems like we're pushing osxfs performance issues to the user to deal with.
Suddenly we'll see compose files everywhere with cached or delegated added to them just so performance doesn't suck on OSX.

Additionally it seems like we're pushing osxfs performance issues to the user to deal with.

Improving performance on Docker for Mac is an immediate goal of this introducing this feature now, but there's nothing specific to osxfs in the design.

We're allowing the user to describe the consistency requirements of the mount, because that's information that only the user has, and because Docker can make use of that information to improve performance.

The interface currently has no way to enable caching because it's been designed with the Linux implementation in mind. If we want Docker to perform well on other systems then we need to adapt the interface so that it's less Linux-specific.

Suddenly we'll see compose files everywhere with cached or delegated added to them just so performance doesn't suck on OSX.

We can certainly hope that people start to use the feature. If we see cached or delegated in compose files it's because those are the consistency levels required by the application.

@dnephin, did the label (rebuild/experimental) trigger an experimental rebuild? I'm not sure whether the test failure represents a genuine problem.

I just retriggered the experimental rebuild, we were having some issues, I don't think it was triggered as the label was not automatically removed.

There's not a lot of activity on this issue, perhaps because it's not clear to the casual reader how critical this patch is to the success of Docker on macOS.

Here's an account posted on Reddit yesterday of how one company gave up on Docker:

This is our primary blocker for not using docker in our infrastructure right now. [...]
Docker is basically a no go at our company because of this issue. (Entire office uses MBP's)
There are some workarounds using rsync or something but it just seems like too much complexity.
I actually ended up spending a ton of time dockerizing our stack only to run into this brick wall. It was devistating.

This PR allows us to address the company's major concern. And this is far from an isolated case; it would be easy to give many more such examples.

@yallop I get it, I really do... but again this is not doing anything but changing the API. Docker is not consuming it any way. Major red flag here.

Why not at least provide a switch to change the default behavior in d4mac preferences? This could be done either globally or per share.
If there's still an issue after such an option is available it can be addressed accordingly.

I applaud the general effort to improve shared folder performance in Docker for Mac but I share @cpuguy83's concerns that this is adding something to the Docker API which does not get used by the Docker daemon at all.

Why would this not be added as a configurable setting in Docker for Mac? It seems to be very Docker for Mac specific. The Docker daemon is designed to run on Linux and Windows, but this adds a parameter which will be ignored by both.

@nathanleclaire while Docker for Mac is the first use case for these semantics, they are applicable to Infinit, Docker for Windows, volume plugins, and potentially Docker on Linux with a future extension point (delegated can effectively disable disk flushes during container run-time).

Just for the record, I was wooed and am ok with this change.

@cpuguy83 we're open to changing the name of the field and the names of the modes. We initially selected state and [consistent,cached,delegated,default] by evaluating three criteria:

1. -v comprehensibility
2. --mount comprehensibility
3. verbalization

The cases considered look like:

-v /a:/a:consistent pronounced "the mount is consistent"
-v /a:/a:cached pronounced "the mount is cached"
-v /a:/a:delegated pronounced "the mount is delegated"
--mount type=bind,src=/a,dst=/a,state=consistent pronounced "the mount's state is consistent"
--mount type=bind,src=/a,dst=/a,state=default pronounced "the mount's state is default"
--mount type=bind,src=/a,dst=/a,state=cached pronounced "the mount's state is cached"
--mount type=bind,src=/a,dst=/a,state=delegated pronounced "the mount's state is delegated"

I think you are proposing to change consistent to synchronous or full and state to consistency? I understand that state seems somewhat ambiguous about whether it is referring to the state of the mount concept or the underlying file system. I think it is unlikely to collide with future changes that do not interact with this specification as state is too general for any Docker mount concept and only makes sense in reference to the state of the file system itself.

I don't think full will work due to the case -v /a:/a:full which is not explanatory.

-v /a:/a:synchronous makes more sense but is longer, contains non-phonetic letters, and describes the implementation rather than the user's obervable experience. We are fine with naming the mode this if these trade-offs are considered and deemed acceptable. sync wouldn't have as many of these downsides but still describes implementation rather than behavior.

Renaming state to consistency would result in:

--mount type=bind,src=/a,dst=/a,consistency=consistent pronounced "the mount's consistency is consistent"
--mount type=bind,src=/a,dst=/a,consistency=default pronounced "the mount's consistency is default"
--mount type=bind,src=/a,dst=/a,consistency=cached pronounced "the mount's consistency is cached"
--mount type=bind,src=/a,dst=/a,consistency=delegated pronounced "the mount's consistency is delegated"

consistency is significantly longer than state, though arguably more descriptive. I don't think the verbalizations read as smoothly as state but they are still understandable.

We also believe that the terms used should be the same between -v and --mount and any future uses. In discussion with Ian Campbell, he suggested that state is ambiguous with some existing flags like ro which was undesirable. I know that the design of ro and rw are themselves in question as they are anonymous booleans. I think it could make sense to unify them with the state field to produce arguments like

--mount type=bind,src=/a,dst=/a,state=cached+ro pronounced "the mount's state is cached and read-only"

Ultimately, this all comes down to various comprehensibility and ease-of-use trade-offs in the design space. We think that the current names are the best of those we considered during design (e.g. state was initially semantics!) but we're happy to explore other options in a framework that takes the whole UX into account.

What issues do you foresee with the current set of names?

I think state is too generic. consistency makes the setting more clear.

14:29:39 These files are not properly gofmt'd:
14:29:39  - api/types/mount/mount.go
14:29:39 
14:29:39 Please reformat the above files using "gofmt -s -w" and commit the result.

Also needs a squash.

I've opened a separate in-progress PR for documentation, following @justincormack's suggestion, so as not to delay the merge here: #31749.

I've pushed docs to #31749.

Thanks for doing the docs PR; let's go ahead and merge this

This seems to be missing CLI docs. @thaJeztah PTAL

@mstanleyjones see #31749

Wow! Thanks.

Just wanted to thank the Moby team for integrating those changes. 👍