overview

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 chef-client --once. In our chef recipes we can access the secrets with Ruby's ENV['...'] syntax.

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

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:

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.

examples

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 oss@conjur.net.

providers

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 with the --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.