Replace CI/Zuul references with manual commands in HSM adoption docs by mauricioharley · Pull Request #1392 · openstack-k8s-operators/data-plane-adoption

mauricioharley · 2026-05-13T14:41:06Z

Problem

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.

Solution

Rewrite the Proteccio HSM procedure (section 4.4.2) to follow the same manual approach used by the simple_crypto adoption procedure (section 4.3): explicit oc create secret and oc patch openstackcontrolplane commands with documented replaceable parameters.

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 <mharley@redhat.com>

openshift-ci · 2026-05-13T14:41:13Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign archana203 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

klgill · 2026-05-15T12:38:05Z

-* 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` CR with HSM-enabled configuration


Suggested change

* Patches the `OpenStackControlPlane` CR with HSM-enabled configuration

* Patches the `OpenStackControlPlane` custom resource with HSM-enabled configuration

klgill · 2026-05-15T12:38:52Z

 * 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 (built using the `rhoso_proteccio_hsm` Ansible role)


Suggested change

* Requires custom container images with HSM client libraries (built using the `rhoso_proteccio_hsm` Ansible role)

* Requires custom container images with HSM client libraries that are built by using the `rhoso_proteccio_hsm` Ansible role

klgill · 2026-05-15T12:50:47Z

@@ -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



@mauricioharley This module is not currently included in the adoption guide. If there is value in including this, we should add it to the "assembly_rhoso-180-adoption-overview.adoc" assembly.

klgill · 2026-05-15T12:52:09Z

 * 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_{context}[Adopting the {key_manager} with Proteccio HSM integration].


Suggested change

For environments that require HSM integration during adoption, see xref:adopting-the-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].

klgill · 2026-05-15T12:54:42Z

 ----

-. If you are not using the automated adoption, create HSM-specific secrets in the target environment:
+. Create HSM-specific secrets in the target environment:


Does "target environment" refer to RHOSO? If so, we could be more specific and use the {rhos_acro} attribute (renders as "RHOSO").

klgill · 2026-05-15T13:08:18Z


-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.
+* The Proteccio client certificates and configuration files are valid for the target environment.


You could add "...source environment (RHOSP)" and "...target environment (RHOSO)" to be more explicit.

klgill · 2026-05-15T13:09:57Z

-# 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.


What if the customer doesn't see the settings?

klgill · 2026-05-15T13:13:35Z

+`<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 as expected by the Proteccio client, for example, `10_8_60_93.CRT`.


Suggested change

Specifies the filename of the HSM server certificate as expected by the Proteccio client, for example, `10_8_60_93.CRT`.

Specifies the filename of the HSM server certificate that is expected by the Proteccio client, for example, `10_8_60_93.CRT`.

klgill · 2026-05-15T13:28:16Z

 .Procedure

-. Edit your hardware security module configuration in the Zuul job vars or CI framework configuration file.
+. Check the `OpenStackControlPlane` CR patch and the Kubernetes secrets that you created during the adoption procedure.


Suggested change

. Check the `OpenStackControlPlane` CR patch and the Kubernetes secrets that you created during the adoption procedure.

. Check the `OpenStackControlPlane` custom resource (CR) patch and the Kubernetes secrets that you created during the adoption procedure.

klgill · 2026-05-15T13:42:03Z

-    "msg": "No HSM configuration found - using standard adoption"
-}
----
+If the {key_manager_first_ref} does not detect the hardware security module (HSM) configuration after adoption, verify that the HSM configuration exists in the source environment and that the `OpenStackControlPlane` CR includes the correct HSM settings.


Suggested change

If the {key_manager_first_ref} does not detect the hardware security module (HSM) configuration after adoption, verify that the HSM configuration exists in the source environment and that the `OpenStackControlPlane` CR includes the correct HSM settings.

If the {key_manager_first_ref} does not detect the hardware security module (HSM) configuration after adoption, verify that the HSM configuration exists in the source environment and that the `OpenStackControlPlane` custom resource (CR) includes the correct HSM settings.

mauricioharley requested a review from klgill May 15, 2026 09:53

mauricioharley self-assigned this May 15, 2026

klgill requested changes May 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Replace CI/Zuul references with manual commands in HSM adoption docs#1392
mauricioharley wants to merge 1 commit into
openstack-k8s-operators:mainfrom
mauricioharley:fix/remove-ci-references-from-hsm-docs

mauricioharley commented May 13, 2026

Uh oh!

openshift-ci Bot commented May 13, 2026

Uh oh!

klgill May 15, 2026

Uh oh!

klgill May 15, 2026

Uh oh!

klgill May 15, 2026

Uh oh!

klgill May 15, 2026

Uh oh!

klgill May 15, 2026

Uh oh!

klgill May 15, 2026

Uh oh!

klgill May 15, 2026

Uh oh!

klgill May 15, 2026

Uh oh!

klgill May 15, 2026

Uh oh!

klgill May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	* Patches the `OpenStackControlPlane` CR with HSM-enabled configuration
	* Patches the `OpenStackControlPlane` custom resource with HSM-enabled configuration

	* Requires custom container images with HSM client libraries (built using the `rhoso_proteccio_hsm` Ansible role)
	* Requires custom container images with HSM client libraries that are built by using the `rhoso_proteccio_hsm` Ansible role

		@@ -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

	For environments that require HSM integration during adoption, see xref:adopting-the-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].

	Specifies the filename of the HSM server certificate as expected by the Proteccio client, for example, `10_8_60_93.CRT`.
	Specifies the filename of the HSM server certificate that is expected by the Proteccio client, for example, `10_8_60_93.CRT`.

	. Check the `OpenStackControlPlane` CR patch and the Kubernetes secrets that you created during the adoption procedure.
	. Check the `OpenStackControlPlane` custom resource (CR) patch and the Kubernetes secrets that you created during the adoption procedure.

	If the {key_manager_first_ref} does not detect the hardware security module (HSM) configuration after adoption, verify that the HSM configuration exists in the source environment and that the `OpenStackControlPlane` CR includes the correct HSM settings.
	If the {key_manager_first_ref} does not detect the hardware security module (HSM) configuration after adoption, verify that the HSM configuration exists in the source environment and that the `OpenStackControlPlane` custom resource (CR) includes the correct HSM settings.

Conversation

mauricioharley commented May 13, 2026

Problem

Solution

Uh oh!

openshift-ci Bot commented May 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants