Skip to content

Commit 1a60e0d

Browse files
crazy-maxcrazy-max
authored
Merge pull request #406 from crazy-max/cache-exporter-doc
Cache backend API example
2 parents 3c507be + 3530a97 commit 1a60e0d

File tree

3 files changed

+159
-47
lines changed

3 files changed

+159
-47
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 57 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -70,9 +70,6 @@ jobs:
7070
name: Inspect
7171
run: |
7272
docker buildx imagetools inspect localhost:5000/name/app:1.0.0
73-
-
74-
name: Image digest
75-
run: echo ${{ steps.docker_build.outputs.digest }}
7673
-
7774
name: Check digest
7875
run: |
@@ -133,9 +130,6 @@ jobs:
133130
name: Inspect
134131
run: |
135132
docker buildx imagetools inspect localhost:5000/name/app:1.0.0
136-
-
137-
name: Image digest
138-
run: echo ${{ steps.docker_build.outputs.digest }}
139133
-
140134
name: Check digest
141135
run: |
@@ -191,9 +185,6 @@ jobs:
191185
name: Inspect
192186
run: |
193187
docker buildx imagetools inspect localhost:5000/name/app:1.0.0
194-
-
195-
name: Image digest
196-
run: echo ${{ steps.docker_build.outputs.digest }}
197188
-
198189
name: Check digest
199190
run: |
@@ -392,9 +383,6 @@ jobs:
392383
name: Inspect
393384
run: |
394385
docker buildx imagetools inspect localhost:5000/name/app:1.0.0
395-
-
396-
name: Image digest
397-
run: echo ${{ steps.docker_build.outputs.digest }}
398386
-
399387
name: Check digest
400388
run: |
@@ -447,9 +435,6 @@ jobs:
447435
name: Inspect (1)
448436
run: |
449437
docker buildx imagetools inspect localhost:5000/name/app:latest
450-
-
451-
name: Image digest (1)
452-
run: echo ${{ steps.docker_build.outputs.digest }}
453438
-
454439
name: Check digest (1)
455440
run: |
@@ -480,9 +465,6 @@ jobs:
480465
name: Inspect (2)
481466
run: |
482467
docker buildx imagetools inspect localhost:5000/name/app:latest
483-
-
484-
name: Image digest (2)
485-
run: echo ${{ steps.docker_build2.outputs.digest }}
486468
-
487469
name: Check digest (2)
488470
run: |
@@ -503,7 +485,7 @@ jobs:
503485
if: always()
504486
uses: crazy-max/ghaction-dump-context@v1
505487

506-
github-cache-first:
488+
local-cache-first:
507489
runs-on: ubuntu-latest
508490
outputs:
509491
digest: ${{ steps.docker_build.outputs.digest }}
@@ -531,7 +513,7 @@ jobs:
531513
uses: actions/cache@v2
532514
with:
533515
path: /tmp/.buildx-cache
534-
key: ${{ runner.os }}-buildx-ghcache-${{ github.sha }}
516+
key: ${{ runner.os }}-buildx-local-${{ github.sha }}
535517
restore-keys: |
536518
${{ runner.os }}-buildx-ghcache-
537519
-
@@ -557,9 +539,6 @@ jobs:
557539
name: Inspect
558540
run: |
559541
docker buildx imagetools inspect localhost:5000/name/app:1.0.0
560-
-
561-
name: Image digest
562-
run: echo ${{ steps.docker_build.outputs.digest }}
563542
-
564543
name: Check digest
565544
run: |
@@ -572,9 +551,9 @@ jobs:
572551
if: always()
573552
uses: crazy-max/ghaction-dump-context@v1
574553

575-
github-cache-hit:
554+
local-cache-hit:
576555
runs-on: ubuntu-latest
577-
needs: github-cache-first
556+
needs: local-cache-first
578557
services:
579558
registry:
580559
image: registry:2
@@ -600,7 +579,7 @@ jobs:
600579
id: cache
601580
with:
602581
path: /tmp/.buildx-cache
603-
key: ${{ runner.os }}-buildx-ghcache-${{ github.sha }}
582+
key: ${{ runner.os }}-buildx-local-${{ github.sha }}
604583
restore-keys: |
605584
${{ runner.os }}-buildx-ghcache-
606585
-
@@ -622,9 +601,6 @@ jobs:
622601
name: Inspect
623602
run: |
624603
docker buildx imagetools inspect localhost:5000/name/app:1.0.0
625-
-
626-
name: Image digest
627-
run: echo ${{ steps.docker_build.outputs.digest }}
628604
-
629605
name: Check digest
630606
run: |
@@ -635,8 +611,8 @@ jobs:
635611
-
636612
name: Compare digests
637613
run: |
638-
echo Compare "${{ needs.github-cache-first.outputs.digest }}" with "${{ steps.docker_build.outputs.digest }}"
639-
if [ "${{ needs.github-cache-first.outputs.digest }}" != "${{ steps.docker_build.outputs.digest }}" ]; then
614+
echo Compare "${{ needs.local-cache-first.outputs.digest }}" with "${{ steps.docker_build.outputs.digest }}"
615+
if [ "${{ needs.local-cache-first.outputs.digest }}" != "${{ steps.docker_build.outputs.digest }}" ]; then
640616
echo "::error::Digests should be identical"
641617
exit 1
642618
fi
@@ -647,3 +623,53 @@ jobs:
647623
name: Dump context
648624
if: always()
649625
uses: crazy-max/ghaction-dump-context@v1
626+
627+
github-cache:
628+
runs-on: ubuntu-latest
629+
strategy:
630+
fail-fast: false
631+
matrix:
632+
buildx_version:
633+
- ""
634+
- latest
635+
services:
636+
registry:
637+
image: registry:2
638+
ports:
639+
- 5000:5000
640+
steps:
641+
-
642+
name: Checkout
643+
uses: actions/checkout@v2
644+
-
645+
name: Set up QEMU
646+
uses: docker/setup-qemu-action@v1
647+
-
648+
name: Set up Docker Buildx
649+
uses: docker/setup-buildx-action@v1
650+
with:
651+
version: ${{ matrix.buildx_version }}
652+
driver-opts: |
653+
network=host
654+
buildkitd-flags: --debug
655+
-
656+
name: Build and push
657+
uses: ./
658+
with:
659+
context: ./test
660+
file: ./test/multi.Dockerfile
661+
platforms: linux/amd64,linux/arm64
662+
push: true
663+
tags: |
664+
localhost:5000/name/app:latest
665+
localhost:5000/name/app:1.0.0
666+
cache-from: type=gha,scope=ci-${{ matrix.buildx_version }}
667+
cache-to: type=gha,scope=ci-${{ matrix.buildx_version }}
668+
-
669+
name: Inspect
670+
run: |
671+
docker buildx imagetools inspect localhost:5000/name/app:1.0.0
672+
-
673+
name: Dump context
674+
if: always()
675+
uses: crazy-max/ghaction-dump-context@v1

‎README.md‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,6 @@ ___
3333
* [Push to multi-registries](docs/advanced/push-multi-registries.md)
3434
* [Copy between registries](docs/advanced/copy-between-registries.md)
3535
* [Cache](docs/advanced/cache.md)
36-
* [Registry cache](docs/advanced/cache.md#registry-cache)
37-
* [GitHub cache](docs/advanced/cache.md#github-cache)
3836
* [Local registry](docs/advanced/local-registry.md)
3937
* [Export image to Docker](docs/advanced/export-docker.md)
4038
* [Share built image between jobs](docs/advanced/share-image-jobs.md)
@@ -100,9 +98,6 @@ jobs:
10098
with:
10199
push: true
102100
tags: user/app:latest
103-
-
104-
name: Image digest
105-
run: echo ${{ steps.docker_build.outputs.digest }}
106101
```
107102
108103
Building from the current repository automatically uses the [GitHub Token](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)
@@ -167,8 +162,6 @@ jobs:
167162
* [Push to multi-registries](docs/advanced/push-multi-registries.md)
168163
* [Copy between registries](docs/advanced/copy-between-registries.md)
169164
* [Cache](docs/advanced/cache.md)
170-
* [Registry cache](docs/advanced/cache.md#registry-cache)
171-
* [GitHub cache](docs/advanced/cache.md#github-cache)
172165
* [Local registry](docs/advanced/local-registry.md)
173166
* [Export image to Docker](docs/advanced/export-docker.md)
174167
* [Share built image between jobs](docs/advanced/share-image-jobs.md)

‎docs/advanced/cache.md‎

Lines changed: 102 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
11
# Cache
22

3+
* [Inline cache](#inline-cache)
34
* [Registry cache](#registry-cache)
45
* [GitHub cache](#github-cache)
6+
* [Cache backend API](#cache-backend-api)
7+
* [Local cache](#local-cache)
58

6-
> More info about buildx cache: https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#cache-from
9+
> More info about cache on [BuildKit](https://github.com/moby/buildkit#export-cache) and [Buildx](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#cache-from) repositories.
710
8-
## Registry cache
11+
## Inline cache
912

10-
You can import/export cache from a cache manifest or (special) image configuration on the registry.
13+
In most case you want to use the [`type=inline` cache exporter](https://github.com/moby/buildkit#inline-push-image-and-cache-together).
14+
However, note that the `inline` cache exporter only supports `min` cache mode. To enable `max` cache mode, push the
15+
image and the cache separately by using the `registry` cache exporter as shown in the [next example](#registry-cache).
1116

1217
```yaml
1318
name: ci
@@ -44,16 +49,104 @@ jobs:
4449
cache-to: type=inline
4550
```
4651
52+
## Registry cache
53+
54+
You can import/export cache from a cache manifest or (special) image configuration on the registry with the
55+
[`type=registry` cache exporter](https://github.com/crazy-max/buildkit/tree/cache-docs#registry-push-image-and-cache-separately).
56+
57+
```yaml
58+
name: ci
59+
60+
on:
61+
push:
62+
branches:
63+
- 'master'
64+
65+
jobs:
66+
docker:
67+
runs-on: ubuntu-latest
68+
steps:
69+
-
70+
name: Checkout
71+
uses: actions/checkout@v2
72+
-
73+
name: Set up Docker Buildx
74+
uses: docker/setup-buildx-action@v1
75+
-
76+
name: Login to DockerHub
77+
uses: docker/login-action@v1
78+
with:
79+
username: ${{ secrets.DOCKERHUB_USERNAME }}
80+
password: ${{ secrets.DOCKERHUB_TOKEN }}
81+
-
82+
name: Build and push
83+
uses: docker/build-push-action@v2
84+
with:
85+
context: .
86+
push: true
87+
tags: user/app:latest
88+
cache-from: type=registry,ref=user/app:buildcache
89+
cache-to: type=registry,ref=user/app:buildcache,mode=max
90+
```
91+
4792
## GitHub cache
4893

94+
### Cache backend API
95+
96+
> :test_tube: This cache exporter is considered EXPERIMENTAL until further notice. Please provide feedback on
97+
> [BuildKit repository](https://github.com/moby/buildkit) if you encounter any issues.
98+
99+
Since [buildx 0.6.0](https://github.com/docker/buildx/releases/tag/v0.6.0) and [BuildKit 0.9.0](https://github.com/moby/buildkit/releases/tag/v0.9.0),
100+
you can use the [`type=gha` cache exporter](https://github.com/moby/buildkit/tree/master#github-actions-cache-experimental).
101+
102+
GitHub Actions cache exporter backend uses the [GitHub Cache API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md)
103+
to fetch and upload cache blobs. That's why this type of cache should be exclusively used in a GitHub Action workflow
104+
as the `url` (`$ACTIONS_CACHE_URL`) and `token` (`$ACTIONS_RUNTIME_TOKEN`) attributes are populated when a workflow
105+
is started.
106+
107+
```yaml
108+
name: ci
109+
110+
on:
111+
push:
112+
branches:
113+
- 'master'
114+
115+
jobs:
116+
docker:
117+
runs-on: ubuntu-latest
118+
steps:
119+
-
120+
name: Checkout
121+
uses: actions/checkout@v2
122+
-
123+
name: Set up Docker Buildx
124+
uses: docker/setup-buildx-action@v1
125+
-
126+
name: Login to DockerHub
127+
uses: docker/login-action@v1
128+
with:
129+
username: ${{ secrets.DOCKERHUB_USERNAME }}
130+
password: ${{ secrets.DOCKERHUB_TOKEN }}
131+
-
132+
name: Build and push
133+
uses: docker/build-push-action@v2
134+
with:
135+
context: .
136+
push: true
137+
tags: user/app:latest
138+
cache-from: type=gha
139+
cache-to: type=gha,mode=max
140+
```
141+
142+
### Local cache
143+
49144
> :warning: At the moment caches are copied over the existing cache so it [keeps growing](https://github.com/docker/build-push-action/issues/252).
50145
> The `Move cache` step is used as a temporary fix (see https://github.com/moby/buildkit/issues/1896).
51146

52-
> :rocket: There is a new cache backend using GitHub cache being developed that will lighten your workflow.
53-
> More info: https://github.com/docker/buildx/pull/535
54-
55-
You can leverage [GitHub cache](https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)
56-
using [actions/cache](https://github.com/actions/cache) with this action:
147+
You can also leverage [GitHub cache](https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)
148+
using [actions/cache](https://github.com/actions/cache) and [`type=local` cache exporter](https://github.com/moby/buildkit#local-directory-1)
149+
with this action:
57150

58151
```yaml
59152
name: ci
@@ -95,7 +188,7 @@ jobs:
95188
push: true
96189
tags: user/app:latest
97190
cache-from: type=local,src=/tmp/.buildx-cache
98-
cache-to: type=local,dest=/tmp/.buildx-cache-new
191+
cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
99192
-
100193
# Temp fix
101194
# https://github.com/docker/build-push-action/issues/252

0 commit comments

Comments
 (0)