Merge "Add a collection for managing encryption of secret data"

Author: Zuul

.gitignore

@@ -45,6 +45,7 @@ logs/*
 # OS generated files #
 ######################
 ._*
+.ansible
 .tox
 *.egg-info
 .eggs

doc/source/encrypt_secrets.rst

@@ -0,0 +1,2 @@
+
+.. include:: ../../encrypt_secrets/README.rst

doc/source/index.rst

@@ -8,6 +8,7 @@ OpenStack-Ansible Operator Tooling
    swift_storage_mount_drives
    elk_metrics
    mcapi
+   encrypt_secrets
 
 OpenStack-Ansible Diff Generator
 --------------------------------

encrypt_secrets/README.rst

@@ -0,0 +1,131 @@
+==================
+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
+-------------
+
+.. literalinclude:: ../../encrypt_secrets/roles/ansible_vault/defaults/main.yml
+   :language: yaml
+   :start-after: under the License.
+
+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:
+
+.. code-block:: yaml
+
+  - 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:
+
+.. code-block:: bash
+
+  pwgen 36 1 > /tmp/vault.secret
+
+2. Run the encryption playbook:
+
+.. code-block:: bash
+
+  ansible-playbook osa_ops.encrypt_secrets.ansible_vault -e ansible_vault_region=${REGION_NAME} -e ansible_vault_pw=/tmp/vault.secret
+
+3. Copy the contents of `/tmp/vault.secret` to the deployment host, for example to `/etc/openstack/vault.secret`.
+4. Define the vault secret path in `/etc/openstack_deploy/user.rc`:
+
+.. code-block:: bash
+
+  export ANSIBLE_VAULT_PASSWORD_FILE=/etc/openstack/vault.secret
+
+5. Store the password securely in your preferred password manager.
+6. Push the changes to your Git repository.
+7. 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:
+
+.. code-block:: bash
+
+  pwgen 36 1 > /etc/openstack/vault.secret
+
+2. Define the vault secret path in `/etc/openstack_deploy/user.rc`:
+
+.. code-block:: bash
+
+  export ANSIBLE_VAULT_PASSWORD_FILE=/etc/openstack/vault.secret
+
+3. Run the encryption playbook:
+
+.. code-block:: bash
+
+  openstack-ansible osa_ops.encrypt_secrets.ansible_vault
+
+4. Commit and push changes to `/etc/openstack_deploy` in your Git repository.
+5. Save the vault password (`/etc/openstack/vault.secret`) in a secure password manager.
+6. 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:
+
+.. code-block:: bash
+
+  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:
+
+.. code-block:: bash
+
+  pwgen 45 1 > /tmp/vault.secret.new
+
+2. Re-encrypt all secrets using the new password:
+
+.. code-block:: bash
+
+  ANSIBLE_VAULT_PASSWORD_FILE=/tmp/vault.secret ansible-playbook osa_ops.encrypt_secrets.ansible_vault -e ansible_vault_action=rotate
+
+3. Transfer the new password to the deployment host and store it securely in a password manager.

encrypt_secrets/galaxy.yml

@@ -0,0 +1,61 @@
+### REQUIRED
+# The namespace of the collection. This can be a company/brand/organization or product namespace under which all
+# content lives. May only contain alphanumeric lowercase characters and underscores. Namespaces cannot start with
+# underscores or numbers and cannot contain consecutive underscores
+namespace: osa_ops
+
+# The name of the collection. Has the same character restrictions as 'namespace'
+name: encrypt_secrets
+
+# The version of the collection. Must be compatible with semantic versioning
+version: 0.1.0
+
+# The path to the Markdown (.md) readme file. This path is relative to the root of the collection
+readme: README.md
+
+# A list of the collection's content authors. Can be just the name or in the format 'Full Name <email> (url)
+# @nicks:irc/im.site#channel'
+authors:
+- Dmitriy Rabotyagov <[email protected]>
+
+
+### OPTIONAL but strongly recommended
+# A short summary description of the collection
+description: Encrypt and manage encrypted files for OpenStack-Ansible
+
+# Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only
+# accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file'
+license:
+- Apache-2.0
+
+# The path to the license file for the collection. This path is relative to the root of the collection. This key is
+# mutually exclusive with 'license'
+license_file: ''
+
+# A list of tags you want to associate with the collection for indexing/searching. A tag name has the same character
+# requirements as 'namespace' and 'name'
+tags: []
+
+# Collections that this collection requires to be installed for it to be usable. The key of the dict is the
+# collection label 'namespace.name'. The value is a version range
+# L(specifiers,https://python-semanticversion.readthedocs.io/en/latest/#requirement-specification). Multiple version
+# range specifiers can be set and are separated by ','
+dependencies: {}
+
+# The URL of the originating SCM repository
+repository: https://opendev.org/openstack/openstack-ansible-ops
+
+# The URL to any online docs
+documentation: https://docs.openstack.org/openstack-ansible-ops
+
+# The URL to the homepage of the collection/project
+homepage: https://docs.openstack.org/openstack-ansible
+
+# The URL to the collection issue tracker
+issues: https://bugs.launchpad.net/openstack-ansible
+
+# A list of file glob-like patterns used to filter any files or directories that should not be included in the build
+# artifact. A pattern is matched from the relative path of the file or directory of the collection directory. This
+# uses 'fnmatch' to match the files or directories. Some directories and files like 'galaxy.yml', '*.pyc', '*.retry',
+# and '.git' are always filtered
+build_ignore: []

encrypt_secrets/molecule/default/converge.yml

@@ -0,0 +1,11 @@
+---
+
+- name: Encrypt secrets
+  hosts: encrypt-default
+  tasks:
+
+    - name: Importing ansible_vault role
+      ansible.builtin.import_role:
+        name: ansible_vault
+      vars:
+        ansible_vault_action: encrypt

encrypt_secrets/molecule/default/molecule.yml

@@ -0,0 +1,55 @@
+---
+dependency:
+  name: galaxy
+  options:
+    requirements-file: requirements.yml
+
+driver:
+  name: docker
+
+platforms:
+  - name: "encrypt-${MOLECULE_SCENARIO_NAME}"
+    image: "${DOCKER_REGISTRY:-quay.io/gotmax23}/${DOCKER_IMAGE_TAG:-debian-systemd:bookworm}"
+    command: ${DOCKER_COMMAND:-""}
+    pre_build_image: true
+    privileged: true
+    systemd: true
+
+provisioner:
+  name: ansible
+  lint:
+    name: ansible-lint
+  env:
+    ANSIBLE_ROLES_PATH: ../../roles
+  inventory:
+    group_vars:
+      all:
+        ansible_vault_repo_path: /etc/openstack_deploy
+        ansible_vault_pw: /etc/openstack_deploy/vault_pw
+        ansible_vault_region: molecule
+        _molecule_password_mapping:
+          keystone_container_mysql_password: oequ0iejahgh8amaiy3Qua1Moo3weicaazo4
+          keystone_auth_admin_password: chaumei2Hoh5eisiesaip5goodees9eesahs
+          keystone_oslomsg_rpc_password: ei6Ooraenuavahleijuv3oos7asheih6Aidi
+  config_options:
+    defaults:
+      inject_facts_as_vars: false
+
+scenario:
+  name: default
+  test_sequence:
+    - dependency
+    - cleanup
+    - destroy
+    - syntax
+    - create
+    - prepare
+    - converge
+    - idempotence
+    # NOTE: We don't use side-effect due to bug preventing to define multiple of them:
+    #       https://github.com/ansible/molecule/issues/3617
+    - verify verify_converge.yml
+    - verify verify_rotate.yml
+    - verify verify_decrypt.yml
+    - cleanup
+    - destroy

encrypt_secrets/molecule/default/prepare.yml

@@ -0,0 +1,54 @@
+---
+- name: Generate data for role verification
+  hosts: encrypt-default
+  tasks:
+    - name: Install required packages
+      ansible.builtin.package:
+        name:
+          - python3-cryptography
+          - ansible-core
+        update_cache: "{{ (ansible_facts['os_family'] | lower == 'debian') | ternary(true, omit) }}"
+
+    - name: Create required directories
+      ansible.builtin.file:
+        path: "{{ item }}"
+        state: directory
+        recurse: true
+        mode: "0755"
+      loop:
+        - /etc/openstack_deploy/pki/certs/private
+        - /etc/openstack_deploy/pki/certs/certs
+        - /etc/openstack_deploy/pki/roots/TestRoot/private
+        - /etc/openstack_deploy/ssh_keypairs
+
+    - name: Generate ansible-vault secrets to use for data encryption
+      ansible.builtin.copy:
+        content: "{{ item.content }}"
+        dest: "{{ item.dest }}"
+        mode: "0600"
+      loop:
+        - dest: /etc/openstack_deploy/vault_pw
+          content: "{{ lookup('ansible.builtin.password', '/dev/null', chars=['ascii_lowercase', 'digits'], length=32) }}"
+        - dest: /etc/openstack_deploy/vault_pw.new
+          content: "{{ lookup('ansible.builtin.password', '/dev/null', chars=['ascii_lowercase', 'digits'], length=32) }}"
+        - dest: /etc/openstack_deploy/user_secrets.yml
+          content: |
+            ---
+            {{ _molecule_password_mapping | to_yaml }}
+
+    - name: Generate private keys
+      community.crypto.openssl_privatekey:
+        path: "{{ item }}"
+      loop:
+        - /etc/openstack_deploy/pki/certs/private/noop.key.pem
+        - /etc/openstack_deploy/pki/roots/TestRoot/private/TestRoot.key.pem
+
+    - name: Generate test certificate
+      community.crypto.x509_certificate:
+        path: /etc/openstack_deploy/pki/certs/certs/noop.crt
+        privatekey_path: /etc/openstack_deploy/pki/certs/private/noop.key.pem
+        provider: selfsigned
+
+    - name: Generate ssh keypair
+      community.crypto.openssh_keypair:
+        path: /etc/openstack_deploy/ssh_keypairs/noop_keypair