openstack/openstack-ansible-ops
Code Issues Proposed changes
Files
6a600eb981aeda03fb558efa2ba3f38af0fd6b20
openstack-ansible-ops/encrypt_secrets/README.rst
Dmitriy Rabotyagov 6a600eb981 Add a collection for managing encryption of secret data 
Best practices should referring to at least basic encryption of data
including SSH keypairs, PKI certificates, user_secrets, etc.

This collection aims to help/assist with managing data in encrypted
state, in case ansuble_vault is used as an encryption mechanism.

The collection should allow adding more supproted mechanism,
like SOPS for managing data encryption in the future.

Change-Id: I8af3118946682af4ec31bb1d4f6bea93be34f68c
2025-05-02 08:03:24 +00:00

4.4 KiB
Raw Blame History

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

../../encrypt_secrets/roles/ansible_vault/defaults/main.yml

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.

  1. Generate a password for the Ansible Vault and store it securely:
pwgen 36 1 > /tmp/vault.secret
  1. 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
  1. Copy the contents of /tmp/vault.secret to the deployment host, for example to /etc/openstack/vault.secret.
  2. Define the vault secret path in `/etc/openstack_deploy/user.rc`:
export ANSIBLE_VAULT_PASSWORD_FILE=/etc/openstack/vault.secret
  1. Store the password securely in your preferred password manager.
  2. Push the changes to your Git repository.
  3. 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:

  1. Generate a password and store it securely:
pwgen 36 1 > /etc/openstack/vault.secret
  1. Define the vault secret path in `/etc/openstack_deploy/user.rc`:
export ANSIBLE_VAULT_PASSWORD_FILE=/etc/openstack/vault.secret
  1. Run the encryption playbook:
openstack-ansible osa_ops.encrypt_secrets.ansible_vault
  1. Commit and push changes to /etc/openstack_deploy in your Git repository.
  2. Save the vault password (/etc/openstack/vault.secret) in a secure password manager.
  3. 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:

  1. Generate a new vault password/encryption key:
pwgen 45 1 > /tmp/vault.secret.new
  1. 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
  1. Transfer the new password to the deployment host and store it securely in a password manager.