Contexts generation

The central part of secenv and the main purpose of its existence, is to generate contexts.

Contexts are basically lists of variables that are read from secrets defined in various stores.

To define a context, use the following code:

contexts:
  my_context: {}

Now, to list the available contexts, run:

$ secenv contexts
my_context

Variables

Variables, in a context, can come from multiple sources. They can be passed raw, or coming from a store.

To define variables, use the following code:

contexts:
  my_context:
    vars:
      raw_var: raw_value

      store_var:
        store: my_store
        secret: my_secret

Now, generate the context my_context by running:

$ secenv context my_context
export raw_var='raw_value'
export store_var='...'

For some stores, secrets can be either a raw value (i.e. file content), or a key-value store like a JSON file (i.e. in AWS). To use a specific key in a secret, use the following code:

contexts:
  my_context:
    vars:
      store_var:
        store: my_store
        secret: my_secret
        key: my_key

For Hashicorp Vault, it is possible to specify the engine to use, to do so, use:

contexts:
  my_context:
    vars:
      store_var:
        store: my_vault_store
        secret: my_secret
        engine: my_engine

It is possible to mimic the context generation to retrieve a single variable by running:

$ secenv secrets get my_store my_secret [--engine my_engine] [--key my_key]
...

AWS Assume role

Contexts can also generate AWS credentials to assume a role in the current context. To do so, add the following code:

contexts:
  my_context:
    aws_assume_role:
      # Give the access key ID directly
      aws_access_key_id: <aws_access_key_id>
      # Retrieve the secret access key from a secret
      aws_secret_access_key:
        store: my_store
        secret: my_secret
      # Read the role from a key in another secret
      role_arn:
        store: my_store
        secret: my_secret
        key: my_key

Unlike the stores, it is not possible to configure the access keys through environment variables. The keys have to be either in the configuration file itself, or read from a secret.

We highly recommend the latter as credentials MUST NOT be committed in a repository.

Now, generate the context:

$ secenv context my_context
export AWS_ACCESS_KEY_ID='...'
export AWS_SECRET_ACCESS_KEY='...'
export AWS_SESSION_TOKEN='...'

Extend and inherit

A context can extend another one, it means the extending context will have the variables of the extended one. If it extends multiple contexts, it is just like each context extended the one before, until the last one.

Here is how to do this:

contexts:
  default:
    vars:
      my_var: my_value
      my_var2: my_value2

  extend1:
    extends:
      - default
      # my_var and my_var2 are inherited
    vars:
      my_var2: my_value3
      # my_var2 is overridden

  extend2:
    extends:
      - default
      # my_var and my_var2 are inherited
      - extend1
      # my_var2 is overridden
    vars:
      my_var: my_value4
      # my_var is overridden

Now, generate the different contexts:

$ secenv contexts gen default
export my_var='my_value'
export my_var2='my_value2'

$ secenv contexts gen extend1
export my_var='my_value'
export my_var2='my_value3'

$ secenv contexts gen extend2
export my_var='my_value4'
export my_var2='my_value3'

Outputs format

By default, secenv will format the output to be sourced by a shell. It is possible to use a format that will be consumed another way.

To do so, use the --output-format option with one of the following formats:

• shell: (default) in the format export VAR='VALUE'
• dotenv: in the format VAR='value'
• github_actions: in the format echo 'VAR=VALUE' >> $GITHUB_ENV

Note that for the github_actions format, the values are masked by default. This behavior can be disabled by using the sensitive parameter. To do so, use the following code:

contexts:
  my_context:
    vars:
      my_var:
        store: my_store
        secret: my_secret
        sensitive: false

This parameter is ignored by the other output formats.

Now generate the context:

$ secenv contexts gen my_context
export my_var='...'

$ secenv contexts gen -o dotenv my_context
my_var='...'

$ secenv contexts gen -o github_actions my_context
echo 'my_var=...' >> $GITHUB_ENV
# If sensitive: false is not given
echo '::add-mask::my_var'