Merge pull request #17186 from dvdksn/build/migrate-bake-reference

build: move bake reference to buildx repo

_config.yml

@@ -269,3 +269,11 @@ fetch-remote:
       - dest: "compose/compose-file/deploy.md"
         src:
          - "deploy.md"
+
+  - repo: "https://github.com/docker/buildx"
+    default_branch: "master"
+    ref: "v0.10"
+    paths:
+      - dest: "build/bake/reference.md"
+        src:
+          - "docs/bake-reference.md"

_data/buildx/docker_buildx_bake.yaml

@@ -186,8 +186,8 @@ examples: |-
     $ docker buildx bake -f docker-bake.dev.hcl db webapp-release
     ```
 
-    See our [file definition](/build/bake/file-definition/)
-    guide for more details.
+    See the [Bake file reference](/build/bake/reference/)
+    for more details.
 
     ### Do not use cache when building the image (--no-cache) {#no-cache}
 

_data/toc.yaml

@@ -1688,8 +1688,8 @@ manuals:
       section:
         - path: /build/bake/
           title: Overview
-        - path: /build/bake/file-definition/
-          title: File definition
+        - path: /build/bake/reference/
+          title: Bake file reference
         - path: /build/bake/configuring-build/
           title: Configuring builds
         - path: /build/bake/hcl-funcs/
@@ -1698,6 +1698,8 @@ manuals:
           title: Build contexts and linking targets
         - path: /build/bake/compose-file/
           title: Building from Compose file
+        - path: /build/bake/remote-definition/
+          title: Remote Bake file definition
     - sectiontitle: Attestations
       section:
         - path: /build/attestations/

build/bake/compose-file.md

@@ -8,7 +8,7 @@ redirect_from:
 ## Specification
 
 Bake uses the [compose-spec](../../compose/compose-file/index.md) to
-parse a compose file and translate each service to a [target](file-definition.md#target).
+parse a compose file and translate each service to a [target](reference.md#target).
 
 ```yaml
 # docker-compose.yml
@@ -94,8 +94,7 @@ $ docker buildx bake --print
 }
 ```
 
-Unlike the [HCL format](file-definition.md#hcl-definition), there are some
-limitations with the compose format:
+The compose format has some limitations compared to the HCL format:
 
 * Specifying variables or global scope attributes is not yet supported
 * `inherits` service field is not supported, but you can use [YAML anchors](../../compose/compose-file/10-fragments.md){:target="blank" rel="noopener" class=""}

build/bake/hcl-funcs.md

@@ -7,7 +7,7 @@ redirect_from:
 
 ## Using interpolation to tag an image with the git sha
 
-As shown in the [File definition](file-definition.md#variable) page, `bake`
+As shown in the [Bake file reference](reference.md#variable) page, `bake`
 supports variable blocks which are assigned to matching environment variables
 or default values:
 

build/bake/index.md

@@ -34,7 +34,7 @@ and also allows better code reuse, different target groups and extended features
 
 ## Next steps
 
-* [File definition](file-definition.md)
+* [Bake file reference](reference.md)
 * [Configuring builds](configuring-build.md)
 * [User defined HCL functions](hcl-funcs.md)
 * [Defining additional build contexts and linking targets](build-contexts.md)

build/bake/reference.md

@@ -0,0 +1,8 @@
+---
+title: Buildx Bake reference
+description: Learn about the syntax and available commands for the Buildx Bake file
+keywords: build, reference, buildx, bake, hcl
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/bake/remote-definition.md

@@ -0,0 +1,136 @@
+---
+title: Remote Bake file definition
+keywords: build, buildx, bake, file, remote
+---
+
+You can also build Bake files directly from a remote Git repository or HTTPS URL:
+
+```console
+$ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print
+#1 [internal] load git source https://github.com/docker/cli.git#v20.10.11
+#1 0.745 e8f1871b077b64bcb4a13334b7146492773769f7       refs/tags/v20.10.11
+#1 2.022 From https://github.com/docker/cli
+#1 2.022  * [new tag]         v20.10.11  -> v20.10.11
+#1 DONE 2.9s
+```
+
+```json
+{
+  "group": {
+    "default": {
+      "targets": [
+        "binary"
+      ]
+    }
+  },
+  "target": {
+    "binary": {
+      "context": "https://github.com/docker/cli.git#v20.10.11",
+      "dockerfile": "Dockerfile",
+      "args": {
+        "BASE_VARIANT": "alpine",
+        "GO_STRIP": "",
+        "VERSION": ""
+      },
+      "target": "binary",
+      "platforms": [
+        "local"
+      ],
+      "output": [
+        "build"
+      ]
+    }
+  }
+}
+```
+
+As you can see the context is fixed to `https://github.com/docker/cli.git` even if
+[no context is actually defined](https://github.com/docker/cli/blob/2776a6d694f988c0c1df61cad4bfac0f54e481c8/docker-bake.hcl#L17-L26){:target="blank" rel="noopener" class=""}
+in the definition.
+
+If you want to access the main context for bake command from a bake file
+that has been imported remotely, you can use the [`BAKE_CMD_CONTEXT` built-in var](reference.md#built-in-variables).
+
+```console
+$ cat https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl
+```
+
+```hcl
+target "default" {
+  context = BAKE_CMD_CONTEXT
+  dockerfile-inline = <<EOT
+FROM alpine
+WORKDIR /src
+COPY . .
+RUN ls -l && stop
+EOT
+}
+```
+
+```console
+$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" --print
+```
+
+```json
+{
+  "target": {
+    "default": {
+      "context": ".",
+      "dockerfile": "Dockerfile",
+      "dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
+    }
+  }
+}
+```
+
+```console
+$ touch foo bar
+$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test"
+```
+
+```text
+...
+ > [4/4] RUN ls -l && stop:
+#8 0.101 total 0
+#8 0.102 -rw-r--r--    1 root     root             0 Jul 27 18:47 bar
+#8 0.102 -rw-r--r--    1 root     root             0 Jul 27 18:47 foo
+#8 0.102 /bin/sh: stop: not found
+```
+
+```console
+$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "https://github.com/docker/cli.git#v20.10.11" --print
+#1 [internal] load git source https://github.com/tonistiigi/buildx.git#remote-test
+#1 0.429 577303add004dd7efeb13434d69ea030d35f7888       refs/heads/remote-test
+#1 CACHED
+```
+
+```json
+{
+  "target": {
+    "default": {
+      "context": "https://github.com/docker/cli.git#v20.10.11",
+      "dockerfile": "Dockerfile",
+      "dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
+    }
+  }
+}
+```
+
+```console
+$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "https://github.com/docker/cli.git#v20.10.11"
+```
+
+```text
+...
+ > [4/4] RUN ls -l && stop:
+#8 0.136 drwxrwxrwx    5 root     root          4096 Jul 27 18:31 kubernetes
+#8 0.136 drwxrwxrwx    3 root     root          4096 Jul 27 18:31 man
+#8 0.136 drwxrwxrwx    2 root     root          4096 Jul 27 18:31 opts
+#8 0.136 -rw-rw-rw-    1 root     root          1893 Jul 27 18:31 poule.yml
+#8 0.136 drwxrwxrwx    7 root     root          4096 Jul 27 18:31 scripts
+#8 0.136 drwxrwxrwx    3 root     root          4096 Jul 27 18:31 service
+#8 0.136 drwxrwxrwx    2 root     root          4096 Jul 27 18:31 templates
+#8 0.136 drwxrwxrwx   10 root     root          4096 Jul 27 18:31 vendor
+#8 0.136 -rwxrwxrwx    1 root     root          9620 Jul 27 18:31 vendor.conf
+#8 0.136 /bin/sh: stop: not found
+```

build/release-notes.md

@@ -101,7 +101,7 @@ fixes in [Docker Buildx](https://github.com/docker/buildx){:target="blank" rel="
   support in BuildKit v0.11.0+. {% include github_issue.md repo="docker/buildx" number="1482" %}
 * Buildx now remembers the last activity for a builder for better organization
   of builder instances. {% include github_issue.md repo="docker/buildx" number="1439" %}
-* Bake definition now supports [null values](bake/file-definition.md#null-values)
+* Bake definition now supports null values for [variables](bake/reference.md#variable) and [labels](bake/reference.md#targetlabels)
   for build arguments and labels to use the defaults set in the Dockerfile {% include github_issue.md repo="docker/buildx" number="1449" %}
 * The [`buildx imagetools inspect` command](../engine/reference/commandline/buildx_imagetools_inspect.md)
   now supports showing SBOM and Provenance data {% include github_issue.md repo="docker/buildx" number="1444" %}