Secrets
Secrets are sensitive data that should not be stored in the Earthfile. For example, a password or an API key. Secrets are similar to build arguments, but they are not stored in the Earthfile and are not cached.
Access to secrets is declared explicitly in the commands that need them.
Passing secrets to RUN commands
Here's an example Earthfile that accesses a secret stored under passwd and exposes it under the environment variable mypassword:
FROM alpine:latest
hush:
RUN --secret mypassword=passwd echo "my password is $mypassword"If the environment variable name is identical to the secret ID. For example to accesses a secret stored under passwd and exposes it under the environment variable passwd you can use the shorthand :
FROM alpine:latest
hush:
RUN --secret passwd echo "my password is $passwd"Setting secret values
The value for passwd in examples above must then be supplied when earth is invoked.
This is possible in a few ways:
Directly, on the command line:
Via an environment variable:
If the value of the secret is omitted on the command line EarthBuild will lookup the environment variable with that name.
Via the environment variable
EARTH_SECRETSMultiple secrets can be specified by separating them with a comma.
Via the
.secretfile.Create a
.secretfile in the same directory where you plan to runearthfrom. Its contents should be:Then simply run earth:
Via your own secret manager. To share secrets across a team, fetch them from a system you control (for example HashiCorp Vault, AWS Secrets Manager, or your CI provider's secret store) and pass them in using one of the approaches above.
Regardless of the approach chosen from above, once earth is invoked, in our example, it will output:
How Arguments and Secrets affect caching
Commands in earth must be re-evaluated when the command itself changes (e.g. echo "hello $name" is changed to echo "greetings $name"), or when one of its inputs has changed (e.g. --name=world is changed to --name=banana). EarthBuild creates a hash based on both the contents of the command and the contents of all defined arguments of the target build context.
However, in the case of secrets, the contents of the secret is not included in the hash; therefore, if the contents of a secret changes, EarthBuild is unable to detect such a change, and thus the command will not be re-evaluated.
Storage of local secrets
EarthBuild stores the contents of command-line-supplied secrets in memory on the localhost. When a RUN command that requires a secret is evaluated by BuildKit, the BuildKit daemon will request the secret from the earth command-line process and will temporarily mount the secret inside the runc container that is evaluating the RUN command. Once the command finishes the secret is unmounted. It will not persist as an environment variable within the saved container snapshot. Secrets will be kept in-memory until the earth command exits.
Secrets are never written to disk by EarthBuild, and never leave the machine running the build.
Last updated