Data Operations

There are three operations which are used as part of Operational Secret lifecycle management. These actions help provide what we believe are safe practices around managing these secrets in a delivery pipeline.

The seed action will provision a Vault server with defined data. This may optionally use a encrypted icefile.
The freeze action will generate an encrypted file (icefile) suitable for cold storage of secrets
The thaw action will extract an icefile for modification
The diff action shows what will change
You can export secrets into a local directory

Common Arguments

These operations all have some shared constructs which allow the user a fair amount of flexibility. Much of the opinionless aspects of aomi are handled by these options.

About File Paths

By default the Secretfile is searched for in the current directory. You can override this behavior with the --secretfile option.

Supplemental data is loaded from relative paths by default. If files are not found at the relative (but tunable) path, the data will be loaded as an absolute path.

All Vault and AWS policy files will be searched for first in a relative location. This relative “metadata directory” defaults to vault adjacent to the Secretfile however you may override it with --policies.

All files containing secrets referenced from the Secretfile will be searched for in an adjacent “secret directory” named .secrets. You are able to override the directory used for static secrets with the --secrets option.

AdHoc Path Selection

You can include or exclude paths from execution on a one-off basis with the --include and --exclude options. This can be used to fine tune an aomi seed operation without having to permanently modify a Secretfile with tags. Note that exclude takes priority over include.

diff

The diff command will go through the Secretfile and report on what would be changed by a seed operation. Note that you need to be logged in, and already have appropriate permissions. The diff command can be executed with no arguments, and it will look for everything in the current working directory. The diff command takes the --secretfile, --policies, and --secrets options.

Differences will be reported in a human readable fashion according annotated depending on the action required.

A green + indicates a new Vault resource will be created
A red -indicates a Vault resource will be removed
A yellow ~ indicates a Vault resource will be changed
A yellow + indicates a write-only Vault resource will be overwritten
Vault resources for which there is no change are not mentioned

seed

The seed command will go through the Secretfile and appropriately provision Vault. Note that you need to be logged in, and already have appropriate permissions. The seed command can be executed with no arguments, and it will look for everything in the current working directory. The seed command takes the --secretfile, --policies, and --secrets options. The --mount-only option ensures that backends are attached and does not actually writing anything to Vault.

It is possible to have aomi clean up unrecognzied Vault mount points. Note that by doing this, any mount point that is not defined in the fully rendered Secretfile will be unmounted. This causes non-recoverable data from the perspective of Vault. Care should be taken to back up your data using freeze and thaw prior to using this option. It may be enabled by specifying --remove-unknown.

The Secretfile is interpreted as a Jinja2 template, and you can pass in --extra-vars and --extra-vars-file to seed. This opens up some possibilities for bulk-creating sets of credentials based on integrations with other systems, while still preserving various paths and structures. The files passed to --extra-vars-file will be interpreted in order, with each being merged subsequently. They are also treated as templates prior to being interpreted as YAML.

The seed command will make some sanity checks as it goes. One of these is to check for the presence of the secrets directory within your .gitignore. As this directory can contain plaintext secrets, it should never be committed. A recommended alternative is to specify an icefile with the --thaw-from option. When doing this, plain text secrets are only accessible in the clear during the seed operation and are removed immediately after.

freeze

The freeze action will go through the Secretfile and extract specified secrets from the local file system into an encrypted zip file. This file is known as an icefile, because it sounds cool. You can specify tags, or include/exclude paths. In order to make use of freeze you must specify a list of either Keybase or GPG fingerprints in the Secretfile under the pgp_keys section. All the options supported by seed for selection of secrets and file paths are supported with this operation.

If you wish to have a static prefix for the icefiles, you may specify it with the --icefile-prefix option. The default behavior is for the filename prefix to be computed based on the working directory.

Secretfile

pgp_keys:
- 'keybase:otakup0pe'
- 'B1234ABC'

This example will generate an icefile in the /tmp directory.

$ aomi freeze /tmp

thaw

The thaw action will take a generated icefile and thaw it into the configured “secrets” directory. This operation will take all of the options that seed accepts with regards to file paths and secret selection.

This example will thaw the named icefile into the default “secrets” directory.

$ aomi thaw /tmp/aomi-example-000000-01-01-2017.ice

export

The export action will go through a Secretfile and read out any readable secret from the Vault server. Note that some paths are write only and thus the information is not retrievable. Examples of this are the root path for the AWS backend or the password of a userpass user. This operation takes the --secretfile, --policies, and --secrets directory options along with --extra-vars and --extra-vars-file options.

$ aomi export /tmp/secrets

Errata

Note that actions which rely on GPG (freeze/thaw/seed with --thaw-from) are not really working well in Docker yet.

aomi

Opinionlessly Express Opinions on Vault