Add documentation for bind mount consistency flags (#31047). by yallop · Pull Request #31749 · moby/moby

yallop · 2017-03-10T22:49:26Z

Documentation for #31047, following @thaJeztah's recommendations, copied here for convenience:

the swagger.yaml

an entry to the API changes

the reference docs for run, create

the service create docs mention mount options

the docker run man page

the docker create man page options section

cpuguy83 · 2017-03-12T11:19:38Z

@yallop I think the service create doc should go in the table just beneath ro/rw options.

justincormack · 2017-03-12T13:54:52Z

cc @thaJeztah

yallop · 2017-03-13T08:15:15Z

Thanks, @cpuguy83. I've added an entry to the table.

thaJeztah · 2017-03-13T10:33:07Z

api/swagger.yaml

Can you list valid options here as well?

thaJeztah · 2017-03-13T10:38:42Z

Left one suggestion. Also, we probably need to add a note that this is (currently) only used on Docker for Mac?

I think it's ok to squash commits here before merging 😸

andrerom · 2017-03-14T16:44:04Z

Seems conceptual difference between consistent, delegate and cached is missing here.

Can maybe reuse text from the original gist, slightly adapted here to signal which one is default:

consistent: perfect consistency (default, host and container have an identical view of the mount at all times)
cached: the host's view is authoritative (permit delays before updates on the host appear in the container)
delegated: the container's view is authoritative (permit delays before updates on the container appear in the host)

mdlinville · 2017-03-17T19:22:38Z

api/swagger.yaml

It seems weird to have default. Isn't that just an alias for consistent?

default is consistent except with the lowest (instead of highest) priority in cases where multiple consistency requirements overlap. In the future, default may be changed to be cached except with the lowest (instead of the second highest) priority in cases where multiple consistency requirements overlap.

Question; if this field is left empty, is that equal to "default"? Wondering if we actually need the literal "default" value

I'm not sure what the API semantics are regarding omitted fields but the default mode is present in the --mount long-form CLI so that every mode is representable as an explicit value. At least in that context, having default allows things like scripting consistency=$MODE where the MODE variable can then be set to any of default, delegated, cached, or consistent. Without a representation for every mode, there is not a nice way to set the consistency to default without additional complexity of omitting consistency= sometimes.

I think overall the API allows omitting values to use the default, which also is "strictly" what default is 😇;

In computer technology, a default (noun, pronounced dee-FAWLT ) is a predesigned value or setting that is used by a computer program when a value or setting is not specified by the program user.

What will the result be if an older client creates a mount? (older clients won't know about this option, so use the old API version, and don't specify this property)

@cpuguy83 wdyt?

It probably doesn't need to be documented other than what the default actually is vs a value of "default".

mdlinville · 2017-03-17T19:24:04Z

docs/reference/commandline/create.md

What's the deal with the order here? Can it be either alphabetical or default-first? Also this doesn't have default as above.

default is not in this list because in the short -v form, :default is not very explanatory and simply omitting it is the same. default is in the long --mount form as it is an actual consistency mode that can be selected and may be indicated for maximum explanatory effect.

delegated is the most relaxed and lowest priority (except for default, not present in this form). cached is the next most relaxed and higher priority. consistent is not relaxed and highest priority.

mdlinville · 2017-03-17T19:24:25Z

docs/reference/commandline/run.md

Same comments as above

mdlinville · 2017-03-17T19:24:55Z

docs/reference/commandline/service_create.md

Ordering again, and questions about default. Also, this is a great time to explain what each of them means. I'd put them into a <ul>.

Thanks for the review, @mstanleyjones. I've added a <ul> explaining the modes, based on @andrerom's suggestion (c06c6bc).

mdlinville · 2017-03-17T19:26:16Z

man/docker-run.1.md

You can remove this line now.

mdlinville · 2017-03-17T19:26:29Z

man/src/container/create.md

Signed-off-by: Jeremy Yallop <yallop@docker.com>

thaJeztah

LGTM

thaJeztah · 2017-03-21T21:11:42Z

Seen this fail a couple of times, possibly flaky test

12:55:59 ----------------------------------------------------------------------
12:55:59 FAIL: docker_cli_push_test.go:607: DockerRegistryAuthTokenSuite.TestPushMisconfiguredTokenServiceResponseError
12:55:59 
12:55:59 docker_cli_push_test.go:615:
12:55:59     c.Assert(out, checker.Contains, "Retrying")
12:55:59 ... obtained string = "" +
12:55:59 ...     "The push refers to a repository [127.0.0.1:5000/busybox]\n" +
12:55:59 ...     "5f70bf18a086: Preparing\n" +
12:55:59 ...     "9508eff2c687: Preparing\n" +
12:55:59 ...     "toomanyrequests: out of tokens\n"
12:55:59 ... substring string = "Retrying"
12:55:59 
12:55:59 
12:55:59 ----------------------------------------------------------------------

Add documentation for bind mount consistency flags (moby#31047). (cherry picked from commit 9439402) Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

GordonTheTurtle added the status/0-triage label Mar 10, 2017

yallop mentioned this pull request Mar 10, 2017

Flags for specifying bind mount consistency #31047

Merged

yallop changed the title ~~Update the docs for run~~ Add documentation for bind mount consistency flags (#31047). Mar 10, 2017

yallop force-pushed the docs-31047 branch from 1c0e451 to e68b3af Compare March 10, 2017 23:05

thaJeztah added status/3-docs-review and removed status/0-triage labels Mar 13, 2017

thaJeztah added this to the 17.04.0 milestone Mar 13, 2017

thaJeztah reviewed Mar 13, 2017

View reviewed changes

api/swagger.yaml Outdated

Copy link
Copy Markdown

Member

thaJeztah Mar 13, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you list valid options here as well?

yallop reacted with thumbs up emoji

yallop force-pushed the docs-31047 branch 4 times, most recently from 6176c6c to 7ebacf7 Compare March 14, 2017 09:38

thaJeztah added the process/docs-cherry-pick label Mar 15, 2017

mdlinville suggested changes Mar 17, 2017

View reviewed changes

yallop force-pushed the docs-31047 branch from 870edaa to c06c6bc Compare March 20, 2017 11:42

Documentation for bind mount consistency flags.

1a710c1

Signed-off-by: Jeremy Yallop <yallop@docker.com>

yallop force-pushed the docs-31047 branch from c06c6bc to 1a710c1 Compare March 21, 2017 11:56

mdlinville approved these changes Mar 21, 2017

View reviewed changes

thaJeztah approved these changes Mar 21, 2017

View reviewed changes

thaJeztah added rebuild/janky labels Mar 21, 2017

GordonTheTurtle removed rebuild/janky labels Mar 21, 2017

thaJeztah added the status/4-merge label Mar 21, 2017

thaJeztah removed the status/3-docs-review label Mar 21, 2017

vdemeester merged commit 9439402 into moby:master Mar 22, 2017

yallop deleted the docs-31047 branch March 22, 2017 09:52

thaJeztah mentioned this pull request Apr 3, 2017

[17.04.x] docs cherry picks #32319

Merged

thaJeztah added process/docs-cherry-picked and removed process/docs-cherry-pick labels Apr 3, 2017

Conversation

yallop commented Mar 10, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cpuguy83 commented Mar 12, 2017

Uh oh!

justincormack commented Mar 12, 2017

Uh oh!

yallop commented Mar 13, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Mar 13, 2017

Uh oh!

andrerom commented Mar 14, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yallop Mar 20, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Mar 21, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

yallop commented Mar 10, 2017 •

edited

Loading

andrerom commented Mar 14, 2017 •

edited

Loading

yallop Mar 20, 2017 •

edited

Loading