From f7f5a6d1e71082a8f6597d8e95fe7e5b5efb868d Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 14 Nov 2023 18:07:03 +0100
Subject: [PATCH] build: add build secrets page

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/build/building/secrets.md | 115 ++++++++++++++++++++++++++++++
 data/toc.yaml                     |   2 +
 2 files changed, 117 insertions(+)
 create mode 100644 content/build/building/secrets.md

diff --git a/content/build/building/secrets.md b/content/build/building/secrets.md
new file mode 100644
index 0000000000..131e0eede5
--- /dev/null
+++ b/content/build/building/secrets.md
@@ -0,0 +1,115 @@
+---
+title: Build secrets
+description: Manage credentials and other secrets securely
+keywords: build, secrets, credentials, passwords, tokens
+---
+
+A build secret is any piece of sensitive information, such as a password or API
+token, consumed as part of your application's build process.
+
+Build arguments and environment variables are inappropriate for passing secrets
+to your build, because they persist in the final image. Instead, should use
+secret mounts or SSH mounts, which expose secrets to your builds securely.
+
+## Secret mounts
+
+Secret mounts expose secrets to the build containers as files. You [mount the
+secrets to the `RUN`
+instructions](../../engine/reference/builder.md#run---mounttypesecret) that
+need to access them, similar to how you would define a bind mount or cache
+mount.
+
+```dockerfile
+RUN --mount=type=secret,id=mytoken \
+    TOKEN=$(cat /run/secrets/mytoken) ...
+```
+
+To pass a secret to a build, use the [`docker build --secret`
+flag](../../engine/reference/commandline/buildx_build.md#secret), or the
+equivalent options for [Bake](../bake/reference.md#targetsecret).
+
+{{< tabs >}}
+{{< tab name="CLI" >}}
+
+```console
+$ docker build --secret id=mytoken,src=$HOME/.aws/credentials .
+```
+
+{{< /tab >}}
+{{< tab name="Bake" >}}
+
+```hcl
+variable "HOME" {
+  default = null
+}
+
+target "default" {
+  secret = [
+    "id=mytoken,src=${HOME}/.aws/credentials"
+  ]
+}
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
+### Sources
+
+The source of a secret can be either a
+[file](../../engine/reference/commandline/buildx_build.md#file) or an
+[environment variable](../../engine/reference/commandline/buildx_build.md#env).
+When you use the CLI or Bake, the type can be detected automatically. You can
+also specify it explicitly with `type=file` or `type=env`.
+
+The following example mounts the environment variable `KUBECONFIG` to secret ID
+`kube`.
+
+```console
+$ docker build --secret id=kube,env=KUBECONFIG .
+```
+
+The following example maps an environment variable directly to a secret ID.
+
+```console
+$ docker build --secret env=KUBECONFIG .
+```
+
+### Target
+
+By default, secrets are mounted to `/run/secrets/<id>`. You can customize the
+mount point in the build container using the `target` option in the Dockerfile.
+
+The following example mounts the secret to a `/root/.aws/credentials` file in
+the build container.
+
+```console
+$ docker build --secret id=aws,src=/root/.aws/credentials .
+```
+
+```dockerfile
+RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
+    aws s3 cp ...
+```
+
+## SSH mounts
+
+If the credential you want to use in your build is an SSH agent socket or key,
+you can use the SSH mount instead of a secret mount. Cloning private Git
+repositories is a common use case for SSH mounts.
+
+The following example clones a private GitHub repository using a [Dockerfile
+SSH mount](../../engine/reference/builder.md#run---mounttypessh).
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM alpine
+ADD git@github.com:me/myprivaterepo.git /src/
+```
+
+To pass an SSH socket the build, you use the [`docker build --ssh`
+flag](../../engine/reference/commandline/buildx_build.md#ssh), or equivalent
+options for [Bake](../bake/reference.md#targetssh).
+
+```console
+$ docker buildx build --ssh default .
+```
diff --git a/data/toc.yaml b/data/toc.yaml
index 8a660199db..be452c53a2 100644
--- a/data/toc.yaml
+++ b/data/toc.yaml
@@ -1751,6 +1751,8 @@ Manuals:
           title: Multi-platform images
         - path: /build/building/env-vars/
           title: Environment variables
+        - path: /build/building/secrets/
+          title: Build secrets
         - path: /build/building/opentelemetry/
           title: OpenTelemetry support
         - path: /build/building/base-images/