Encrypting secrets¶
This document describes the supported operations for encrypting secrets and explains how to perform them using the appropriate tooling.
Ansible-Vault¶
OpenStack-Ansible provides tooling to encrypt and rotate secret files and keypairs using Ansible Vault.
Role Defaults¶
# Allowed values: "encrypt", "decrypt" and "rotate"
ansible_vault_action: encrypt
# Path to the OpenStack-Ansible configuration (openstack_deploy) folder
ansible_vault_repo_path: "{{ lookup('ansible.builtin.env', 'OSA_CONFIG_DIR') | default(lookup('ansible.builtin.env', 'PWD') ~ '/openstack_deploy', True) }}"
# Name of the region, which will be used as vault id
ansible_vault_region: "{{ service_region | default('RegionOne') }}"
# Path to the ansible-vault password file
ansible_vault_pw: "{{ lookup('ansible.builtin.env', 'ANSIBLE_VAULT_PASSWORD_FILE') }}"
# Path to the freshly generated ansible-vault password file. Used for rotation only
ansible_vault_new_pw: "{{ ansible_vault_pw ~ '.new' }}"
# If in-place copy is enabled, role will completely override the resulting file
# When disabled, Ansible will produce a managed block for each managed variable
ansible_vault_in_place_copy: true
# Paths to files, where individual variables needs to be encrypted
ansible_vault_secrets_paths:
- "{{ ansible_vault_repo_path }}/user_secrets.yml"
- "{{ ansible_vault_repo_path }}/group_vars/all/secrets.yml"
# Instead of defining paths to files explicitly, you can search filesystem for
# files with individually encrypted secrets. Results will be combined with
# `ansible_vault_secrets_paths`
ansible_vault_secrets_search_paths: []
ansible_vault_secrets_search_pattern: "secrets.yml"
# Can be overriden to a specific destination in case venv is not activated
ansible_vault_binary: ansible-vault
Installing the Collection¶
To install the collection, define it in your region deployment configuration file, located at /etc/openstack_deploy/user-collection-requirements.yml, as shown below:
- name: osa_ops.encrypt_secrets
type: git
version: master
source: https://opendev.org/openstack/openstack-ansible-ops#/encrypt_secrets
Then, run ./scripts/bootstrap-ansible.sh to install the collection.
Initial Encryption of Secret Files¶
When initializing a region for the first time, you should encrypt secrets and generated private keys before storing them in Git. You can perform this process locally or on the deployment host.
Note
You must re-run the encryption process whenever new services or keypairs are generated, which may occur at later deployment stages.
Encrypting Secrets Locally¶
The process for encrypting secrets locally is similar to running it on the deploy host, but some context-specific variables required by OpenStack-Ansible may be unavailable and must be supplied manually.
Ensure you have a Python virtual environment with Ansible installed before proceeding.
Generate a password for the Ansible Vault and store it securely:
pwgen 36 1 > /tmp/vault.secret
Run the encryption playbook:
ansible-playbook osa_ops.encrypt_secrets.ansible_vault -e ansible_vault_region=${REGION_NAME} -e ansible_vault_pw=/tmp/vault.secret
Copy the contents of /tmp/vault.secret to the deployment host, for example to /etc/openstack/vault.secret.
Define the vault secret path in /etc/openstack_deploy/user.rc:
export ANSIBLE_VAULT_PASSWORD_FILE=/etc/openstack/vault.secret
Store the password securely in your preferred password manager.
Push the changes to your Git repository.
Ensure that the deploy host decrypts any required secrets.
Encrypting Secrets on the Deployment Host¶
Follow these steps to encrypt secrets directly on the deployment host:
Generate a password and store it securely:
pwgen 36 1 > /etc/openstack/vault.secret
Define the vault secret path in /etc/openstack_deploy/user.rc:
export ANSIBLE_VAULT_PASSWORD_FILE=/etc/openstack/vault.secret
Run the encryption playbook:
openstack-ansible osa_ops.encrypt_secrets.ansible_vault
Commit and push changes to /etc/openstack_deploy in your Git repository.
Save the vault password (/etc/openstack/vault.secret) in a secure password manager.
Decrypt any necessary secrets before running OpenStack playbooks.
Decrypting Keypairs on the Deploy Host¶
The OpenStack-Ansible PKI role does not support storing private keys in encrypted format on the deployment host. Instead, configure a pipeline that decrypts the keys after placing them on the deploy host.
Encrypted keypairs should be committed to the Git repository, but stored unencrypted on the deployment host.
To decrypt them, run the following playbook:
openstack-ansible osa_ops.encrypt_secrets.ansible_vault -e ansible_vault_action=decrypt
Rotating the Ansible Vault Secret¶
Rotating the Ansible Vault password requires re-encrypting all secrets in the repository. Assuming the original password is stored in /tmp/vault.secret, follow these steps:
Generate a new vault password/encryption key:
pwgen 45 1 > /tmp/vault.secret.new
Re-encrypt all secrets using the new password:
ANSIBLE_VAULT_PASSWORD_FILE=/tmp/vault.secret ansible-playbook osa_ops.encrypt_secrets.ansible_vault -e ansible_vault_action=rotate
Transfer the new password to the deployment host and store it securely in a password manager.
