summon is a command-line tool that reads a file in secrets.yml format and injects secrets as environment variables into any process. Once the process exits, the secrets are gone.
summon is not tied to a particular secrets source. Instead, sources are implemented as providers that summon calls to fetch values for secrets. Providers need only satisfy a simple contract and can be written in any language.
Running summon looks like this:
summon --provider conjur -f secrets.yml chef-client --once
summon resolves the entries in
secrets.yml with the
conjur provider and
makes the secret values available to the environment of the command
In our chef recipes we can access the secrets with Ruby’s
This same pattern works for any tooling that can access environment variables.
As a second example, Docker:
summon --provider conjur -f secrets.yml docker run --env-file @SUMMONENVFILE myapp
Full usage docs for summon are in the Github README for the project.
secrets.yml defines a format for mapping an environment variable to a location where a secret is stored. There are no sensitive values in this file itself. It can safely be checked into source control. Given a secrets.yml file, summon fetches the values of the secrets from a provider and provide them as environment variables for a specified process.
The format is basic YAML with an optional tag. Each line looks like this:
<key>: !<tag> <secret>
key is the name of the environment variable you wish to set.
tag sets a context for interpretation:
!varthe value of
keyis set to the the secret’s value, resolved by a provider given
!filewrites the literal value of
secretto a memory-mapped temporary file and sets the value of
keyto the file’s path.
!var:fileis a combination of the two. It will use a provider to fetch the value of a secret identified by
secret, write it to a temp file and set
keyto the temp file path.
If there is no tag,
<secret>is treated as a literal string and set as the value of
key. In this scenario, the value in the
<secret>should not actually be a secret, but rather a piece of metadata which is associated with secrets.
Here is an example:
AWS_ACCESS_KEY_ID: !var aws/$environment/iam/user/robot/access_key_id AWS_SECRET_ACCESS_KEY: !var aws/$environment/iam/user/robot/secret_access_key AWS_REGION: us-east-1 SSL_CERT: !var:file ssl/certs/private
$environment is an example of a substitution variable, given as an flag argument when running summon.
Summon is meant to work with your existing toolchains. If you can access environment variables, you can use Summon.
Here are some specific examples of how you can use summon with your current tools.
- AWS S3
- Chef encrypted data bags
- Keepass kdbx database file
- AWS Secrets Manager
Providers are easy to write. Given the identifier of a secret, they either return its value or an error.
This is their contract:
- They take one argument, the identifier of a secret (a string).
- If retrieval is successful, they return the value on stdout with exit code 0.
- If an error occurs, they return an error message on stderr and a non-0 exit code.
The default path for providers is
/usr/local/lib/summon/. If one provider is in that path,
summon will use it. If multiple providers are in the path, you can specify which one to use
--provider flag or the environment variable
SUMMON_PROVIDER. If your providers are
placed outside the default path, give summon the full path to them.
Open a Github issue if you’d like to include your provider on this page.