From 7b7affb11ae35c966b808dbee3fee00ab4a95094 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 18 Nov 2024 16:19:43 +0100
Subject: [PATCH 1/2] docs(bake): improve docs on "call" and "description" in
bake file
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
docs/bake-reference.md | 28 ++++++++++++++++++++++++++++
1 file changed, 28 insertions(+)
diff --git a/docs/bake-reference.md b/docs/bake-reference.md
index 19483210a5b..dd2039135ee 100644
--- a/docs/bake-reference.md
+++ b/docs/bake-reference.md
@@ -221,8 +221,10 @@ The following table shows the complete list of attributes that you can assign to
| [`attest`](#targetattest) | List | Build attestations |
| [`cache-from`](#targetcache-from) | List | External cache sources |
| [`cache-to`](#targetcache-to) | List | External cache destinations |
+| [`call`](#targetcall) | String | Specify the frontend method to call for the target. |
| [`context`](#targetcontext) | String | Set of files located in the specified path or URL |
| [`contexts`](#targetcontexts) | Map | Additional build contexts |
+| [`description`](#targetdescription) | String | Description of a target |
| [`dockerfile-inline`](#targetdockerfile-inline) | String | Inline Dockerfile string |
| [`dockerfile`](#targetdockerfile) | String | Dockerfile location |
| [`inherits`](#targetinherits) | List | Inherit attributes from other targets |
@@ -371,6 +373,13 @@ target "app" {
}
```
+Supported values are:
+
+- `build` builds the target (default)
+- `check`: evaluates [build checks](https://docs.docker.com/build/checks/) for the target
+- `outline`: displays the target's build arguments and their default values if available
+- `targets`: lists all Bake targets in the loaded definition, along with its [description](#targetdescription).
+
For more information about frontend methods, refer to the CLI reference for
[`docker buildx build --call`](https://docs.docker.com/reference/cli/docker/buildx/build/#call).
@@ -481,6 +490,25 @@ FROM baseapp
RUN echo "Hello world"
```
+### `target.description`
+
+Defines a human-readable description for the target, clarifying its purpose or
+functionality.
+
+```hcl
+target "lint" {
+ description = "Runs golangci-lint to detect style errors"
+ args = {
+ GOLANGCI_LINT_VERSION = null
+ }
+ dockerfile = "lint.Dockerfile"
+}
+```
+
+This attribute is useful when combined with the `targets` frontend method,
+providing a more informative output when listing the available build workflows
+in a Bake file.
+
### `target.dockerfile-inline`
Uses the string value as an inline Dockerfile for the build target.
From 642c778a65f1015a83e971c3b9f521e39fe6766b Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 28 Nov 2024 14:31:55 +0100
Subject: [PATCH 2/2] docs: add docs for bake --allow
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
docs/reference/buildx_bake.md | 62 ++++++++++++++++++++++++++++++++++-
1 file changed, 61 insertions(+), 1 deletion(-)
diff --git a/docs/reference/buildx_bake.md b/docs/reference/buildx_bake.md
index 3e02b859b09..113913fa29c 100644
--- a/docs/reference/buildx_bake.md
+++ b/docs/reference/buildx_bake.md
@@ -15,7 +15,7 @@ Build from a file
| Name | Type | Default | Description |
|:------------------------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------|
-| `--allow` | `stringArray` | | Allow build to access specified resources |
+| [`--allow`](#allow) | `stringArray` | | Allow build to access specified resources |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| [`--call`](#call) | `string` | `build` | Set method for evaluating build (`check`, `outline`, `targets`) |
| [`--check`](#check) | `bool` | | Shorthand for `--call=check` |
@@ -50,6 +50,66 @@ guide for introduction to writing bake files.
## Examples
+### Allow extra privileged entitelement (--allow)
+
+```text
+--allow=ENTITLEMENT[=VALUE]
+```
+
+In addition to BuildKit's `network.host` and `security.insecure` entitlements
+(see [`docker buildx build --allow`](https://docs.docker.com/reference/cli/docker/buildx/build/#allow),
+Bake also supports the following entitlements:
+
+- `fs.read=` - Grant read access to files outside of the working
+ directory.
+- `fs.write=` - Grant write access to files outside of the working
+ directory.
+
+The `fs.read` and `fs.write` entitlements take a path value (relative or
+absolute) to a directory on the filesystem. Alternatively, you can pass a
+wildcard (`*`) to allow Bake to access the entire filesystem.
+
+### Example: fs.read
+
+Given the following Bake configuration, Bake would need to access the parent
+directory, relative to the Bake file.
+
+```hcl
+target "app" {
+ context = "../src"
+}
+```
+
+Assuming `docker buildx bake app` is executed in the same directory as the
+`docker-bake.hcl` file, you would need to explicitly allow Bake to read from
+the `../src` directory. In this case, the following invocations all work:
+
+```console
+$ docker buildx bake --allow fs.read=* app
+$ docker buildx bake --allow fs.read=../ app
+$ docker buildx bake --allow fs.read=../src app
+```
+
+### Example: fs.write
+
+The following `docker-bake.hcl` file requires write access to the `/tmp`
+directory.
+
+```hcl
+target "app" {
+ output = "/tmp"
+}
+```
+
+Assuming `docker buildx bake app` is executed outside of the `/tmp` directory,
+you would need to allow the `fs.write` entitlement, either by specifying the
+path or using a wildcard:
+
+```console
+$ docker buildx bake --allow fs.write=/tmp app
+$ docker buildx bake --allow fs.write=* app
+```
+
### Override the configured builder instance (--builder)
Same as [`buildx --builder`](buildx.md#builder).