From 2c8d8f226845a2bbadce75c2a608221181e276ea Mon Sep 17 00:00:00 2001 From: Salathiel Genese Date: Tue, 21 Jan 2025 14:58:28 +0100 Subject: [PATCH] =?UTF-8?q?fix:=20invalid=20command,=20unrelated=20output?= =?UTF-8?q?=20chunks,=20too=20large=20minimal=20exam=E2=80=A6=20(#21859)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FIXes in the Docker Bake documentation. ## Description [x] Commands not matching outputs: _(e.g.: the presence of a group on the CLI affect the group section in the output)_ [x] Some file not being named bring about confusion to the reader _(e.g.: [Using a Target as Build Context](https://docs.docker.com/build/bake/contexts/#using-a-target-as-a-build-context) is not clear about needed two distinct Dockerfiles, or [Using a secondary source directory](https://docs.docker.com/build/bake/contexts/#using-a-secondary-source-directory) about the fact that the first stage in the Dockerfile does not have to be defined at all)_ [x] Multiple confusing relationships between input and output _(e.g.: the [Variables in Bake](https://docs.docker.com/build/bake/variables/) part shows multiple `webapp` target in the outputs whilst the HCL input only defines a `default` target)_ ## Related issues or tickets ## Reviews - [ ] Technical review - [x] Editorial review - [ ] Product review --------- Signed-off-by: Salathiel Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/build/bake/_index.md | 2 +- content/manuals/build/bake/contexts.md | 29 ++++++++-------- content/manuals/build/bake/expressions.md | 9 ++--- content/manuals/build/bake/inheritance.md | 12 +++---- content/manuals/build/bake/introduction.md | 2 +- content/manuals/build/bake/matrices.md | 6 ++-- .../manuals/build/bake/remote-definition.md | 2 +- content/manuals/build/bake/targets.md | 6 ++-- content/manuals/build/bake/variables.md | 34 ++++++++++++------- 9 files changed, 52 insertions(+), 50 deletions(-) diff --git a/content/manuals/build/bake/_index.md b/content/manuals/build/bake/_index.md index 93dfc11b946..ee9e59453cd 100644 --- a/content/manuals/build/bake/_index.md +++ b/content/manuals/build/bake/_index.md @@ -14,7 +14,7 @@ A Bake file can be written in HCL, JSON, or YAML formats, where the YAML format is an extension of a Docker Compose file. Here's an example Bake file in HCL format: -```hcl +```hcl {title=docker-bake.hcl} group "default" { targets = ["frontend", "backend"] } diff --git a/content/manuals/build/bake/contexts.md b/content/manuals/build/bake/contexts.md index 276939cefc3..6157b805b50 100644 --- a/content/manuals/build/bake/contexts.md +++ b/content/manuals/build/bake/contexts.md @@ -29,14 +29,13 @@ Supported context values are: ## Pinning alpine image -```dockerfile +```dockerfile {title=Dockerfile} # syntax=docker/dockerfile:1 FROM alpine RUN echo "Hello world" ``` -```hcl -# docker-bake.hcl +```hcl {title=docker-bake.hcl} target "app" { contexts = { alpine = "docker-image://alpine:3.13" @@ -46,16 +45,14 @@ target "app" { ## Using a secondary source directory -```dockerfile -# syntax=docker/dockerfile:1 -FROM scratch AS src - +```dockerfile {title=Dockerfile} FROM golang COPY --from=src . . ``` -```hcl -# docker-bake.hcl +```hcl {title=docker-bake.hcl} +# Running `docker buildx bake app` will result in `src` not pointing +# to some previous build stage but to the client filesystem, not part of the context. target "app" { contexts = { src = "../path/to/source" @@ -68,14 +65,16 @@ target "app" { To use a result of one target as a build context of another, specify the target name with `target:` prefix. -```dockerfile +```dockerfile {title=baseapp.Dockerfile} +FROM scratch +``` +```dockerfile {title=Dockerfile} # syntax=docker/dockerfile:1 FROM baseapp RUN echo "Hello world" ``` -```hcl -# docker-bake.hcl +```hcl {title=docker-bake.hcl} target "base" { dockerfile = "baseapp.Dockerfile" } @@ -119,7 +118,7 @@ result in significant impact on build time, depending on your build configuration. For example, say you have a Bake file that defines the following group of targets: -```hcl +```hcl {title=docker-bake.hcl} group "default" { targets = ["target1", "target2"] } @@ -148,7 +147,7 @@ context that only loads the context files, and have each target that needs those files reference that named context. For example, the following Bake file defines a named target `ctx`, which is used by both `target1` and `target2`: -```hcl +```hcl {title=docker-bake.hcl} group "default" { targets = ["target1", "target2"] } @@ -177,7 +176,7 @@ The named context `ctx` represents a Dockerfile stage, which copies the files from its context (`.`). Other stages in the Dockerfile can now reference the `ctx` named context and, for example, mount its files with `--mount=from=ctx`. -```dockerfile +```dockerfile {title=Dockerfile} FROM scratch AS ctx COPY --link . . diff --git a/content/manuals/build/bake/expressions.md b/content/manuals/build/bake/expressions.md index ded6d0eb505..71e7ef7de72 100644 --- a/content/manuals/build/bake/expressions.md +++ b/content/manuals/build/bake/expressions.md @@ -30,7 +30,7 @@ Printing the Bake file with the `--print` flag shows the evaluated value for the `answer` build argument. ```console -$ docker buildx bake --print app +$ docker buildx bake --print ``` ```json @@ -76,13 +76,8 @@ $ docker buildx bake --print ```json { - "group": { - "default": { - "targets": ["default"] - } - }, "target": { - "webapp": { + "default": { "context": ".", "dockerfile": "Dockerfile", "tags": ["my-image:latest"] diff --git a/content/manuals/build/bake/inheritance.md b/content/manuals/build/bake/inheritance.md index b07a56bcec8..6f4328579d1 100644 --- a/content/manuals/build/bake/inheritance.md +++ b/content/manuals/build/bake/inheritance.md @@ -10,7 +10,7 @@ Targets can inherit attributes from other targets, using the `inherits` attribute. For example, imagine that you have a target that builds a Docker image for a development environment: -```hcl +```hcl {title=docker-bake.hcl} target "app-dev" { args = { GO_VERSION = "{{% param example_go_version %}}" @@ -28,7 +28,7 @@ slightly different attributes for a production build. In this example, the `app-release` target inherits the `app-dev` target, but overrides the `tags` attribute and adds a new `platforms` attribute: -```hcl +```hcl {title=docker-bake.hcl} target "app-release" { inherits = ["app-dev"] tags = ["docker.io/username/myapp:latest"] @@ -43,7 +43,7 @@ shared attributes for all or many of the build targets in the project. For example, the following `_common` target defines a common set of build arguments: -```hcl +```hcl {title=docker-bake.hcl} target "_common" { args = { GO_VERSION = "{{% param example_go_version %}}" @@ -55,7 +55,7 @@ target "_common" { You can then inherit the `_common` target in other targets to apply the shared attributes: -```hcl +```hcl {title=docker-bake.hcl} target "lint" { inherits = ["_common"] dockerfile = "./dockerfiles/lint.Dockerfile" @@ -88,7 +88,7 @@ When a target inherits another target, it can override any of the inherited attributes. For example, the following target overrides the `args` attribute from the inherited target: -```hcl +```hcl {title=docker-bake.hcl} target "app-dev" { inherits = ["_common"] args = { @@ -110,7 +110,7 @@ The `inherits` attribute is a list, meaning you can reuse attributes from multiple other targets. In the following example, the app-release target reuses attributes from both the `app-dev` and `_common` targets. -```hcl +```hcl {title=docker-bake.hcl} target "_common" { args = { GO_VERSION = "{{% param example_go_version %}}" diff --git a/content/manuals/build/bake/introduction.md b/content/manuals/build/bake/introduction.md index 02c23ff6730..5265a26e387 100644 --- a/content/manuals/build/bake/introduction.md +++ b/content/manuals/build/bake/introduction.md @@ -71,7 +71,7 @@ $ docker build \ The Bake equivalent would be: -```hcl +```hcl {title=docker-bake.hcl} target "myapp" { context = "." dockerfile = "Dockerfile" diff --git a/content/manuals/build/bake/matrices.md b/content/manuals/build/bake/matrices.md index c4764132f4c..c53da927854 100644 --- a/content/manuals/build/bake/matrices.md +++ b/content/manuals/build/bake/matrices.md @@ -19,7 +19,7 @@ should resolve, use the name attribute. The following example resolves the app target to `app-foo` and `app-bar`. It also uses the matrix value to define the [target build stage](/build/bake/reference/#targettarget). -```hcl +```hcl {title=docker-bake.hcl} target "app" { name = "app-${tgt}" matrix = { @@ -73,7 +73,7 @@ The following example builds four targets: - `app-bar-1-0` - `app-bar-2-0` -```hcl +```hcl {title=docker-bake.hcl} target "app" { name = "app-${tgt}-${replace(version, ".", "-")}" matrix = { @@ -98,7 +98,7 @@ The following example builds two targets: - `app-foo-1-0` - `app-bar-2-0` -```hcl +```hcl {title=docker-bake.hcl} target "app" { name = "app-${item.tgt}-${replace(item.version, ".", "-")}" matrix = { diff --git a/content/manuals/build/bake/remote-definition.md b/content/manuals/build/bake/remote-definition.md index ff13e70a4db..bffe599c085 100644 --- a/content/manuals/build/bake/remote-definition.md +++ b/content/manuals/build/bake/remote-definition.md @@ -91,7 +91,7 @@ execution context as named contexts. The following example defines the `docs` context as `./src/docs/content`, relative to the current working directory where Bake is run as a named context. -```hcl +```hcl {title=docker-bake.hcl} target "default" { contexts = { docs = "cwd://src/docs/content" diff --git a/content/manuals/build/bake/targets.md b/content/manuals/build/bake/targets.md index 64b74e25904..29c6a1d376b 100644 --- a/content/manuals/build/bake/targets.md +++ b/content/manuals/build/bake/targets.md @@ -9,7 +9,7 @@ keywords: bake, target, targets, buildx, docker, buildkit, default A target in a Bake file represents a build invocation. It holds all the information you would normally pass to a `docker build` command using flags. -```hcl +```hcl {title=docker-bake.hcl} target "webapp" { dockerfile = "webapp.Dockerfile" tags = ["docker.io/username/webapp:latest"] @@ -35,7 +35,7 @@ $ docker buildx bake webapp api tests If you don't specify a target when running `docker buildx bake`, Bake will build the target named `default`. -```hcl +```hcl {title=docker-bake.hcl} target "default" { dockerfile = "webapp.Dockerfile" tags = ["docker.io/username/webapp:latest"] @@ -61,7 +61,7 @@ For all the properties you can set for a target, see the [Bake reference](/build You can group targets together using the `group` block. This is useful when you want to build multiple targets at once. -```hcl +```hcl {title=docker-bake.hcl} group "all" { targets = ["webapp", "api", "tests"] } diff --git a/content/manuals/build/bake/variables.md b/content/manuals/build/bake/variables.md index 0db49d53718..e4861a5a723 100644 --- a/content/manuals/build/bake/variables.md +++ b/content/manuals/build/bake/variables.md @@ -15,7 +15,7 @@ environment variables. Use the `variable` block to define a variable. -```hcl +```hcl {title=docker-bake.hcl} variable "TAG" { default = "docker.io/username/webapp:latest" } @@ -23,8 +23,8 @@ variable "TAG" { The following example shows how to use the `TAG` variable in a target. -```hcl -target "default" { +```hcl {title=docker-bake.hcl} +target "webapp" { context = "." dockerfile = "Dockerfile" tags = [ TAG ] @@ -37,7 +37,7 @@ Bake supports string interpolation of variables into values. You can use the `${}` syntax to interpolate a variable into a value. The following example defines a `TAG` variable with a value of `latest`. -```hcl +```hcl {title=docker-bake.hcl} variable "TAG" { default = "latest" } @@ -46,8 +46,16 @@ variable "TAG" { To interpolate the `TAG` variable into the value of an attribute, use the `${TAG}` syntax. -```hcl -target "default" { +```hcl {title=docker-bake.hcl} +group "default" { + targets = [ "webapp" ] +} + +variable "TAG" { + default = "latest" +} + +target "webapp" { context = "." dockerfile = "Dockerfile" tags = ["docker.io/username/webapp:${TAG}"] @@ -87,7 +95,7 @@ range, or other condition, you can define custom validation rules using the In the following example, validation is used to enforce a numeric constraint on a variable value; the `PORT` variable must be 1024 or higher. -```hcl +```hcl {title=docker-bake.hcl} # Define a variable `PORT` with a default value and a validation rule variable "PORT" { default = 3000 # Default value assigned to `PORT` @@ -115,7 +123,7 @@ the variable. All conditions must be `true`. Here’s an example: -```hcl +```hcl {title=docker-bake.hcl} # Define a variable `VAR` with multiple validation rules variable "VAR" { # First validation block: Ensure the variable is not empty @@ -148,7 +156,7 @@ dependent variables are set correctly before proceeding. Here’s an example: -```hcl +```hcl {title=docker-bake.hcl} # Define a variable `FOO` variable "FOO" {} @@ -171,8 +179,8 @@ will trigger the validation error. If you want to bypass variable interpolation when parsing the Bake definition, use double dollar signs (`$${VARIABLE}`). -```hcl -target "default" { +```hcl {title=docker-bake.hcl} +target "webapp" { dockerfile-inline = <