From 1c6ff26042c48fc4c643f7fbb997e6c5b8d53ebd Mon Sep 17 00:00:00 2001 From: Victoria Bialas Date: Fri, 21 Jul 2017 15:52:41 -0400 Subject: [PATCH] added Compose topics on caching options for performance (#3932) * added Compose topics on caching options for performance Signed-off-by: Victoria Bialas * updated title for Compose topic Signed-off-by: Victoria Bialas * line wrap per review Signed-off-by: Victoria Bialas --- compose/compose-file/index.md | 43 ++++++++++++++++++++++++++++++++- docker-for-mac/osxfs-caching.md | 34 ++++++++++++++++++++------ 2 files changed, 68 insertions(+), 9 deletions(-) diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index 483d0797f3..ae52995665 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -1426,9 +1426,50 @@ services: constraints: [node.role == manager] ``` +#### Caching options for volume mounts (Docker for Mac) + +On Docker 17.04 CE Edge and up, including 17.06 CE Edge and Stable, you can +configure container-and-host consistency requirements for bind-mounted +directories in Compose files to allow for better performance on read/write of +volume mounts. These options address issues specific to `osxfs` file sharing, +and therefore are only applicable on Docker for Mac. + +The flags are: + +* `consistent`: Full consistency. The container runtime and the +host maintain an identical view of the mount at all times. This is the default. + +* `cached`: The host's view of the mount is authoritative. There may be +delays before updates made on the host are visible within a container. + +* `delegated`: The container runtime's view of the mount is +authoritative. There may be delays before updates made in a container +are visible on the host. + +Here is an example of configuring a volume as `cached`: + +``` +version: '3' +services: + php: + image: php:7.1-fpm + ports: + - 9000 + volumes: + - .:/var/www/project:cached +``` + +Full detail on these flags, the problems they solve, and their +`docker run` counterparts is in the Docker for Mac topic [Performance tuning for +volume mounts (shared filesystems)](/docker-for-mac/osxfs-caching.md). + + ### restart -`no` is the default restart policy, and it will not restart a container under any circumstance. When `always` is specified, the container always restarts. The `on-failure` policy restarts a container if the exit code indicates an on-failure error. +`no` is the default restart policy, and it will not restart a container under +any circumstance. When `always` is specified, the container always restarts. The +`on-failure` policy restarts a container if the exit code indicates an +on-failure error. restart: "no" restart: always diff --git a/docker-for-mac/osxfs-caching.md b/docker-for-mac/osxfs-caching.md index 99da8f9c4a..1a0135af2d 100644 --- a/docker-for-mac/osxfs-caching.md +++ b/docker-for-mac/osxfs-caching.md @@ -15,7 +15,22 @@ of mounted volume access on Docker for Mac. These options begin to solve some of the challenges discussed in [Performance issues, solutions, and roadmap](/docker-for-mac/osxfs.md#performance-issues-solutions-and-roadmap). -> **Tip:** Release notes for Docker CE Edge 17.04 are [here](https://github.com/moby/moby/releases/tag/v17.04.0-ce), and the associated pull request for the additional `docker run -v` flags is [here](https://github.com/moby/moby/pull/31047). +> **Tip:** Release notes for Docker CE Edge 17.04 are +[here](https://github.com/moby/moby/releases/tag/v17.04.0-ce), and the +associated pull request for the additional `docker run -v` flags is +[here](https://github.com/moby/moby/pull/31047). + +The following topics describe the challenges of bind-mounted volumes on `osxfs`, +and the caching options provided to optimize performance. + +This blog post on [Docker on Mac +Performance](https://stories.amazee.io/docker-on-mac-performance-docker-machine-vs-docker-for-mac-4c64c0afdf99) +gives a nice, quick summary. + +For information on how to configure these options in a Compose file, see +[Caching options for volume +mounts](/compose/compose-file.md#caching-options-for-volume-mounts-docker-for-mac) +the Docker Compose topics. ## Performance implications of host-container file system consistency @@ -67,9 +82,10 @@ there is no need for writes to build artifacts within the container to be immediately reflected on the host file system. Distinguishing between these two cases makes it possible to significantly improve performance. -There are three broad scenarios to consider, based on which you can dial in the level of consistency you need. In each case, the container -has an internally-consistent view of bind-mounted directories, but in -two cases temporary discrepancies are allowed between container and host. +There are three broad scenarios to consider, based on which you can dial in the +level of consistency you need. In each case, the container has an +internally-consistent view of bind-mounted directories, but in two cases +temporary discrepancies are allowed between container and host. * `consistent`: perfect consistency (host and container have an identical view of the mount at all times) @@ -82,10 +98,12 @@ two cases temporary discrepancies are allowed between container and host. ## Examples -Each of these configurations (`consistent`, `cached`, `delegated`) can be specified as a suffix to the [`-v`](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) -option of [`docker run`](https://docs.docker.com/engine/reference/run.md). -For example, to bind-mount `/Users/yallop/project` in a container under -the path `/project`, you might run the following command: +Each of these configurations (`consistent`, `cached`, `delegated`) can be +specified as a suffix to the +[`-v`](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) +option of [`docker run`](https://docs.docker.com/engine/reference/run.md). For +example, to bind-mount `/Users/yallop/project` in a container under the path +`/project`, you might run the following command: ``` docker run -v /Users/yallop/project:/project:cached alpine command