Add Barbican adoption framework for Proteccio HSM environments

Implement a comprehensive adoption framework for migrating Barbican service from OpenStack 17.1 to RHOSO 18 while preserving Proteccio Hardware Security Module (HSM) integration.

This PR introduces a specialized adoption role and supporting infrastructure for environments that use Proteccio HSM with Barbican key management service. The standard data-plane-adoption framework does not support HSM backends, making this specialized approach necessary to preserve HSM integration and access to existing secrets.

Key Components
1. Core Adoption Role (`barbican_proteccio_adoption`)
2. User-Friendly Execution Script
3. Security-Hardened Configuration

Adoption Phases
1. **Phase 1 (Preparation)**: Extract source configuration and validate environment
2. **Phase 2 (Base Deployment)**: Deploy RHOSO 18 with standard images
3. **Phase 3 (Database Adoption)**: Migrate Barbican database and execute HSM role
4. **Phase 4 (Proteccio Deployment)**: Deploy custom images and HSM configuration
5. **Phase 5 (Verification)**: Validate adoption success and API functionality

Execution Approaches
- **Primary**: `./run_proteccio_adoption.sh` (user-friendly with validation)
- **Alternative**: Direct `ansible-playbook` execution (advanced users/troubleshooting)

Fixes: OSPRH-18981

Signed-off-by: Mauricio Harley <[email protected]>

Author: Mauricio Harley

tests/config.env.sample

@@ -0,0 +1,25 @@
+# Sample configuration file for run_proteccio_adoption.sh
+# Copy this file to config.env and customize for your environment
+
+# Base directory for Proteccio adoption files
+# Default uses current user's home directory
+PROTECCIO_BASE_DIR="$HOME/adopt_proteccio"
+
+# Path to the Proteccio HSM Ansible role
+PROTECCIO_ROLES_DIR="$PROTECCIO_BASE_DIR/roles/ansible-role-rhoso-proteccio-hsm"
+
+# Directory containing Proteccio client certificates and configuration files
+PROTECCIO_FILES_DIR="$PROTECCIO_BASE_DIR/proteccio_files"
+
+# Ansible inventory file for the adoption
+INVENTORY_FILE="inventory.proteccio.yaml"
+
+# Ansible playbook file for the adoption
+PLAYBOOK_FILE="playbooks/barbican_proteccio_adoption.yml"
+
+# Expected user account (user that should run the script)
+EXPECTED_USER="stack"
+
+# Additional Ansible variables (optional)
+# export ANSIBLE_HOST_KEY_CHECKING=False
+# export ANSIBLE_TIMEOUT=60

tests/inventory.proteccio.yaml

@@ -0,0 +1,15 @@
+---
+# Inventory for OpenStack Proteccio Adoption Role
+# Use this inventory specifically for the barbican_proteccio_adoption role
+# For standard dp-adopt framework, use inventory.yaml instead
+
+all:
+  hosts:
+    localhost:
+      ansible_connection: local
+      ansible_python_interpreter: "{{ ansible_playbook_python }}"
+
+  children:
+    adoption:
+      hosts:
+        localhost:

tests/my_vars.yaml.sample

@@ -0,0 +1,10 @@
+# Sample source environment connection variables
+# This file is generated automatically by the barbican_proteccio_adoption role
+# Copy this file to my_vars.yaml and customize for your environment
+
+UC_HOST: "YOUR_UNDERCLOUD_HOSTNAME"
+CTRL_HOST: "YOUR_CONTROLLER_HOSTNAME.ctlplane"
+controller1_ssh: "sudo ssh -t YOUR_UNDERCLOUD_HOSTNAME 'sudo -u stack ssh -t tripleo-admin@YOUR_CONTROLLER_HOSTNAME.ctlplane bash -lc'"
+undercloud_ssh: "sudo ssh -t YOUR_UNDERCLOUD_HOSTNAME 'sudo -u stack bash -lc'"
+tripleo_passwords:
+  default: "/path/to/your/overcloud-passwords.yaml"

tests/playbooks/barbican_proteccio_adoption.yml

@@ -0,0 +1,66 @@
+---
+# Main playbook for Barbican adoption with Proteccio HSM integration
+# OpenStack 17.1 to RHOSO 18 adoption
+
+- name: Barbican Adoption with Proteccio HSM Integration
+  hosts: localhost
+  connection: local
+  gather_facts: true
+  become: false
+
+  vars: {}
+    # Override default variables here if needed
+    # source_undercloud_host: "your-undercloud-host"
+    # source_controller_host: "your-controller-host"
+    # target_namespace: "openstack"
+    # barbican_simple_crypto_kek: "your-custom-kek"
+
+  pre_tasks:
+    - name: Verify environment prerequisites
+      block:
+        - name: Check if running as correct user
+          ansible.builtin.fail:
+            msg: "This playbook should be run as the stack user"
+          when: ansible_user_id != "stack"
+
+        - name: Verify oc/oc access
+          ansible.builtin.command: oc cluster-info
+          register: cluster_check
+          failed_when: cluster_check.rc != 0
+
+        - name: Check OpenShift/Kubernetes cluster access
+          ansible.builtin.command: "oc get namespace {{ target_namespace | default('openstack') }}"
+          register: namespace_check
+          changed_when: false
+          failed_when: namespace_check.rc != 0
+
+  roles:
+    - role: barbican_proteccio_adoption
+
+  post_tasks:
+    - name: Display completion summary
+      ansible.builtin.debug:
+        msg: |
+          ===============================================
+          ADOPTION COMPLETED SUCCESSFULLY!
+          ===============================================
+
+          Barbican adoption with Proteccio HSM integration has been completed.
+
+          Key achievements:
+          - Database adopted with {{ adopted_secrets_count | default('N/A') }} secrets
+          - Proteccio custom images deployed
+          - HSM configuration applied
+          - API functionality verified
+
+          Check the generated summary file for detailed results.
+          ===============================================
+
+  handlers:
+    - name: Clean up temporary files
+      ansible.builtin.file:
+        path: "{{ item }}"
+        state: absent
+      loop:
+        - "{{ backup_dir }}/temp_*"
+      listen: "cleanup"

tests/roles/barbican_proteccio_adoption/README.md

@@ -0,0 +1,140 @@
+# Barbican Proteccio Adoption Role
+
+Ansible role for adopting Barbican service from OpenStack 17.1 to RHOSO 18 with Proteccio HSM integration.
+
+## 🔗 **Relationship to Existing Barbican Adoption Role**
+
+This repository contains **two distinct Barbican adoption roles**:
+
+### 1. `barbican_adoption` (Standard)
+- **Purpose**: Standard Barbican adoption without HSM
+- **Backend**: Uses `simple_crypto` plugin only
+- **Use Case**: Standard OpenStack deployments
+- **Process**: Simple configuration adoption and service deployment
+
+### 2. `barbican_proteccio_adoption` (HSM-Enabled) - **This Role**
+- **Purpose**: Barbican adoption with Proteccio HSM integration
+- **Backend**: Supports both `simple_crypto` and `pkcs11` (HSM) plugins
+- **Use Case**: High-security environments requiring HSM
+- **Process**: Complex multi-phase adoption with HSM configuration
+
+**WARNING: Important**: These roles are **mutually exclusive**. Choose the appropriate role based on your source environment:
+- If your TripleO 17.1 has **standard Barbican** → use `barbican_adoption`
+- If your TripleO 17.1 has **Proteccio HSM integration** → use `barbican_proteccio_adoption`
+
+## WARNING: **IMPORTANT: Customization Required**
+
+**This role contains placeholder values that MUST be customized for your environment before use.**
+
+### Required Customization Steps:
+
+1. **Copy and customize the sample variables:**
+   ```bash
+   cp vars/sample_environment.yml vars/my_environment.yml
+   # Edit vars/my_environment.yml with your values
+   ```
+
+2. **Generate your own KEK key:**
+   ```bash
+   openssl rand -base64 32
+   ```
+
+3. **Update the following in `vars/my_environment.yml`:**
+   - `source_undercloud_host`: Your actual undercloud hostname
+   - `source_controller_host`: Your actual controller hostname
+   - `barbican_simple_crypto_kek`: Your generated 32-byte base64 key
+   - `hsm_login_password`: Your HSM login password
+   - `hsm_token_labels`: Your HSM token label
+   - `proteccio_required_files`: List your actual certificate filenames
+   - `work_dir` and `proteccio_files_dir`: Your actual directory paths
+
+4. **Use your custom variables:**
+   ```bash
+   ansible-playbook -i inventory.proteccio.yaml -e @vars/my_environment.yml playbooks/barbican_proteccio_adoption.yml
+   ```
+
+## Key Features
+
+- **Automatic RabbitMQ user management** to prevent service authentication failures
+- **Graceful HSM role dependency handling** with fallback mechanisms
+- **Database adoption with backup and verification** capabilities
+- **Custom Proteccio image deployment** and HSM configuration management
+- **Comprehensive relationship with standard adoption** - clearly separated workflows
+
+## Documentation
+
+For complete documentation, see the official adoption guide:
+
+- **Procedure**: `docs_user/modules/proc_adopting-key-manager-service-with-proteccio-hsm.adoc`
+- **Concept**: `docs_user/modules/con_key-manager-service-adoption-approaches.adoc`
+- **Troubleshooting**: `docs_user/modules/ref_troubleshooting-key-manager-proteccio-adoption.adoc`
+
+## Quick Start
+
+**WARNING: DO NOT run without customization - it will fail with placeholder values!**
+
+### **Recommended Approach: Use the Adoption Script**
+
+```bash
+# 1. Navigate to the tests directory
+cd /path/to/your/dp-adopt/tests
+
+# 2. Configure script environment
+cp config.env.sample config.env
+vim config.env  # Update paths for your environment
+
+# 3. Customize role variables
+cp roles/barbican_proteccio_adoption/vars/sample_environment.yml \
+   roles/barbican_proteccio_adoption/vars/my_environment.yml
+vim roles/barbican_proteccio_adoption/vars/my_environment.yml  # Update with your values
+
+# 4. Execute the adoption
+./run_proteccio_adoption.sh
+```
+
+### **Alternative: Direct Ansible Execution (Advanced Users)**
+
+```bash
+# For advanced users or troubleshooting specific phases
+ansible-playbook -i inventory.proteccio.yaml \
+  -e @roles/barbican_proteccio_adoption/vars/my_environment.yml \
+  playbooks/barbican_proteccio_adoption.yml
+```
+
+## Dependencies
+
+### **MANDATORY Requirements**
+
+- **`ansible-role-rhoso-proteccio-hsm` role**: **REQUIRED** - This role is absolutely mandatory for Proteccio HSM adoption. It MUST be executed either:
+  - As part of this adoption process (automatic execution), OR
+  - Before running this adoption process (manual execution)
+  - **WITHOUT THIS ROLE, THE ADOPTION WILL FAIL**
+
+- **Proteccio client files**: All certificate and key files must be present in the specified directory
+- **OpenStack 17.1 source environment** with **Proteccio HSM integration** already configured
+- **RHOSO 18 target cluster** with administrative access
+- **Kubernetes/OpenShift CLI access** with appropriate permissions
+
+### **Critical HSM Role Information**
+
+The `ansible-role-rhoso-proteccio-hsm` role is responsible for:
+- Creating essential Kubernetes secrets (`hsm-login`, `proteccio-data`)
+- Mounting Proteccio certificate files in the target environment
+- Configuring HSM authentication for Barbican services
+
+**This role is NOT optional**. If you attempt to run the adoption without it:
+- The adoption process will fail with clear error messages
+- Barbican services will not be able to access the HSM
+- Your existing HSM-protected secrets will become inaccessible
+
+## Troubleshooting
+
+If Barbican services show CrashLoopBackOff after deployment, the role automatically:
+1. Extracts RabbitMQ credentials from transport URLs
+2. Creates missing RabbitMQ users
+3. Sets appropriate permissions
+4. The services should recover automatically
+
+## Security Note
+
+**Never commit files containing real credentials, passwords, or certificate data to version control.**

tests/roles/barbican_proteccio_adoption/defaults/main.yml

@@ -0,0 +1,66 @@
+---
+# Default variables for OpenStack adoption
+
+# Source environment connection details (CUSTOMIZE THESE)
+source_undercloud_host: "CHANGE_ME_UNDERCLOUD_HOSTNAME"  # Change to your undercloud hostname
+source_controller_host: "CHANGE_ME_CONTROLLER_HOSTNAME.ctlplane"  # Change to your controller hostname
+
+# Target RHOSO environment
+target_namespace: "openstack"
+target_storage_class: "local-storage"
+
+# Database configuration (GENERATE YOUR OWN KEK)
+barbican_simple_crypto_kek: "CHANGE_ME_GENERATE_32_BYTE_BASE64_KEY"  # openssl rand -base64 32
+
+# Proteccio HSM configuration (CUSTOMIZE THESE IMAGE URLS)
+proteccio_custom_images:
+  barbican_api: "CHANGE_ME_YOUR_REGISTRY/barbican-api:CHANGE_ME_YOUR_TAG"  # Replace with your Proteccio-enabled Barbican API image
+  barbican_worker: "CHANGE_ME_YOUR_REGISTRY/barbican-worker:CHANGE_ME_YOUR_TAG"  # Replace with your Proteccio-enabled Barbican Worker image
+
+# HSM configuration (CUSTOMIZE THESE)
+hsm_login_password: "CHANGE_ME_YOUR_HSM_PASSWORD"  # Replace with your HSM password
+hsm_token_labels: "CHANGE_ME_YOUR_HSM_TOKEN_LABEL"  # Replace with your HSM token label
+hsm_mkek_label: "CHANGE_ME_YOUR_MKEK_LABEL"  # Replace with your MKEK label
+hsm_hmac_label: "CHANGE_ME_YOUR_HMAC_LABEL"  # Replace with your HMAC label
+
+# Required Proteccio client files (list of filenames expected in proteccio_files_dir)
+# CUSTOMIZE THIS LIST with your actual certificate and key filenames
+proteccio_required_files:
+  - "CHANGE_ME_YOUR_CLIENT_CERT_FILENAME.crt"  # Your Proteccio client certificate
+  - "CHANGE_ME_YOUR_CLIENT_KEY_FILENAME.key"   # Your Proteccio client private key
+  - "CHANGE_ME_YOUR_CONFIG_FILENAME.rc"        # Your Proteccio configuration file
+  - "CHANGE_ME_YOUR_HSM_CERT_FILENAME.crt"     # Your HSM certificate
+
+# Service replica counts
+barbican_api_replicas: 1
+barbican_worker_replicas: 1
+barbican_keystone_listener_replicas: 1
+
+# Adoption settings
+backup_database: true
+verify_adoption: true
+start_with_simple_crypto: true
+handle_rabbitmq_users: true
+# NOTE: The ansible-role-rhoso-proteccio-hsm role is MANDATORY for Proteccio environments
+# It must be available and executable, either as part of this process or run beforehand
+require_hsm_role: true
+
+# Verification settings (CUSTOMIZE THESE)
+# List of secret names to specifically verify during adoption
+# Leave empty to skip specific secret verification
+expected_secrets_to_verify: []  # Example: ["hsm-secret", "my-important-secret"]
+verify_any_secrets: true  # If true, verify that ANY secrets were adopted (recommended)
+
+# Timeouts (seconds)
+service_ready_timeout: 600
+database_import_timeout: 300
+
+# Working directories (CUSTOMIZE THESE PATHS)
+work_dir: "{{ ansible_env.PWD | default('/tmp/adopt_proteccio') }}"  # Current working directory or change as needed
+proteccio_base_dir: "{{ proteccio_base_dir | default('/home/' + ansible_user + '/adopt_proteccio') }}"  # Base directory for all Proteccio files
+proteccio_files_dir: "{{ proteccio_files_dir | default(proteccio_base_dir + '/proteccio_files') }}"  # Proteccio certificate files directory
+hsm_role_path: "{{ hsm_role_path | default(proteccio_base_dir + '/roles/ansible-role-rhoso-proteccio-hsm') }}"  # HSM role path
+backup_dir: "{{ backup_dir | default(work_dir + '/backups') }}"
+
+# TripleO configuration files (CUSTOMIZE THESE PATHS)
+tripleo_passwords_file: "CHANGE_ME_PATH_TO_OVERCLOUD_PASSWORDS_YAML"  # Path to overcloud passwords file (usually /home/USER/overcloud-passwords.yaml)

tests/roles/barbican_proteccio_adoption/meta/main.yml

@@ -0,0 +1,19 @@
+---
+galaxy_info:
+  author: Red Hat
+  description: Automated Barbican adoption from OpenStack 17.1 to RHOSO 18 with Proteccio HSM
+  company: Red Hat
+  license: Apache-2.0
+  min_ansible_version: "2.9"
+  platforms:
+    - name: EL
+      versions:
+        - all
+  galaxy_tags:
+    - openstack
+    - adoption
+    - barbican
+    - hsm
+    - proteccio
+
+dependencies: []