Merge pull request #3017 from airtower-luna/apt-example-lock

frontend/dockerfile/docs/reference.md

@@ -894,11 +894,18 @@ RUN --mount=type=cache,target=/root/.cache/go-build \
 # syntax=docker/dockerfile:1
 FROM ubuntu
 RUN rm -f /etc/apt/apt.conf.d/docker-clean; echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' > /etc/apt/apt.conf.d/keep-cache
-RUN --mount=type=cache,target=/var/cache/apt \
-  --mount=type=cache,target=/var/lib/apt \
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+  --mount=type=cache,target=/var/lib/apt,sharing=locked \
   apt update && apt-get --no-install-recommends install -y gcc
 ```
 
+Apt needs exclusive access to its data, so the caches use the option
+`sharing=locked`, which will make sure multiple parallel builds using
+the same cache mount will wait for each other and not access the same
+cache files at the same time. You could also use `sharing=private` if
+you prefer to have each build create another cache directory in this
+case.
+
 ### RUN --mount=type=tmpfs
 
 This mount type allows mounting tmpfs in the build container.