Managing Secrets

Unfurl allows you to store secrets separately from the rest for your configuration, either in separate configuration file or in a secrets manager such as HashiCorp Vault. In the project configuration file you specify how those secrets should be managed. You can apply the following strategies:

  • Store the secrets in a local configuration file and distribute that file out-of-band if necessary.

  • Encrypt the secrets file using Ansible Vault so they can be safely checked into the ensemble repository.

  • Store them in a secrets manager such as HashiCorp Vault or Amazon Secrets Manager or your OS’s keyring. You can use any secrets manager that has an Ansible Lookup Plugin available for it.

  • If your ensemble repository is private and the secrets not highly sensitive you can just commit it into the repository in plain text.

You can apply any of these techniques to different secrets and projects can inherit the secrets configuration from unfurl_home.


    # Include secrets from a file that will be automatically encrypted when committed to the repository:
    +?include: secrets/secrets.yaml

    # include secrets from a file that will not be committed to the repository:
    +?include: local/secrets.yaml

    # plaintext:
    not_so_secret: admin

    # encrypted inlined:
    the_dev_secret: !vault |
    # if secret isn't defined above look it up in a HashiCorp Vault instance
    # (assumes VAULT_TOKEN etc. environment variables are set)
    default: "{{ lookup('hashi_vault', 'secret='+key) }}" # "key" will be set to the secret name

Sensitive Values

You can mark configuration data as sensitive. If you have Ansible Vault ids associated with your ensemble that will be saved encrypted, if not, they will be saved as “<<<Redacted>>>”. When loading a YAML configuration file, any Vault data will be decrypted and any attribute with a value of “<<<Redacted>>>” will be omitted. By default, unfurl init will generate a random Ansible Vault key to your local secrets (found in local/unfurl.yaml) and so any data marked sensitive will be encrypted.


Store this master Vault password found in local/unfurl.yaml in a safe place!

Creating secrets

When unfurl commit commits changes to a project, any files in directories named secrets will automatically be encrypted with the project’s vault password and committed into a parallel directory named .secrets. When Unfurl starts it will automatically decrypt those files and restore them to their secrets directory.

To create secrets manually (for example, to use inline as shown in the example above), you can use the unfurl-vault-client script with the ansible-vault command. The unfurl-vault-client script outputs the vault password for the current project so you can encrypt secrets using the ansible-vault utility like this:

ansible-vault encrypt_string --vault-id default@unfurl-vault-client "secret1" "secret2"