Bake file YAML support (?)

[emacdona]

Is this a docs issue?

• [x] My issue is about the documentation content or website

Type of issue

I can't find what I'm looking for

Description

This is a cruel joke: "or YAML formats, where the YAML format is an extension of a Docker Compose file."

I spent a few hours trying to get YAML to work with no success. It would be nice to give some YAML examples... or just remove that text all together :-)

It's not at all clear what the syntax of an analogous yaml bake file should be.

Location

https://docs.docker.com/build/bake/

Suggestion

Give corresponding YAML examples... or just don't mention that YAML is an option. Thank you for making docker!

[thaJeztah]

I suspect the intent here was to describe that docker bake / docker buildx bake can build from a compose file, in addition to a bake-file, but it's indeed confusing because the page doesn't explain that, doesn't show an example, and doesn't link to the compose-file reference ("build") section;

ls -l
total 16
-rw-r--r--  1 thajeztah  staff  37 Jun  6 12:24 Dockerfile
-rw-r--r--  1 thajeztah  staff  30 Jun  6 12:24 docker-compose.yml

cat Dockerfile
FROM nginx:alpine
RUN echo foo > bar

cat docker-compose.yml
services:
  web:
    build: .


docker bake
[+] Building 4.5s (8/8) FINISHED                                                                                                         docker:desktop-linux
 => [internal] load local bake definitions                                                                                                               0.0s
 => => reading docker-compose.yml 30B / 30B                                                                                                              0.0s
 => [internal] load build definition from Dockerfile                                                                                                     0.1s
 => => transferring dockerfile: 74B                                                                                                                      0.0s
 => [internal] load metadata for docker.io/library/nginx:alpine                                                                                          0.3s
 => [internal] load .dockerignore                                                                                                                        0.1s
 => => transferring context: 2B                                                                                                                          0.0s
 => [1/2] FROM docker.io/library/nginx:alpine@sha256:65645c7bb6a0661892a8b03b89d0743208a18dd2f3f17a54ef4b76fb8e2f2a10                                    1.9s
 => => resolve docker.io/library/nginx:alpine@sha256:65645c7bb6a0661892a8b03b89d0743208a18dd2f3f17a54ef4b76fb8e2f2a10                                    1.3s
 => [auth] library/nginx:pull token for registry-1.docker.io                                                                                             0.0s
 => [2/2] RUN echo foo > bar                                                                                                                             0.5s
 => exporting to image                                                                                                                                   0.9s
 => => exporting layers                                                                                                                                  0.4s
 => => exporting manifest sha256:7ef6bcdb1fb61cec05253be77115fdf6461d11a744a41420b74368c8020c0a12                                                        0.1s
 => => exporting config sha256:434125ce2c51126ce2609da37b8c7728c8f9d0ee5ef1ff4e286b7801bbb2ab28                                                          0.1s
 => => exporting attestation manifest sha256:52d86140e40db9f01fc64ba47a52022e25624e7a85ba80efb94d05f6fa58c5f6                                            0.1s
 => => exporting manifest list sha256:f64b4464040f5644b4fb71e7435983ae9456d4f91fe28a0ef8d2f8342dac16d7                                                   0.1s
 => => naming to moby-dangling@sha256:f64b4464040f5644b4fb71e7435983ae9456d4f91fe28a0ef8d2f8342dac16d7                                                   0.0s
 => => unpacking to moby-dangling@sha256:f64b4464040f5644b4fb71e7435983ae9456d4f91fe28a0ef8d2f8342dac16d7                                                0.1s

View build details: docker-desktop://dashboard/build/desktop-linux/desktop-linux/xnkbc4ctjrfvzrul3xpzayjxy

[thaJeztah]

@glours @ArthurFlag @crazy-max PTAL

[crazy-max]

I think we could link to https://docs.docker.com/build/bake/compose-file/

[glours]

IIUC there is an ambiguity with the following sentence which doesn't clearly explain that the YAML file expected is in fact a Compose file

A Bake file can be written in HCL, JSON, or YAML formats, where the YAML format is an extension of a Docker Compose file.

What is "an extension of a Docker Compose file" here?

[thaJeztah]

I wasn't sure if JSON was still supported, but https://docs.docker.com/build/bake/reference/ shows it does, so I think it's trying to outline that a bake-file could be either;

• A bake-file in HCL
• A bake-file in JSON format
• A compose-file (YAML)

(possibly a link to "file formats"; https://docs.docker.com/build/bake/reference/#file-format)

I think it would be a nice addition to show the "basic" example on that page in both HCL and JSON ("example Bake file"), and (perhaps as separate tabs) show the same file in HCL and JSON format, or if we can't use tabs, something like "Here's the same example in JSON format).

We should include a link to "refer to the bakefile reference for detailed information on the bake-file format" (https://docs.docker.com/build/bake/reference/)

And then a link and/or short section to describe that bake can also use a docker-compose file that has "build" sections, and for that we can link to https://docs.docker.com/build/bake/compose-file/