Replace CI/Zuul references with manual commands in HSM adoption docs

Mauricio Harley · Mauricio Harley · commit 917ecc9faeaf · 2026-05-18T18:03:18.000+02:00
The Key Manager (Barbican) HSM adoption documentation contained
references to CI-specific tooling (Zuul job vars, CI framework
configuration, cifmw_* variables) that are not applicable to users
performing adoption manually. This made the Proteccio HSM procedure
(section 4.4.2) impossible to follow as a user.

Replace CI-oriented instructions with concrete manual commands (oc
create secret, oc patch) following the same pattern used by the
simple_crypto adoption procedure (section 4.3). Update related
concept modules and troubleshooting procedures to remove CI
references and use user-facing terminology throughout.

Signed-off-by: Mauricio Harley &lt;mharley@redhat.com&gt;
diff --git a/docs_user/modules/con_key-manager-service-hsm-adoption-approaches.adoc b/docs_user/modules/con_key-manager-service-hsm-adoption-approaches.adoc
@@ -16,13 +16,12 @@ Standard adoption approach::
 * Is suitable for development, testing, and standard production environments
 
 HSM-enabled adoption approach::
-* Uses the enhanced `barbican_adoption` role with HSM awareness
-* Configures HSM integration through a simple boolean flag (`barbican_hsm_enabled: true`)
-* Automatically creates required Kubernetes secrets (`hsm-login` and `proteccio-data`)
+* Patches the `OpenStackControlPlane` custom resource with HSM-enabled configuration
+* Creates required Kubernetes secrets (`hsm-login` and `proteccio-data`) for HSM credentials and certificates
 * Preserves HSM metadata during database migration
 * Supports both simple crypto and HSM back ends in the target environment
-* Requires HSM-specific configuration variables and custom container images with HSM client libraries (built using the `rhoso_proteccio_hsm` Ansible role)
-* Uses HSM client certificates and configuration files accessible via URLs
+* Requires custom container images with HSM client libraries that are built by using the `rhoso_proteccio_hsm` Ansible role
+* Requires HSM client certificates and configuration files
 * Requires proper HSM partition and key configuration that matches your source environment
 * The HSM-enabled adoption approach currently supports:
 ** Proteccio (Eviden Trustway): Fully supported with PKCS#11 integration
@@ -34,7 +33,7 @@ HSM-enabled adoption approach::
 HSM adoption requires additional configuration steps, including:
 
 * Custom Barbican container images with HSM client libraries that are built using the `rhoso_proteccio_hsm` Ansible role
-* HSM client certificates and configuration files that are accessible by using URLs
+* HSM client certificates and configuration files that are accessible from the host where you run the adoption commands
 * Proper HSM partition and key configuration that matches your source environment
 
 These approaches are mutually exclusive. Choose an approach based on your source environment configuration.
diff --git a/docs_user/modules/con_key-manager-service-support-for-crypto-plugins.adoc b/docs_user/modules/con_key-manager-service-support-for-crypto-plugins.adoc
@@ -21,4 +21,4 @@ The {key_manager} supports HSM integration through the PKCS#11 plugin. This enab
 * Compliance with security requirements for production environments
 * Preservation of existing HSM-protected secrets during adoption
 
-HSM integration is configured through a simple boolean flag (`barbican_hsm_enabled`) during the adoption process. For environments that require HSM integration during adoption, see xref:adopting-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].
+For environments that require HSM integration during adoption, see xref:adopting-the-key-manager-service-with-proteccio-hsm_hsm-integration[Adopting the {key_manager} with Proteccio HSM integration].
diff --git a/docs_user/modules/proc_adopting-key-manager-service-with-hsm-integration.adoc b/docs_user/modules/proc_adopting-key-manager-service-with-hsm-integration.adoc
@@ -13,11 +13,6 @@ When your source {OpenStackPreviousInstaller} environment includes hardware secu
 * The target {rhos_long} environment with HSM infrastructure is accessible.
 * HSM-enabled {key_manager_first_ref} container images are built and available in your registry.
 
-[NOTE]
-====
-If you use the automated adoption process by setting `barbican_hsm_enabled: true`, the required HSM secrets (`hsm-login` and `proteccio-data`) are created automatically. You only need to manually create the secret when you perform the manual adoption steps.
-====
-
 .Procedure
 
 . Confirm that your source environment configuration includes HSM integration:
@@ -45,7 +40,7 @@ $ SIMPLE_CRYPTO_KEK=$(ssh tripleo-admin@controller-0.ctlplane \
 $ oc set data secret/osp-secret "BarbicanSimpleCryptoKEK=${SIMPLE_CRYPTO_KEK}"
 ----
 
-. If you are not using the automated adoption, create HSM-specific secrets in the target environment:
+. Create HSM-specific secrets in the {rhos_acro} target environment:
 +
 [source,bash]
 ----
@@ -76,11 +71,6 @@ Specifies the path to the client key.
 Specifies the path to the server certificate.
 <path_to_hsm_config>::
 Specifies the path to your HSM configuration in your {rhos_acro} environment.
-+
-[NOTE]
-====
-When you use the automated adoption by setting `barbican_hsm_enabled: true`, the `barbican_adoption` role creates these secrets automatically. The secret names default to `hsm-login` and `proteccio-data`.
-====
 
 . Patch the `OpenStackControlPlane` custom resource to deploy {key_manager} with HSM support:
 +
diff --git a/docs_user/modules/proc_adopting-key-manager-service-with-proteccio-hsm.adoc b/docs_user/modules/proc_adopting-key-manager-service-with-proteccio-hsm.adoc
@@ -4,98 +4,171 @@
 = Adopting the {key_manager} with Proteccio HSM integration
 
 [role="_abstract"]
-To adopt the {key_manager_first_ref} with Proteccio hardware security module (HSM) integration, you use the enhanced Barbican adoption role with HSM support enabled through a configuration flag. This approach preserves HSM integration while adopting all existing secrets from your source {rhos_prev_long} ({OpenStackShort}) environment.
-When you run the data plane adoption tests with HSM support enabled, the adoption process performs the following actions:
-
-* Extracts the simple crypto KEK from the source configuration.
-* Creates the required HSM secrets (hsm-login and proteccio-data) in the target namespace.
-* Deploys Barbican with HSM-enabled configuration by using the PKCS#11 plugin.
-* Verifies the HSM functionality and secret migration.
-When you run the data plane adoption tests with HSM support enabled, the adoption process performs the following actions:
-
-* Extracts the simple crypto KEK from the source configuration.
-* Creates the required HSM secrets (hsm-login and proteccio-data) in the target namespace.
-* Deploys Barbican with HSM-enabled configuration by using the PKCS#11 plugin.
-* Verifies the HSM functionality and secret migration.
+To adopt the {key_manager_first_ref} with Proteccio hardware security module (HSM) integration, you patch an existing `OpenStackControlPlane` custom resource (CR) where {key_manager} is disabled. The patch starts the service with the configuration parameters from the {rhos_prev_long} ({OpenStackShort}) environment and preserves access to existing HSM-backed secrets. You configure the {key_manager} to use both the `simple_crypto` and `pkcs11` back ends.
 
 The {key_manager} Proteccio HSM adoption is complete if you see the following results:
 
-* The `BarbicanAPI` and `BarbicanWorker` services are up and running with HSM-enabled configuration.
+* The `BarbicanAPI`, `BarbicanWorker`, and `BarbicanKeystoneListener` services are up and running with HSM-enabled configuration.
 * All secrets from the source {OpenStackShort} {rhos_prev_ver} environment are available in {rhos_long} {rhos_curr_ver}.
 * The PKCS11 crypto plugin is available alongside `simple_crypto` for new secret storage.
 * HSM functionality is verified and operational.
 
 [NOTE]
-====
-If your environment does not include Proteccio HSM, to adopt the {key_manager} by using `simple_crypto`, see xref:adopting-the-key-manager-service_{context}[Adopting the {key_manager}].
-
-The enhanced {key_manager} adoption role supports HSM configuration through a simple boolean flag. This approach integrates seamlessly with the standard data plane adoption framework while providing HSM support.
-====
+If your environment does not include Proteccio HSM, to adopt the {key_manager} by using `simple_crypto` only, see xref:adopting-the-key-manager-service_adopt-control-plane[Adopting the {key_manager}].
 
 .Prerequisites
 
 * You have a running {OpenStackPreviousInstaller} environment with Proteccio HSM integration (the source cloud).
 * You have a Single Node OpenShift or OpenShift Local running in the {rhocp_long} cluster.
 * You have SSH access to the source {OpenStackPreviousInstaller} undercloud and Controller nodes.
-* You have configured HSM variables in your adoption configuration files.
-* Custom {key_manager} container images with the Proteccio client libraries are available in your registry.
+* Custom {key_manager} container images with the Proteccio client libraries are built and available in your container registry. For more information, see the `rhoso_proteccio_hsm` Ansible role documentation.
+* The Proteccio client certificate, client key, server certificate, and `proteccio.rc` configuration file for the target environment are available on the host where you run the adoption commands.
 
 [IMPORTANT]
 ====
-The HSM adoption process requires proper configuration of HSM-related variables. The adoption role automatically creates the required Kubernetes secrets (`hsm-login` and `proteccio-data`) when `barbican_hsm_enabled` is set to `true`. Ensure that your environment includes the following:
-
-* All HSM-related variables are properly set in your configuration files
-* The Proteccio client ISO, certificates, and configuration files are accessible from the configured URLs
-* Custom {key_manager} images with Proteccio client are built and available in your container registry
+Without proper HSM configuration, your HSM-protected secrets become inaccessible after adoption. Ensure the following before you begin:
 
-Without proper HSM configuration, your HSM-protected secrets become inaccessible after adoption.
+* The HSM partition name, MKEK label, and HMAC label match the values configured in your source environment ({OpenStackShort}).
+* The Proteccio client certificates and configuration files are valid for the target environment ({rhos_acro}).
 ====
 
 .Procedure
 
-. Configure HSM integration variables in your adoption configuration (Zuul job vars or CI framework configuration):
+. Confirm that your source environment configuration includes Proteccio HSM integration:
 +
+[source,bash]
+----
+$ ssh tripleo-admin@controller-0.ctlplane \
+  "sudo cat /var/lib/config-data/puppet-generated/barbican/etc/barbican/barbican.conf | grep -A5 '\[p11_crypto_plugin\]'"
 ----
-# Enable HSM integration for the Barbican adoption role
-barbican_hsm_enabled: true
++
+If you see the `[p11_crypto_plugin]` section with Proteccio-specific settings, for example `library_path = /usr/lib64/libnethsm.so`, continue with the HSM adoption. If you do not see this section, your source environment does not include Proteccio HSM integration. Use the standard adoption procedure instead. For more information, see xref:adopting-the-key-manager-service_adopt-control-plane[Adopting the {key_manager}].
 
-# HSM login credentials
-proteccio_login_password: "your_hsm_password"
+. Add the simple crypto key encryption key (KEK) secret:
++
+----
+$ oc set data secret/osp-secret "BarbicanSimpleCryptoKEK=$($CONTROLLER1_SSH "python3 -c \"import configparser; c = configparser.ConfigParser(); c.read('/var/lib/config-data/puppet-generated/barbican/etc/barbican/barbican.conf'); print(c['simple_crypto_plugin']['kek'])\"")"
+----
 
-# Kubernetes secret names (defaults shown)
-proteccio_login_secret_name: "hsm-login"
-proteccio_client_data_secret_name: "proteccio-data"
+. Create the HSM login credentials secret:
++
+[source,bash]
+----
+$ oc create secret generic hsm-login \
+  --from-literal=PKCS11Pin=<your_hsm_password> \
+  -n openstack
+----
++
+where:
 
-# HSM partition and key configuration
-cifmw_hsm_proteccio_partition: "VHSM1"
-cifmw_hsm_mkek_label: "adoption_mkek_1"
-cifmw_hsm_hmac_label: "adoption_hmac_1"
-cifmw_hsm_proteccio_library_path: "/usr/lib64/libnethsm.so"
-cifmw_hsm_key_wrap_mechanism: "CKM_AES_CBC_PAD"
+`<your_hsm_password>`::
+Specifies the HSM PKCS#11 PIN for the Proteccio partition in your environment.
 
-# HSM client sources (URLs to download Proteccio client files)
-cifmw_hsm_proteccio_client_src: "<URL_of_Proteccio_ISO_file>"
-cifmw_hsm_proteccio_conf_src: "<URL_of_proteccio.rc_config_file>"
-cifmw_hsm_proteccio_client_crt_src: "<URL_of_client_certificate_file>"
-cifmw_hsm_proteccio_client_key_src: "<URL_of_client_certificate_key>"
-cifmw_hsm_proteccio_server_crt_src:
-  - "<URL_of_HSM_certificate_file>"
+. Create the Proteccio client data secret with the certificates and configuration:
++
+[source,bash]
+----
+$ oc create secret generic proteccio-data \
+  --from-file=client.crt=<path_to_client_cert> \
+  --from-file=client.key=<path_to_client_key> \
+  --from-file=<hsm_server_cert_filename>=<path_to_server_cert> \
+  --from-file=proteccio.rc=<path_to_hsm_config> \
+  -n openstack
 ----
 +
 where:
 
-<URL_of_Proteccio_ISO_file>::
-Specifies the full URL (including "http://" or "https://") of the Proteccio client ISO image file.
-<URL_of_proteccio.rc_config_file>::
-Specifies the full URL (including "http://" or "https://") of the `proteccio.rc` configuration in your {rhos_acro} environment.
-<URL_of_client_certificate_file>::
-Specifies the full URL (including "http://" or "https://") of the HSM client certificate file.
-<URL_of_client_certificate_key>::
-Specifies the full URL (including "http://" or "https://") of the client key file.
-<URL_of_HSM_certificate_file>::
-Specifies the full URL (including "http://" or "https://") of the HSM certificate file.
+`<path_to_client_cert>`::
+Specifies the path to the HSM client certificate file.
+`<path_to_client_key>`::
+Specifies the path to the HSM client key file.
+`<hsm_server_cert_filename>`::
+Specifies the filename of the HSM server certificate that is expected by the Proteccio client, for example, `10_8_60_93.CRT`.
+`<path_to_server_cert>`::
+Specifies the path to the HSM server certificate file.
+`<path_to_hsm_config>`::
+Specifies the path to the `proteccio.rc` configuration file for your environment.
+
+. Patch the `OpenStackControlPlane` CR to deploy the {key_manager} with HSM support:
++
+[subs="+quotes"]
+----
+$ oc patch openstackcontrolplane openstack --type=merge --patch '
+spec:
+  barbican:
+    enabled: true
+    apiOverride:
+      route: {}
+    template:
+      databaseInstance: openstack
+      databaseAccount: barbican
+      messagingBus:
+        cluster: rabbitmq
+      secret: osp-secret
+      simpleCryptoBackendSecret: osp-secret
+      serviceAccount: barbican
+      serviceUser: barbican
+      passwordSelectors:
+        database: BarbicanDatabasePassword
+        service: BarbicanPassword
+        simplecryptokek: BarbicanSimpleCryptoKEK
+      customServiceConfig: |
+        [p11_crypto_plugin]
+        plugin_name = PKCS11
+        library_path = *<library_path>*
+        token_labels = *<partition_name>*
+        mkek_label = *<mkek_label>*
+        hmac_label = *<hmac_label>*
+        encryption_mechanism = CKM_AES_CBC
+        hmac_key_type = CKK_GENERIC_SECRET
+        hmac_keygen_mechanism = CKM_GENERIC_SECRET_KEY_GEN
+        hmac_mechanism = CKM_SHA256_HMAC
+        key_wrap_mechanism = *<key_wrap_mechanism>*
+        key_wrap_generate_iv = true
+        always_set_cka_sensitive = true
+        os_locking_ok = false
+      globalDefaultSecretStore: pkcs11
+      enabledSecretStores: ["simple_crypto", "pkcs11"]
+      pkcs11:
+        loginSecret: hsm-login
+        clientDataSecret: proteccio-data
+        clientDataPath: /etc/proteccio
+      barbicanAPI:
+        replicas: 1
+        override:
+          service:
+            internal:
+              metadata:
+                annotations:
+                  metallb.universe.tf/address-pool: internalapi
+                  metallb.universe.tf/allow-shared-ip: internalapi
+                  metallb.universe.tf/loadBalancerIPs: *<172.17.0.80>*
+              spec:
+                type: LoadBalancer
+      barbicanWorker:
+        replicas: 1
+      barbicanKeystoneListener:
+        replicas: 1
+'
+----
++
+where:
 
-. Run the data plane adoption tests with HSM support enabled:
+`<library_path>`::
+Specifies the path to the PKCS#11 library inside the container, for example, `/usr/lib64/libnethsm.so` for Proteccio.
+`<partition_name>`::
+Specifies the HSM partition name, for example, `VHSM1`. This value must match the partition configured in your source environment.
+`<mkek_label>`::
+Specifies the label of the Master Key Encryption Key (MKEK) in the HSM. This value must match the key configured in your source environment.
+`<hmac_label>`::
+Specifies the label of the HMAC key in the HSM. This value must match the key configured in your source environment.
+`<key_wrap_mechanism>`::
+Specifies the PKCS#11 key wrap mechanism, for example, `CKM_AES_CBC_PAD`. This value must match the mechanism configured in your source environment.
+`<172.17.0.80>`::
+Specifies the load balancer IP in your environment. If you use IPv6, change the load balancer IP to the load balancer IP in your environment, for example, `metallb.universe.tf/loadBalancerIPs: fd00:bbbb::80`.
+
+`messagingBus.Cluster`::
+For more information about RHOSO RabbitMQ clusters, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/monitoring_high_availability_services/ref_rhoso-rabbitmq-clusters_ha-monitoring#con_understand-the-rabbitmq-interface-for-openstack-services[RHOSO RabbitMQ clusters] in _Monitoring high availability services_.
 
 .Verification
 
@@ -117,7 +190,7 @@ $ openstack service list | grep key-manager
 $ openstack secret list
 ----
 
-. Confirm that Barbican services are running:
+. Confirm that the {key_manager} services are running with HSM-enabled configuration:
 +
 ----
 $ oc get pods -n openstack -l service=barbican -o wide
@@ -129,13 +202,18 @@ $ oc get pods -n openstack -l service=barbican -o wide
 $ openstack secret store --name adoption-verification --payload 'HSM adoption successful'
 ----
 
-. Verify that the HSM back end is operational:
+. Verify that the HSM back end is operational by retrieving the secret:
 +
 ----
 $ openstack secret get <secret_id> --payload
 ----
 +
 where:
 
-<secret_id>::
-Specifies the ID of the HSM secret.
+`<secret_id>`::
+Specifies the ID of the secret created in the previous step.
+
+[NOTE]
+====
+HSM adoption preserves both simple crypto and HSM-backed secrets. The migration process maintains HSM metadata and secret references, ensuring continued access to existing secrets while enabling new secrets to use either back end.
+====
diff --git a/docs_user/modules/proc_resolving-config-validation-failures.adoc b/docs_user/modules/proc_resolving-config-validation-failures.adoc
@@ -4,7 +4,7 @@
 = Resolving configuration validation failures
 
 [role="_abstract"]
-If the adoption fails with validation errors about placeholder values, replace the placeholder values with your environment's configuration values.
+If the adoption fails with validation errors about placeholder values, replace the placeholder values with your environment's actual configuration values.
 
 Example error:
 
@@ -17,17 +17,12 @@ fatal: [localhost]: FAILED! => {
 
 .Procedure
 
-. Edit your hardware security module configuration in the Zuul job vars or CI framework configuration file.
+. Check the `OpenStackControlPlane` custom resource (CR) patch and the Kubernetes secrets that you created during the adoption procedure.
 
-. Check the following key variables and replace all placeholder values with actual configuration values for your environment:
+. Verify that the following configuration values are correct for your environment and do not contain placeholder values:
 +
-----
-cifmw_hsm_password: <your_actual_hsm_password>
-cifmw_barbican_proteccio_partition: <VHSM1>
-cifmw_barbican_proteccio_mkek_label: <your_mkek_label>
-cifmw_barbican_proteccio_hmac_label: <your_hmac_label>
-cifmw_hsm_proteccio_client_src: <https://your-server/path/to/Proteccio.iso>
-cifmw_hsm_proteccio_conf_src: <https://your-server/path/to/proteccio.rc>
-----
+* The HSM PKCS#11 PIN in the `hsm-login` secret
+* The HSM partition name, MKEK label, and HMAC label in the `customServiceConfig` section of the `OpenStackControlPlane` CR patch
+* The Proteccio client certificate, client key, server certificate, and `proteccio.rc` configuration file in the `proteccio-data` secret
 
-. Verify that no placeholder values remain in your configuration.
+. Verify that no placeholder values remain in your configuration before you re-run the adoption.
diff --git a/docs_user/modules/proc_resolving-custom-image-registry-issues.adoc b/docs_user/modules/proc_resolving-custom-image-registry-issues.adoc
@@ -44,11 +44,16 @@ Specifies the name of your registry server.
 `<namespace>`::
 Specifies the namespace of your container image.
 
-. Update registry configuration variables if needed:
+. If needed, verify that the custom {key_manager} images with Proteccio client libraries are available in the registry:
 +
-[source,yaml]
+[source,bash]
 ----
-cifmw_update_containers_registry: "your-registry:5001"
-cifmw_update_containers_org: "your-namespace"
-cifmw_image_registry_verify_tls: false
+$ podman search <registry>/<namespace>/barbican --list-tags
 ----
++
+where:
+
+`<registry>`::
+Specifies the name of your registry server.
+`<namespace>`::
+Specifies the namespace of your container image.
diff --git a/docs_user/modules/proc_resolving-hsm-backend-detection-failures.adoc b/docs_user/modules/proc_resolving-hsm-backend-detection-failures.adoc
diff --git a/docs_user/modules/proc_resolving-missing-HSM-file-prerequisites.adoc b/docs_user/modules/proc_resolving-missing-HSM-file-prerequisites.adoc
