Merge pull request #928 from tonistiigi/bake-named-contexts

bake: add named contexts keys

docs/reference/buildx_bake.md

@@ -339,7 +339,7 @@ target "db" {
 
 Complete list of valid target fields:
 
-`args`, `cache-from`, `cache-to`, `context`, `dockerfile`, `inherits`, `labels`,
+`args`, `cache-from`, `cache-to`, `context`, `contexts`, `dockerfile`, `inherits`, `labels`,
 `no-cache`, `output`, `platform`, `pull`, `secrets`, `ssh`, `tags`, `target`
 
 ### Global scope attributes
@@ -799,6 +799,78 @@ $ docker buildx bake --print app
 }
 ```
 
+### Defining additional build contexts and linking targets
+
+In addition to the main `context` key that defines the build context each target can also define additional named contexts with a map defined with key `contexts`. These values map to the `--build-context` flag in the [build command](buildx_build.md#build-context).
+
+Inside the Dockerfile these contexts can be used with the `FROM` instruction or `--from` flag.
+
+The value can be a local source directory, container image (with docker-image:// prefix), Git URL, HTTP URL or a name of another target in the Bake file (with target: prefix).
+
+#### Pinning alpine image
+
+```Dockerfile
+# Dockerfile
+FROM alpine
+RUN echo "Hello world"
+```
+
+```hcl
+# docker-bake.hcl
+target "app" {
+    contexts = {
+        alpine = "docker-image://alpine:3.13"
+    }
+}
+```
+
+#### Using a secondary source directory
+
+```Dockerfile
+# Dockerfile
+
+FROM scratch AS src
+
+FROM golang
+COPY --from=src . .
+```
+
+```hcl
+# docker-bake.hcl
+target "app" {
+    contexts = {
+        src = "../path/to/source"
+    }
+}
+```
+
+#### Using a result of one target as a base image in another target
+
+To use a result of one target as a build context of another, specity the target name with `target:` prefix.
+
+```Dockerfile
+# Dockerfile
+FROM baseapp
+RUN echo "Hello world"
+```
+
+```hcl
+# docker-bake.hcl
+
+target "base" {
+    dockerfile = "baseapp.Dockerfile"
+}
+
+target "app" {
+    contexts = {
+        baseapp = "target:base"
+    }
+}
+```
+
+Please note that in most cases you should just use a single multi-stage Dockerfile with multiple targets for similar behavior. This case is recommended when you have multiple Dockerfiles that can't be easily merged into one.
+
+
 ### Extension field with Compose
 
 [Special extension](https://github.com/compose-spec/compose-spec/blob/master/spec.md#extension)