Managing secrets
Each Azimuth environment contains a small number of files and variable values that must be kept secret. However we would also like to have these files and variables in version control so that we can track when they have changed and share them with others in our team.
The way to achieve both these goals is to encrypt the secrets when at rest in the Git repository. For an Azimuth configuration repository, the recommended method for doing this is using git-crypt.
git-crypt provides transparent encryption and decryption of files in a Git repository
using Git filters. This
allows for a mix of encrypted and unencrypted content in the same repository, which is
exactly what we want for an Azimuth configuration.
By encrypting files when they are committed and decrypting them when they are checked
out, git-crypt allows you to work as if the encryption is not present while being
confident that your secrets remain private. Team members can also work on the public
parts of the repository without decrypting the private parts if you wish to maintain
separation of privilege.
git-crypt works on entire files, not at the variable level, so it is recommended
that encrypted files contain only secret values so that information is not hidden
unnecessarily. To this end, a typical azimuth-config environment for a site will
have one or more group_vars files in the inventory that are unencrypted, but
secret values will be placed in a secrets.yaml that is encrypted.
Initialising git-crypt
To initialise git-crypt for your config repository, first make sure that the CLI
is installed. This can be installed using the package manager on most major Linux
operating systems, using Homebrew on Mac OSX or by
building from source.
Then execute the following command to begin encrypting files:
Danger
If you lose access to the key that git-crypt generates to encrypt your repository,
you will be locked out of the repository for good.
It is recommended that you export the key (see below) and store it somewhere safe, e.g. in your organisation's secret store.
Verifying which files are encrypted
azimuth-config contains a .gitattributes file that ensures all clouds.yaml,
secrets.yaml, env.secret and TLS key files in the repository will be encrypted (except those
for the example environment). If required, you can add additional patterns to the
file to encrypt other files.
You can check the files that git-crypt is encrypting using the following command:
Granting access to others
As mentioned above, team members can work on the public parts of the repository
without decrypting the encrypted files. However in order to make a deployment, the
secrets must be decrypted - git-crypt refers to this process as "unlocking".
Using a shared secret key
The simplest way to grant access to the encrypted files in a repository is by sharing
the secret key generated by git-crypt. The key is binary, so the best way to share
the key is by base64-encoding it:
To unlock the repository you must first clone it, then use the key to unlock it:
# Clone the repository
git clone $REPOSITORY_URL
# Move into the repository directory
cd $REPOSITORY_DIR
# Unlock it using the base64-encoded key
echo $GIT_CRYPT_KEY_B64 | base64 -d | git-crypt unlock -
Using GPG keys
git-crypt is also able to grant access to the repository using
GPG keys. This avoids the use of shared secrets and makes it
explicit in the repository who has access.
A full discussion of the use of GPG is beyond the scope of this documentation, including the generation of keys, as it differs substantially depending on your operating system.
To add a GPG key to your repository, use the following command:
where USER_ID is a key ID, a full fingerprint, an email address, or anything else that
uniquely identifies a public key to GPG.
You will then need to push the changes to the repository that encode the user's access:
To unlock a repository using your GPG identity, just execute:
Created: March 22, 2024