From 35cd491dc9bc375b0f3ebac773e1c3bb4b706889 Mon Sep 17 00:00:00 2001 From: Andy Caldwell Date: Fri, 1 Oct 2021 19:21:03 +0100 Subject: [PATCH] Expand documentation for --secret --- develop/develop-images/build_enhancements.md | 90 ++++++++++++-------- 1 file changed, 55 insertions(+), 35 deletions(-) diff --git a/develop/develop-images/build_enhancements.md b/develop/develop-images/build_enhancements.md index 00614c2de431..7166fcf149e2 100644 --- a/develop/develop-images/build_enhancements.md +++ b/develop/develop-images/build_enhancements.md @@ -126,48 +126,60 @@ checks for updates of the syntax before building, making sure you are using the most current version. Learn more about the `syntax` directive in the [Dockerfile reference](/engine/reference/builder/#syntax). -## New Docker Build secret information +## Securely managing secrets during Docker Build -The new `--secret` flag for docker build allows the user to pass secret -information to be used in the Dockerfile for building docker images in a safe -way that will not end up stored in the final image. +`docker build` understands the `--secret` flag to allow the user to pass secret +information that can be referenced in the Dockerfile. The secret values are +only used for building docker images and will not end up stored in the final +image. -`id` is the identifier to pass into the `docker build --secret`. This identifier -is associated with the `RUN --mount` identifier to use in the Dockerfile. Docker -does not use the filename of where the secret is kept outside of the Dockerfile, -since this may be sensitive information. +A build operation may have multiple secrets associated with it, each identified +with an `id` which is shared between the `docker build` command line flag and +the Dockerfile. -`dst` renames the secret file to a specific file in the Dockerfile `RUN` command -to use. +### Accessing Secrets during the build -For example, with a secret piece of information stored in a text file: - -```console -$ echo 'WARMACHINEROX' > mysecret.txt -``` - -And with a Dockerfile that specifies use of a BuildKit frontend -`docker/dockerfile:1.2`, the secret can be accessed when performing a `RUN`: +Secrets are accessed in Dockerfiles with a `RUN --mount=type=secret,id=` +command. The value of the secret with the given `id` will be mounted as a file +in the file-system for the duration of that `RUN` command and will otherwise be +invisible to the rest of the build and to uses of the image. ```dockerfile # syntax=docker/dockerfile:1.2 FROM alpine -# shows secret from default secret location: +# Fetch secret from default secret location: RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret - -# shows secret from custom secret location: -RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar ``` -The secret needs to be passed to the build using the `--secret` flag. -This Dockerfile is only to demonstrate that the secret can be accessed. As you +_This Dockerfile is only to demonstrate that the secret can be accessed. As you can see the secret printed in the build output. The final image built will not -have the secret file: +have the secret file._ + +The `type=secret` and `id` parameters are mandatory but the following optional +parameters are also available if desired: + +* `dst=` - By default the secret file is created at `/run/secret/` by + passing the `dst` parameter you can specify a different path. +* `required` - By default, if no secret with the given `id` was specified for + the build then the secret file will still be created, but will be empty. If + the mount is specified as `required` then this will instead cause the build + to fail. + +Multiple secrets may be mounted into the `RUN` command by providing multiple +`--mount=type=secret` flags. + +### Providing the secret value to the build + +The secret value itself needs to be passed to the build using the `--secret` +flag on `docker build`. The secret can be retrieved from a file on disk or an +environment variable and is associated with the `id` that the Dockerfile can +use to access the secret during the build. ```console -$ docker build --no-cache --progress=plain --secret id=mysecret,src=mysecret.txt . +$ echo "WARMACHINEROX" > mysecret.txt +$ docker build --progress=plain --secret id=mysecret,src=mysecret.txt . ... #8 [2/3] RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret #8 digest: sha256:5d8cbaeb66183993700828632bfbde246cae8feded11aad40e524f54ce7438d6 @@ -176,18 +188,26 @@ $ docker build --no-cache --progress=plain --secret id=mysecret,src=mysecret.txt #8 1.081 WARMACHINEROX #8 completed: 2018-08-31 21:03:32.051053831 +0000 UTC #8 duration: 1.347502967s - - -#9 [3/3] RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar -#9 digest: sha256:6c7ebda4599ec6acb40358017e51ccb4c5471dc434573b9b7188143757459efa -#9 name: "[3/3] RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar" -#9 started: 2018-08-31 21:03:32.052880985 +0000 UTC -#9 1.216 WARMACHINEROX -#9 completed: 2018-08-31 21:03:33.523282118 +0000 UTC -#9 duration: 1.470401133s ... ``` +The `--secret` flag requires the `id` parameter and accepts the following +optional parameters: + +* `src=` - The file to read the secret value from. This must be a path within + the build context and the user running `docker build` must have permission to + read the file. +* `env=` - The name of the environment variable to read the secret value from. + +If neither `src` nor `env` are passed then the builder will first check for +an environment variable with the same name as the secret's `id`. If that does +not exist then it looks for a file in the current directory with the same name +as the secret's `id`. If neither of these checks succeeds to find a value the +build will fail. + +Multiple secrets may be passed to the build by passing the `--secret` flag +once per secret, specifying a different `id` for each one. + ## Using SSH to access private data in builds > **Acknowledgment**