update docs

Signed-off-by: Akihiro Suda <suda.akihiro@lab.ntt.co.jp>

README.md

@@ -27,16 +27,24 @@ Read the proposal from https://github.com/moby/moby/issues/32925
 
 Introductory blog post https://blog.mobyproject.org/introducing-buildkit-17e056cc5317
 
+:information_source: If you are visiting this repo for the usage of experimental Dockerfile features like `RUN --mount=type=(bind|cache|tmpfs|secret|ssh)`, please refer to [`docs/dockerfile_experimental.md`](./docs/dockerfile_experimental.md).
+
 ### Used by
 
-[Moby](https://github.com/moby/moby/pull/37151)
+[Moby & Docker](https://github.com/moby/moby/pull/37151)
 
 [img](https://github.com/genuinetools/img)
 
 [OpenFaaS Cloud](https://github.com/openfaas/openfaas-cloud)
 
 [container build interface](https://github.com/containerbuilding/cbi)
 
+[Knative Build Templates](https://github.com/knative/build-templates)
+
+[boss](https://github.com/crosbymichael/boss)
+
+[Rio](https://github.com/rancher/rio) (on roadmap)
+
 ### Quick start
 
 Dependencies:
@@ -79,6 +87,7 @@ See [`solver/pb/ops.proto`](./solver/pb/ops.proto) for the format definition.
 Currently, following high-level languages has been implemented for LLB:
 
 - Dockerfile (See [Exploring Dockerfiles](#exploring-dockerfiles))
+- [Buildpacks](https://github.com/tonistiigi/buildkit-pack)
 - (open a PR to add your own language)
 
 For understanding the basics of LLB, `examples/buildkit*` directory contains scripts that define how to build different configurations of BuildKit itself and its dependencies using the `client` package. Running one of these scripts generates a protobuf definition of a build graph. Note that the script itself does not execute any steps of the build.
@@ -145,6 +154,10 @@ buildctl build --frontend=gateway.v0 --frontend-opt=source=tonistiigi/dockerfile
 buildctl build --frontend gateway.v0 --frontend-opt=source=tonistiigi/dockerfile --frontend-opt=context=git://github.com/moby/moby --frontend-opt build-arg:APT_MIRROR=cdn-fastly.deb.debian.org
 ````
 
+##### Building a Dockerfile with experimental features like `RUN --mount=type=(bind|cache|tmpfs|secret|ssh)`
+
+See [`docs/dockerfile_experimental.md`](./docs/dockerfile_experimental.md).
+
 ### Exporters
 
 By default, the build result and intermediate cache will only remain internally in BuildKit. Exporter needs to be specified to retrieve the result.
@@ -210,12 +223,12 @@ BuildKit can also be used by running the `buildkitd` daemon inside a Docker cont
 To run daemon in a container:
 
 ```
-docker run -d --privileged -p 1234:1234 tonistiigi/buildkit --addr tcp://0.0.0.0:1234
+docker run -d --privileged -p 1234:1234 moby/buildkit --addr tcp://0.0.0.0:1234
 export BUILDKIT_HOST=tcp://0.0.0.0:1234
 buildctl build --help
 ```
 
-The `tonistiigi/buildkit` image can be built locally using the Dockerfile in `./hack/dockerfiles/test.Dockerfile`.
+The [`moby/buildkit`](https://hub.docker.com/r/moby/buildkit/tags/) image can be built locally using the Dockerfile in `./hack/dockerfiles/test.Dockerfile` (or `./hack/dockerfiles/test.buildkit.Dockerfile` if you already have BuildKit).
 
 ### Opentracing support
 

docs/dockerfile_experimental.md

@@ -0,0 +1,128 @@
+# Dockerfile frontend experimental syntaxes
+
+The contents of this document is planned to be moved to https://docs.docker.com in future.
+
+## Note for Docker users
+
+If you are using Docker v18.06 or later, BuildKit mode can be enabled by setting `export DOCKER_BUILDKIT=1` on the client side.
+Docker v18.06 also requires the daemon to be running as the experimental mode.
+
+You need to use `docker build` CLI instead of `buildctl` CLI mentioned in this document.
+See [the `docker build` document](https://docs.docker.com/engine/reference/commandline/build/) for the usage.
+
+Note that not all upstream BuildKit features are available in Docker BuildKit-mode.
+
+## Use experimental Dockerfile frontend
+The features mentioned in this document are experimentally available as [`tonistiigi/dockerfile:master-experimental`](https://hub.docker.com/r/tonistiigi/dockerfile/tags/) image.
+
+To use the experimental features, the first line of your Dockerfile needs to be `# syntax=tonistiigi/dockerfile:master-experimental`.
+As the experimental syntaxes may change in future revisions, you may want to pin the image to a specific revision.
+
+NOTE: `tonistiigi/dockerfile` is planned to be renamed to `docker/dockerfile-upstream` soon. See [#528](https://github.com/moby/buildkit/issues/528).
+
+## Experimental syntaxes
+
+### `RUN --mount=type=bind` (the default mount type)
+
+This mount type allows binding directories (read-only) in the context or in an image to the build container.
+
+|Option               |Description|
+|---------------------|-----------|
+|`target`(required)   | Mount path.|
+|`source`             | Source path in the `from`. Defaults to the root of the `from`.|
+|`from`               | Image name. Defaults to the build context.|
+
+
+### `RUN --mount=type=cache`
+
+This mount type allows the build container to cache directories for compilers and package managers.
+
+|Option               |Description|
+|---------------------|-----------|
+|`id`                 | ID of the cache.|
+|`target`(required)   | Mount path.|
+|`ro`,`readonly`      | Read-only if set.|
+|`sharing`            | Either one of `shared`, `private`, or `locked`. Defaults to `shared`. `shared` cache mount can be used concurrently by multiple writers. `private` creates a new mount if there are multiple writers. `locked` pauses second writer until first one releases the mount.|
+
+
+Example: cache Go packages
+
+```dockerfile
+# syntax = tonistiigi/dockerfile:master-experimental
+FROM golang
+...
+RUN --mount=type=cache,target=/root/.cache/go-build go build ...
+```
+
+Example: cache apt packages
+
+```dockerfile
+# syntax = tonistiigi/dockerfile:master-experimental
+FROM ubuntu
+RUN rm -f /etc/apt/apt.conf.d/docker-clean; echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' > /etc/apt/apt.conf.d/keep-cache
+RUN --mount=type=cache,target=/var/cache/apt --mount=type=cache,target=/var/lib/apt \
+  apt update && apt install -y gcc
+```
+
+### `RUN --mount=type=tmpfs`
+
+This mount type allows mounting tmpfs in the build container.
+
+|Option               |Description|
+|---------------------|-----------|
+|`target`(required)   | Mount path.|
+
+
+### `RUN --mount=type=secret`
+
+This mount type allows the build container to access credential files such as AWS keys without baking them into the image.
+
+|Option               |Description|
+|---------------------|-----------|
+|`id`                 | ID of the secret. Defaults to `path.Base(target)`.|
+|`target`             | Mount path. Defaults to `/run/secrets/ + path.Base(id)`.|
+|`required`           | If set to `true`, the instruction errors out when the secret is unavailable. Defaults to `false`.|
+
+
+Example: access to S3
+
+```dockerfile
+# syntax = tonistiigi/dockerfile:master-experimental
+FROM python:3
+RUN pip install awscli
+RUN --mount=type=secret,id=aws,target=/root/.aws/credentials aws s3 cp s3://... ...
+```
+
+```console
+$ buildctl build --frontend=dockerfile.v0 --local context=. --local dockerfile=. \
+  --secret id=aws,src=$HOME/.aws/credentials
+```
+
+### `RUN --mount=type=ssh`
+
+This mount type allows the build container to access SSH keys, with support for passphrases.
+
+|Option               |Description|
+|---------------------|-----------|
+|`required`           | If set to `true`, the instruction errors out when the key is unavailable. Defaults to `false`.|
+
+
+Example: access to Gitlab
+
+```dockerfile
+# syntax = tonistiigi/dockerfile:master-experimental
+FROM alpine
+RUN apk add --no-cache openssh-client
+RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
+RUN --mount=type=ssh ssh git@gitlab.com | tee /hello
+# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" should be printed here
+```
+
+```console
+$ eval $(ssh-agent)
+$ ssh-add ~/.ssh/id_rsa
+(Input your passphrase here)
+$ buildctl build --frontend=dockerfile.v0 --local context=. --local dockerfile=. \
+  --ssh default=$SSH_AUTH_SOCK
+```
+

docs/rootless.md

@@ -56,9 +56,10 @@ $ build-using-dockerfile --buildkit-addr unix:///run/user/1001/buildkit/buildkit
 
 ## Set up (using a container)
 
+Docker image is available as [`moby/buildkit:master-rootless`](https://hub.docker.com/r/moby/buildkit/tags/).
+
 ```
-$ docker build -t buildkit-rootless --target rootless -f hack/dockerfiles/test.Dockerfile .
-$ docker run --name buildkitd -d --privileged -p 1234:1234  buildkit-rootless --addr tcp://0.0.0.0:1234
+$ docker run --name buildkitd -d --privileged -p 1234:1234  moby/buildkit:master-rootless --addr tcp://0.0.0.0:1234
 ```
 
 `docker run` requires `--privileged` but the BuildKit daemon is executed as a normal user.