Plug-and-play entrypoint to inject secrets directly into your application's environment variables.
- How it works
- Using whisper locally
- Including whisper in a Docker image
- Secret providers
- Filters
- Troubleshooting
Whisper must run as your application's entrypoint. This means that instead of running this command to start your application:
/bin/run-my-app
Run this instead:
whisper exec -- /bin/run-my-app
Whisper reads its environment variables, replaces references to secrets with the secrets' values, and passes the resulting variables to your application. Variables that are not references to secrets are passed as is. See Secret providers below for more details.
Environment variable values can also contain filters that transform the secret's value. See Filters below for more details.
Download the whisper
binary for your OS and architecture on the
project's releases page and put
the binary in your PATH.
For convenience, the whisper binary is also released as a Docker image. In your application's Dockerfile, simply add the following line:
COPY --from=ghcr.io/busser/whisper:latest /whisper /bin/whisper
And then change your image's entrypoint:
# from this:
ENTRYPOINT ["/bin/run-my-app"]
# to this:
ENTRYPOINT ["/bin/whisper", "exec", "--", "/bin/run-my-app"]
See examples/dockerfile for actual code.
Whisper supports fetching secrets from the following providers.
Whisper will fetch secrets from Azure Key Vault for all environment variables
that start with azkv:
. What follows the prefix should reference a secret.
Here are some examples:
azkv:example.vault.azure.net/secret-sauce
references the latest value of thesecret-sauce
secret in theexample
Key Vault.azkv:example.vault.azure.net/secret-sauce#5ddc29704c1c4429a4c53605b7949100
references a specific version of thesecret-sauce
secret in theexample
Key Vault.
Whisper uses the environment's default credentials to authenticate to Azure. You can set these credentials with the environment variables listed here, or with workload identity.
Whisper will fetch secrets from Google Cloud Platform's Secret Manager for all
environment variables that start with gcpsm:
. What follows the prefix should
reference a secret.
Here are some examples:
gcpsm:example/secret-sauce
references the latest value of thesecret-sauce
secret in theexample
project.gcpsm:example/secret-sauce#123
references a specific version of thesecret-sauce
secret in theexample
project.
Whisper uses the environment's default credentials to authenticate to Google
Cloud. You can set these with the gcloud
CLI, with environment variables,
with Google Cloud's environment service accounts, or with workload identity.
An alternative to whisper, specific to Google Cloud, is berglas.
Not yet supported.
You mat want to have a look at bank-vaults in the mean time.
Whisper will fetch secrets from AWS Secrets Manager for all environment
variables that start with awssm:
. What follows the prefix should reference a
secret.
Here are some examples:
awssm:secret-sauce
references the current value of thesecret-sauce
secret in the region and account defined by the environment.awssm:secret-sauce#9517cc59-646a-4393-81d7-5e6f2d43cbe7
references a specific version of thesecret-sauce
secret in the region and account defined by the environment.awssm:secret-sauce#my-label
references a specific staging label of thesecret-sauce
secret in the region and account defined by the environment.awssm:arn:aws:secretsmanager:us-east-1:123456789012:secret:secret-sauce-abcdef
references the secret with the specified ARN.awssm:arn:aws:secretsmanager:us-east-1:123456789012:secret:secret-sauce-abcdef#my-label
references a specific staging label of the secret with the specified ARN.
The string that comes after #
could be a version ID or a version label. If the
string is a UUID, then whisper assumes it is a version ID. Otherwise, it assumes
it is a version label.
Whisper uses the environment's default credentials to authenticate to AWS.
The passthrough:
prefix is special: it does not fetch secrets from anywhere.
Whisper uses the secret's reference as its value. In effect, this simply removes
the passthrough:
prefix from any environment variables.
Whisper supports transforming secrets with the following filters.
Whisper embeds the Kubernetes JSONPath
library. You can use it to extract specific fields from a JSON-encoded secret.
For example, if you have a secret with a value of {"sauce": "szechuan"}
, the
jsonpath
filter can extract the sauce
field's value:
awssm:secret-sauce|jsonpath:{.sauce}
Your application may use flags, like this:
whisper exec /bin/run-my-app --port=3000
Whisper then picks up the --port
flag and returns an error:
Error: unknown flag: --port
Whisper ignores any flags that come after a special --
argument. So simply run
this command instead:
whisper exec -- /bin/run-my-app --port=3000
Any flags after the --
argument will still be passed to your application.