docs: bake v0.19 entitlements

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.

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
 
+### <a name="allow"></a> 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=<path|*>` - Grant read access to files outside of the working
+  directory.
+- `fs.write=<path|*>` - 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
+```
+
 ### <a name="builder"></a> Override the configured builder instance (--builder)
 
 Same as [`buildx --builder`](buildx.md#builder).