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 is the name of the environment variable you wish to set.
tag sets a context for interpretation:
!var the value of
key is set to the the secret's value, resolved by a provider given
!file writes the literal value of
secret to a memory-mapped temporary
file and sets the value of
key to the file's path.
!var:file is a combination of the two. It will use a provider to fetch the value of a secret
secret, write it to a temp file and set
key to the temp file path.
If there is no tag,
<secret> is treated as a literal string and set as the value of
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.
Let us know what tools you would like us to cover next at firstname.lastname@example.org.
Providers are easy to write. Given the identifier of a secret, they either return its value or an error.
This is their contract:
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.Summon is maintained by conjurinc. This page was generated by GitHub Pages using the Cayman theme by Jason Long.