add cache backend docs (upstream) (#15853)

Signed-off-by: David Karlsson <david.karlsson@docker.com>

Signed-off-by: David Karlsson <david.karlsson@docker.com>

_config.yml

@@ -172,6 +172,9 @@ fetch-remote:
       - dest: "build/building/drivers"
         src:
           - "docs/guides/drivers/**"
+      - dest: "build/building/cache/backends"
+        src:
+          - "docs/guides/cache/**"
 
   - repo: "https://github.com/distribution/distribution"
     default_branch: "main"

_data/toc.yaml

@@ -1472,9 +1472,7 @@ manuals:
       section:
         - path: /build/building/packaging/
           title: Packaging your software
-        - path: /build/building/cache/
-          title: Optimizing builds with cache
-        - sectiontitle: Choosing a build driver
+        - sectiontitle: Build drivers
           section:
             - path: /build/building/drivers/
               title: Overview
@@ -1486,6 +1484,24 @@ manuals:
               title: Kubernetes driver
             - path: /build/building/drivers/remote/
               title: Remote driver
+        - path: /build/building/cache/
+          title: Optimizing builds with cache
+        - sectiontitle: Cache backends
+          section:
+            - path: /build/building/cache/backends/
+              title: Overview
+            - path: /build/building/cache/backends/inline/
+              title: Inline
+            - path: /build/building/cache/backends/local/
+              title: Local
+            - path: /build/building/cache/backends/registry/
+              title: Registry
+            - path: /build/building/cache/backends/gha/
+              title: GitHub Actions
+            - path: /build/building/cache/backends/azblob/
+              title: Azure Blob Storage
+            - path: /build/building/cache/backends/s3/
+              title: Amazon S3
         - path: /build/building/multi-stage/
           title: Multi-stage builds
         - path: /build/building/multi-platform/

build/building/cache/backends/azblob.md

@@ -0,0 +1,7 @@
+---
+title: "Azure Blob Storage cache"
+keywords: build, buildx, cache, backend, azblob, azure
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/building/cache/backends/gha.md

@@ -0,0 +1,7 @@
+---
+title: "GitHub Actions cache"
+keywords: build, buildx, cache, backend, gha, github, actions
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/building/cache/backends/index.md

@@ -0,0 +1,7 @@
+---
+title: "Cache storage backends"
+keywords: build, buildx, cache, backend, gha, azblob, s3, registry, local
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/building/cache/backends/inline.md

@@ -0,0 +1,7 @@
+---
+title: "Inline cache"
+keywords: build, buildx, cache, backend, inline
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/building/cache/backends/local.md

@@ -0,0 +1,7 @@
+---
+title: "Local cache"
+keywords: build, buildx, cache, backend, local
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/building/cache/backends/registry.md

@@ -0,0 +1,7 @@
+---
+title: "Registry cache"
+keywords: build, buildx, cache, backend, registry
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/building/cache/backends/s3.md

@@ -0,0 +1,7 @@
+---
+title: "Amazon S3 cache"
+keywords: build, buildx, cache, backend, s3
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/building/cache/index.md

@@ -25,7 +25,7 @@ program written in C.
 FROM ubuntu:latest
 
 RUN apt-get update && apt-get install -y build-essentials
-COPY main.c /src/
+COPY main.c Makefile /src/
 WORKDIR /src/
 RUN make build
 ```
@@ -34,7 +34,7 @@ Each instruction in this Dockerfile translates (roughly) to a layer in your
 final image. You can think of image layers as a stack, with each layer adding
 more content on top of the layers that came before it:
 
-![Image layer diagram showing the above commands chained together one after the other](../images/cache-stack.svg){:.invertible}
+![Image layer diagram showing the above commands chained together one after the other](../../images/cache-stack.svg){:.invertible}
 
 Whenever a layer changes, that layer will need to be re-built. For example,
 suppose you make a change to your program in the `main.c` file. After this
@@ -42,13 +42,13 @@ change, the `COPY` command will have to run again in order for those changes to
 appear in the image. In other words, Docker will invalidate the cache for this
 layer.
 
-![Image layer diagram, but now with the link between COPY and WORKDIR marked as invalid](../images/cache-stack-invalidate-copy.svg){:.invertible}
+![Image layer diagram, but now with the link between COPY and WORKDIR marked as invalid](../../images/cache-stack-invalidate-copy.svg){:.invertible}
 
 If a layer changes, all other layers that come after it are also affected. When
 the layer with the `COPY` command gets invalidated, all layers that follow will
 need to run again, too:
 
-![Image layer diagram, but now with all links after COPY marked as invalid](../images/cache-stack-invalidate-rest.svg){:.invertible}
+![Image layer diagram, but now with all links after COPY marked as invalid](../../images/cache-stack-invalidate-rest.svg){:.invertible}
 
 And that's the Docker build cache in a nutshell. Once a layer changes, then all
 downstream layers need to be rebuilt as well. Even if they wouldn't build
@@ -287,8 +287,6 @@ of continuing.)
 
 ## Other resources
 
-For more information on using cache to do efficient builds:
+For more information on using cache to do efficient builds, see:
 
-<!-- x-link to dedicated cache exporter content once that's written -->
-
-- [Export your build cache](https://github.com/moby/buildkit#export-cache)
+- [Cache storage backends](./backends/index.md)

build/images/cache-stack-invalidate-copy.dot

@@ -8,7 +8,7 @@ digraph {
 
   from [ label = <<B>FROM </B>ubuntu:latest> ];
   deps [ label = <<B>RUN </B>apt-get update &amp;&amp; \\<br/>apt-get install -y build-essentials> ];
-  copy [ label = <<B>COPY </B>main.c /src/>, color = "red" ];
+  copy [ label = <<B>COPY </B>main.c Makefile /src/>, color = "red" ];
   workdir [ label = <<B>WORKDIR </B>/src/> ];
   build [ label = <<B>RUN </B>make build> ];
   

build/images/cache-stack-invalidate-copy.svg

@@ -33,8 +33,8 @@
 <g id="node3" class="node">
 <title>copy</title>
 <polygon fill="none" stroke="red" points="360,-146 0,-146 0,-117 360,-117 360,-146"/>
-<text text-anchor="start" x="128" y="-130" font-family="monospace" font-weight="bold" font-size="10.00">COPY </text>
-<text text-anchor="start" x="159" y="-130" font-family="monospace" font-size="10.00">main.c /src/</text>
+<text text-anchor="start" x="101" y="-130" font-family="monospace" font-weight="bold" font-size="10.00">COPY </text>
+<text text-anchor="start" x="132" y="-130" font-family="monospace" font-size="10.00">main.c Makefile /src/</text>
 </g>
 <!-- deps&#45;&gt;copy -->
 <g id="edge2" class="edge">

build/images/cache-stack-invalidate-rest.dot

@@ -8,7 +8,7 @@ digraph {
 
   from [ label = <<B>FROM </B>ubuntu:latest> ];
   deps [ label = <<B>RUN </B>apt-get update &amp;&amp; \\<br/>apt-get install -y build-essentials> ];
-  copy [ label = <<B>COPY </B>main.c /src/>, color = "red" ];
+  copy [ label = <<B>COPY </B>main.c Makefile /src/>, color = "red" ];
   workdir [ label = <<B>WORKDIR </B>/src/>, color = "red" ];
   build [ label = <<B>RUN </B>make build>, color = "red" ];
   

build/images/cache-stack-invalidate-rest.svg

@@ -33,8 +33,8 @@
 <g id="node3" class="node">
 <title>copy</title>
 <polygon fill="none" stroke="red" points="360,-161 0,-161 0,-132 360,-132 360,-161"/>
-<text text-anchor="start" x="128" y="-145" font-family="monospace" font-weight="bold" font-size="10.00">COPY </text>
-<text text-anchor="start" x="159" y="-145" font-family="monospace" font-size="10.00">main.c /src/</text>
+<text text-anchor="start" x="101" y="-145" font-family="monospace" font-weight="bold" font-size="10.00">COPY </text>
+<text text-anchor="start" x="132" y="-145" font-family="monospace" font-size="10.00">main.c Makefile /src/</text>
 </g>
 <!-- deps&#45;&gt;copy -->
 <g id="edge2" class="edge">

build/images/cache-stack.dot

@@ -8,7 +8,7 @@ digraph {
 
   from [ label = <<B>FROM </B>ubuntu:latest> ];
   deps [ label = <<B>RUN </B>apt-get update &amp;&amp; \\<br/>apt-get install -y build-essentials> ];
-  copy [ label = <<B>COPY </B>main.c /src/> ];
+  copy [ label = <<B>COPY </B>main.c Makefile /src/> ];
   workdir [ label = <<B>WORKDIR </B>/src/> ];
   build [ label = <<B>RUN </B>make build> ];
   

build/images/cache-stack.svg

@@ -33,8 +33,8 @@
 <g id="node3" class="node">
 <title>copy</title>
 <polygon fill="none" stroke="black" points="360,-131 0,-131 0,-102 360,-102 360,-131"/>
-<text text-anchor="start" x="128" y="-115" font-family="monospace" font-weight="bold" font-size="10.00">COPY </text>
-<text text-anchor="start" x="159" y="-115" font-family="monospace" font-size="10.00">main.c /src/</text>
+<text text-anchor="start" x="101" y="-115" font-family="monospace" font-weight="bold" font-size="10.00">COPY </text>
+<text text-anchor="start" x="132" y="-115" font-family="monospace" font-size="10.00">main.c Makefile /src/</text>
 </g>
 <!-- deps&#45;&gt;copy -->
 <g id="edge2" class="edge">

build/index.md

@@ -67,7 +67,7 @@ Improve build performance by using a persistent shared build cache to avoid
 repeating costly operations such as package installs, file downloads, or code
 build steps:
 
-[Optimizing builds with cache](building/cache.md){: .button .outline-btn }
+[Optimizing builds with cache](./building/cache/index.md){: .button .outline-btn }
 
 ### Multi-stage builds