docs: document cache-from

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>
Signed-off-by: Tibor Vass <tibor@docker.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
(cherry picked from commit 73cd257d0f4fd717decc0d4bfe2260125d8da7da)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Upstream-commit: 56324e6348b87b96cfc3b1bad8d843df87e401a1
Component: cli

Author: tonistiigi

components/cli/docs/reference/commandline/build.md

@@ -489,6 +489,46 @@ FROM alpine AS production-env
 $ docker build -t mybuildimage --target build-env .
 ```
 
+### Specifying external cache sources
+
+In addition to local build cache, the builder can reuse the cache generated from
+previous builds with the `--cache-from` flag pointing to an image in the registry.
+
+To use an image as a cache source, cache metadata needs to be written into the
+image on creation. This can be done by setting `--build-arg BUILDKIT_INLINE_CACHE=1`
+when building the image. After that, the built image can be used as a cache source
+for subsequent builds.
+
+Upon importing the cache, the builder will only pull the JSON metadata from the
+registry and determine possible cache hits based on that information. If there
+is a cache hit, the matched layers are pulled into the local environment.
+
+In addition to images, the cache can also be pulled from special cache manifests
+generated by [`buildx`](https://github.com/docker/buildx) or the BuildKit CLI
+(`buildctl`). These manifests (when built with the `type=registry` and `mode=max`
+options) allow pulling layer data for intermediate stages in multi-stage builds.
+
+The following example builds an image with inline-cache metadata and pushes it
+to a registry, then uses the image as a cache source on another machine:
+
+```bash
+$ docker build -t myname/myapp --build-arg BUILDKIT_INLINE_CACHE=1 .
+$ docker push myname/myapp
+```
+
+After pushing the image, the image is used as cache source on another machine.
+BuildKit automatically pulls the image from the registry if needed.
+
+```bash
+# on another machine
+$ docker build --cache-from myname/myapp .
+```
+
+> **Note**: This feature requires the BuildKit backend. You can either
+> [enable BuildKit](../builder.md#buildkit) or use the [buildx](https://github.com/docker/buildx)
+> plugin. The previous builder has limited support for reusing cache from
+> pre-pulled images.
+
 ### Squash an image's layers (--squash) (experimental)
 
 #### Overview