diff --git a/_config.yml b/_config.yml index 582084c34e1..9c178aca2af 100644 --- a/_config.yml +++ b/_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" diff --git a/_data/toc.yaml b/_data/toc.yaml index 32817207f04..12609e91b4b 100644 --- a/_data/toc.yaml +++ b/_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/ diff --git a/build/building/cache/backends/azblob.md b/build/building/cache/backends/azblob.md new file mode 100644 index 00000000000..2db5435fe5e --- /dev/null +++ b/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 +--- diff --git a/build/building/cache/backends/gha.md b/build/building/cache/backends/gha.md new file mode 100644 index 00000000000..c4bbc05ca83 --- /dev/null +++ b/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 +--- diff --git a/build/building/cache/backends/index.md b/build/building/cache/backends/index.md new file mode 100644 index 00000000000..25f8047fc88 --- /dev/null +++ b/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 +--- diff --git a/build/building/cache/backends/inline.md b/build/building/cache/backends/inline.md new file mode 100644 index 00000000000..960dead6060 --- /dev/null +++ b/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 +--- diff --git a/build/building/cache/backends/local.md b/build/building/cache/backends/local.md new file mode 100644 index 00000000000..ac7b305cee8 --- /dev/null +++ b/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 +--- diff --git a/build/building/cache/backends/registry.md b/build/building/cache/backends/registry.md new file mode 100644 index 00000000000..7e738716b2b --- /dev/null +++ b/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 +--- diff --git a/build/building/cache/backends/s3.md b/build/building/cache/backends/s3.md new file mode 100644 index 00000000000..2482973aa99 --- /dev/null +++ b/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 +--- diff --git a/build/building/cache.md b/build/building/cache/index.md similarity index 96% rename from build/building/cache.md rename to build/building/cache/index.md index 282e375c6cc..6ce025c0e01 100644 --- a/build/building/cache.md +++ b/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: - - -- [Export your build cache](https://github.com/moby/buildkit#export-cache) +- [Cache storage backends](./backends/index.md) diff --git a/build/images/cache-stack-invalidate-copy.dot b/build/images/cache-stack-invalidate-copy.dot index b552138127e..f97486f367e 100644 --- a/build/images/cache-stack-invalidate-copy.dot +++ b/build/images/cache-stack-invalidate-copy.dot @@ -8,7 +8,7 @@ digraph { from [ label = <FROM ubuntu:latest> ]; deps [ label = <RUN apt-get update && \\
apt-get install -y build-essentials> ]; - copy [ label = <COPY main.c /src/>, color = "red" ]; + copy [ label = <COPY main.c Makefile /src/>, color = "red" ]; workdir [ label = <WORKDIR /src/> ]; build [ label = <RUN make build> ]; diff --git a/build/images/cache-stack-invalidate-copy.svg b/build/images/cache-stack-invalidate-copy.svg index a0408995dba..1a93f67c159 100644 --- a/build/images/cache-stack-invalidate-copy.svg +++ b/build/images/cache-stack-invalidate-copy.svg @@ -33,8 +33,8 @@ copy -COPY -main.c /src/ +COPY +main.c Makefile /src/ diff --git a/build/images/cache-stack-invalidate-rest.dot b/build/images/cache-stack-invalidate-rest.dot index 91c0ccc1274..81824186e09 100644 --- a/build/images/cache-stack-invalidate-rest.dot +++ b/build/images/cache-stack-invalidate-rest.dot @@ -8,7 +8,7 @@ digraph { from [ label = <FROM ubuntu:latest> ]; deps [ label = <RUN apt-get update && \\
apt-get install -y build-essentials> ]; - copy [ label = <COPY main.c /src/>, color = "red" ]; + copy [ label = <COPY main.c Makefile /src/>, color = "red" ]; workdir [ label = <WORKDIR /src/>, color = "red" ]; build [ label = <RUN make build>, color = "red" ]; diff --git a/build/images/cache-stack-invalidate-rest.svg b/build/images/cache-stack-invalidate-rest.svg index 7d0830d51db..ee6c2e0672d 100644 --- a/build/images/cache-stack-invalidate-rest.svg +++ b/build/images/cache-stack-invalidate-rest.svg @@ -33,8 +33,8 @@ copy -COPY -main.c /src/ +COPY +main.c Makefile /src/ diff --git a/build/images/cache-stack.dot b/build/images/cache-stack.dot index 7df536f7272..31e35443248 100644 --- a/build/images/cache-stack.dot +++ b/build/images/cache-stack.dot @@ -8,7 +8,7 @@ digraph { from [ label = <FROM ubuntu:latest> ]; deps [ label = <RUN apt-get update && \\
apt-get install -y build-essentials> ]; - copy [ label = <COPY main.c /src/> ]; + copy [ label = <COPY main.c Makefile /src/> ]; workdir [ label = <WORKDIR /src/> ]; build [ label = <RUN make build> ]; diff --git a/build/images/cache-stack.svg b/build/images/cache-stack.svg index 73522805a7d..9ac19295941 100644 --- a/build/images/cache-stack.svg +++ b/build/images/cache-stack.svg @@ -33,8 +33,8 @@ copy -COPY -main.c /src/ +COPY +main.c Makefile /src/ diff --git a/build/index.md b/build/index.md index b318af2fb78..16a6db03274 100644 --- a/build/index.md +++ b/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