[WIP/DNM/RFC] support local cache exporter and importer

Export:

  $ buildctl build ... --export-cache type=local,store=/path/to/output-dir

Import:

  $ buildctl build ... --cache-import type=local,store=/path/to/input-dir,digest=sha256:deadbeef

Impact on CLI:
* Old (deprecated but still effective): `--export-cache localhost:5000/myrepo:buildcache --export-cache-opt mode=max`
* New: `--cache-export type=registry,ref=localhost:5000/myrepo:buildcache,mode=max`

Impact on API:
* New fields are added to control.proto and gateway.proto. The daemon
internally translates old API calls to the new ones.
* While new API can be used for `registry` caches, the client continues
to use the legacy API for `registry` caches to ensure compatibility with
old daemons.
* To import `local` caches with a frontend, the frontend needs to support
a new frontend opt `cache-imports`.

Signed-off-by: Akihiro Suda <[email protected]>

README.md

@@ -198,6 +198,36 @@ buildctl build ... --exporter=oci --exporter-opt output=path/to/output.tar
 buildctl build ... --exporter=oci > output.tar
 ```
 
+### Exporting/Importing build cache (not image itself)
+
+#### To/From registry
+
+```
+buildctl build ... --cache-export type=registry,ref=localhost:5000/myrepo:buildcache
+buildctl build ... --cache-import type=registry,ref=localhost:5000/myrepo:buildcache
+```
+
+#### To/From local filesystem
+
+```
+buildctl build ... --cache-export type=local,store=path/to/output-dir
+buildctl build ... --cache-import type=local,store=path/to/output-dir,digest=sha256:deadbeef
+```
+
+The directory layout conforms to OCI Image Spec v1.0.
+However, `index.json` is not generated, because creating `index.json` would require locking the file, which can be problematic on shared filesystems.
+
+#### `--cache-export` options
+* `mode=min` (default): only export layers for the resulting image
+* `mode=max`: export all the layers of all intermediate steps
+* `ref=docker.io/user/image`: reference for `registry` cache exporter
+* `output=path/to/output-dir`: directory for `local` cache exporter
+
+#### `--cache-import` options
+* `ref=docker.io/user/image`: reference for `registry` cache importer
+* `input=path/to/input-dir`: directory for `local` cache importer
+* `digest=sha256:deadbeef`: digest of the manifest list to import for `local` cache importer
+
 ### Other
 
 #### View build cache