From 8d7f69883f93c924364f75c211a7068a8831396c Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 16 Oct 2024 15:50:54 +0200
Subject: [PATCH] docs: clarify options for secret types (file, env)

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 docs/reference/buildx_build.md | 79 ++++++++++++++++++++++++++++------
 1 file changed, 66 insertions(+), 13 deletions(-)

diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md
index 801aef6f294..78c265a5bd0 100644
--- a/docs/reference/buildx_build.md
+++ b/docs/reference/buildx_build.md
@@ -912,17 +912,39 @@ For more information about how to use build secrets, see
 
 Supported types are:
 
-- [`file`](#file)
-- [`env`](#env)
+- [`type=file`](#typefile)
+- [`type=env`](#typeenv)
 
-Buildx attempts to detect the `type` automatically if unset.
+Buildx attempts to detect the `type` automatically if unset. If an environment
+variable with the same key as `id` is set, then Buildx uses `type=env` and the
+variable value becomes the secret. If no such environment variable is set, and
+`type` is not set, then Buildx falls back to `type=file`.
 
-#### `file`
+#### `type=file`
 
-Attribute keys:
+Source a build secret from a file.
+
+##### `type=file` synopsis
+
+```console
+$ docker buildx build --secret [type=file,]id=<ID>[,src=<FILEPATH>] .
+```
+
+##### `type=file` attributes
+
+| Key             | Description                                                                                           | Default                    |
+| --------------- | ----------------------------------------------------------------------------------------------------- | -------------------------- |
+| `id`            | ID of the secret.                                                                                     | N/A (this key is required) |
+| `src`, `source` | Filepath of the file containing the secret value (absolute or relative to current working directory). | `id` if unset.             |
+
+###### `type=file` usage
 
-- `id` - ID of the secret. Defaults to base name of the `src` path.
-- `src`, `source` - Secret filename. `id` used if unset.
+In the following example, `type=file` is automatically detected because no
+environment variable mathing `aws` (the ID) is set.
+
+```console
+$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
+```
 
 ```dockerfile
 # syntax=docker/dockerfile:1
@@ -932,16 +954,31 @@ RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
   aws s3 cp s3://... ...
 ```
 
+#### `type=env`
+
+Source a build secret from an environment variable.
+
+##### `type=env` synopsis
+
 ```console
-$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
+$ docker buildx build --secret [type=env,]id=<ID>[,env=<VARIABLE>] .
 ```
 
-#### `env`
+##### `type=env` attributes
 
-Attribute keys:
+| Key                    | Description                                     | Default                    |
+| ---------------------- | ----------------------------------------------- | -------------------------- |
+| `id`                   | ID of the secret.                               | N/A (this key is required) |
+| `env`, `src`, `source` | Environment variable to source the secret from. | `id` if unset.             |
+
+##### `type=env` usage
+
+In the following example, `type=env` is automatically detected because an
+environment variable matching `id` is set.
 
-- `id` - ID of the secret. Defaults to `env` name.
-- `env` - Secret environment variable. `id` used if unset, otherwise will look for `src`, `source` if `id` unset.
+```console
+$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
+```
 
 ```dockerfile
 # syntax=docker/dockerfile:1
@@ -951,10 +988,26 @@ RUN --mount=type=bind,target=. \
   yarn run test
 ```
 
+In the following example, the build argument `SECRET_TOKEN` is set to contain
+the value of the environment variable `API_KEY`.
+
 ```console
-$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
+$ API_KEY=token docker buildx build --secret id=SECRET_TOKEN,env=API_KEY .
 ```
 
+You can also specify the name of the environment variable with `src` or `source`:
+
+```console
+$ API_KEY=token docker buildx build --secret type=env,id=SECRET_TOKEN,src=API_KEY .
+```
+
+> [!NOTE]
+> Specifying the environment variable name with `src` or `source`, you are
+> required to set `type=env` explicitly, or else Buildx assumes that the secret
+> is `type=file`, and looks for a file with the name of `src` or `source` (in
+> this case, a file named `API_KEY` relative to the location where the `docker
+> buildx build` command was executed.
+
 ### <a name="shm-size"></a> Shared memory size for build containers (--shm-size)
 
 Sets the size of the shared memory allocated for build containers when using