5.2.3.5 Secret Non Persistence
A focused guide to Secret Non Persistence, connecting core concepts with practical Docker and container operations.
Secret non-persistence is the specific property of BuildKit secret mounts that guarantees a secret's value never becomes part of any image layer, regardless of how that secret is used within the single instruction it's mounted for — a guarantee fundamentally different from how ordinary COPYed or ARG-supplied data behaves.
How Ordinary Build Data Persists
Anything copied into an image, or used in a way that affects filesystem state, becomes part of a layer and persists in the image's history indefinitely, even if a later instruction attempts to remove or overwrite it.
COPY secret.txt /tmp/secret.txt
RUN process-secret.sh /tmp/secret.txt
RUN rm /tmp/secret.txt
Despite the explicit removal in the final instruction, the secret's content still exists in the earlier layer that copied it in, fully recoverable by anyone with access to the image.
Why Secret Mounts Behave Fundamentally Differently
A secret mount is never written to any layer at all — it exists only as a temporary mount within the container's filesystem during a single instruction's execution, with no corresponding layer ever capturing its content.
RUN --mount=type=secret,id=my_secret process-secret.sh /run/secrets/my_secret
No layer in the resulting image contains this secret's content, regardless of what process-secret.sh actually does with it internally (assuming the script itself doesn't separately write the secret somewhere persistent).
A Caveat Worth Understanding
If the instruction using a secret mount itself writes that secret's value into a persistent location within the image — logging it to a file that gets copied elsewhere, for instance — the non-persistence guarantee can still be undermined by that specific action, since the guarantee covers the mount mechanism itself, not arbitrary things a script might choose to do with the value.
RUN --mount=type=secret,id=my_secret sh -c 'cat /run/secrets/my_secret > /app/config.txt'
This defeats the protection entirely, since the script itself persists the secret's value into a file that does become part of a layer.
Why Secret Non-Persistence Matters
Understanding precisely what BuildKit's non-persistence guarantee covers — and what it does not — is essential for using secret mounts correctly, since the mechanism itself is safe by design but can still be undermined by careless handling within the instruction that uses it.