docs: Enhance podman build --secret documentation and add examples

Signed-off-by: H Dub <14808878+hdub-tech@users.noreply.github.com>
baude · Jan 24, 2025 · 0d2431d · 0d2431d
1 parent 3b6c766
commit 0d2431d
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 5 deletions.
diff --git a/docs/source/markdown/options/secret.image.md b/docs/source/markdown/options/secret.image.md
@@ -2,12 +2,22 @@
 ####>   podman build, farm build
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
-#### **--secret**=**id=id,src=path**
+#### **--secret**=**id=id[,src=*envOrFile*][,env=*ENV*][,type=*file* | *env*]**
 
-Pass secret information used in the Containerfile for building images
-in a safe way that are not stored in the final image, or be seen in other stages.
-The secret is mounted in the container at the default location of `/run/secrets/id`.
+Pass secret information to be used in the Containerfile for building images
+in a safe way that will not end up stored in the final image, or be seen in other stages.
+The value of the secret will be read from an environment variable or file named
+by the "id" option, or named by the "src" option if it is specified, or from an
+environment variable specified by the "env" option. See [EXAMPLES](#examples).
+The secret will be mounted in the container at `/run/secrets/id` by default.
 
-To later use the secret, use the --mount option in a `RUN` instruction within a `Containerfile`:
+To later use the secret, use the --mount flag in a `RUN` instruction within a `Containerfile`:
 
 `RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret`
+
+The location of the secret in the container can be overridden using the
+"target", "dst", or "destination" option of the `RUN --mount` flag.
+
+`RUN --mount=type=secret,id=mysecret,target=/run/secrets/myothersecret cat /run/secrets/myothersecret`
+
+Note: changing the contents of secret files will not trigger a rebuild of layers that use said secrets.
diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in
@@ -566,6 +566,23 @@ Build image using the specified network when running containers during the build
 $ podman build --network mynet .
 ```
 
+Build an image using a secret stored in an environment variable or file named `mysecret` to be used with the instruction `RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret`:
+```
+$ podman build --secret=id=mysecret .
+```
+
+Build an image using a secret stored in an environment variable named `MYSECRET` to be used with the instruction `RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret`:
+```
+$ podman build --secret=id=mysecret,env=MYSECRET .
+$ podman build --secret=id=mysecret,src=MYSECRET,type=env .
+```
+
+Build an image using a secret stored in a file named `.mysecret` to be used with the instruction `RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret`:
+```
+$ podman build --secret=id=mysecret,src=.mysecret .
+$ podman build --secret=id=mysecret,src=.mysecret,type=file .
+```
+
 ### Building a multi-architecture image using the --manifest option (requires emulation software)
 
 Build image using the specified architectures and link to a single manifest on successful completion: