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.
seedaction will provision a Vault server with defined data. This may optionally use a encrypted icefile.
freezeaction will generate an encrypted file (icefile) suitable for cold storage of secrets
thawaction will extract an icefile for modification
diffaction shows what will change
- You can
exportsecrets into a local directory
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
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
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
You may tag individual policies, appids, and secrets. When resources have tags, and the
seed command is run with the
--tags option, only matching items will be seeded. If the
--tags option is not specified, then only things which do not have tags specified will be seeded.
AdHoc Path Selection
You can include or exclude paths from execution on a one-off basis with the
--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.
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
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
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
--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
thaw prior to using this option. It may be enabled by specifying
Secretfile is interpreted as a Jinja2 template, and you can pass in
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.
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 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.
pgp_keys: - 'keybase:otakup0pe' - 'B1234ABC'
This example will generate an icefile in the
$ aomi freeze /tmp
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 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
--secrets directory options along with
$ aomi export /tmp/secrets
Note that actions which rely on GPG (
--thaw-from) are not really working well in Docker yet.