Add Barbican adoption with Proteccio HSM integration documentation #1058

mauricioharley · 2025-09-19T20:34:44Z

Add comprehensive documentation for Barbican service adoption from OpenStack 17.1 to RHOSO 18 with Proteccio HSM integration.

This PR introduces documentation for a specialized Barbican adoption approach that preserves Proteccio Hardware Security Module (HSM) integration during the migration from TripleO-based OpenStack 17.1 to RHOSO 18.

Fixes: OSPRH-20143

openshift-ci · 2025-09-19T20:34:53Z

[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 jistr 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

docs_user/modules/proc_adopting-key-manager-service-with-proteccio-hsm.adoc

klgill · 2025-10-02T13:36:19Z

@mauricioharley Do you consider this PR to be a work in progress?
I noticed that the feature got deferred to FR5, so I can review this PR if I have capacity, but this will be lower priority compared to FR4 work.

softwarefactory-project-zuul · 2025-10-06T10:06:10Z

Build failed (check pipeline). Post recheck (without leading slash)
to rerun all jobs. Make sure the failure cause has been resolved before
you rerun jobs.

https://softwarefactory-project.io/zuul/t/rdoproject.org/buildset/e8aac29c00b7476eb3b1c91d6e1b0d10

✔️ noop SUCCESS in 0s
❌ adoption-docs-preview FAILURE in 1m 53s

softwarefactory-project-zuul · 2025-10-06T11:53:59Z

Build failed (check pipeline). Post recheck (without leading slash)
to rerun all jobs. Make sure the failure cause has been resolved before
you rerun jobs.

https://softwarefactory-project.io/zuul/t/rdoproject.org/buildset/a3ab0f81b626426781e3db7f4a4fdb51

✔️ noop SUCCESS in 0s
❌ adoption-docs-preview FAILURE in 1m 20s

mauricioharley · 2025-10-14T12:15:12Z

@mauricioharley Do you consider this PR to be a work in progress? I noticed that the feature got deferred to FR5, so I can review this PR if I have capacity, but this will be lower priority compared to FR4 work.

Hi, @klgill. This PR is a bit dependent of what is being done on #1059. I'm adding @vakwetu as reviewer so he can provide his PoV on what is being proposed here.

github-actions · 2025-10-30T02:59:30Z

This PR is stale because it has been for over 15 days with no activity.
Remove stale label or comment or this PR will be closed in 7 days.

klgill · 2025-12-19T14:00:27Z

Note: Will plan to start reviewing this before Dec. 24th. Might need to finish it after I return from recharge (Jan. 5th).
@mauricioharley I just want to check: Are you incorporating any more feedback from stakeholders, or is this the final version that is ready for writer review?

mauricioharley · 2025-12-23T12:52:08Z

@mauricioharley Do you consider this PR to be a work in progress? I noticed that the feature got deferred to FR5, so I can review this PR if I have capacity, but this will be lower priority compared to FR4 work.

Hello, @klgill. This PR is ready to be reviewed by your team.

klgill

@mauricioharley I'm not finished with my review yet. I submitted my comments so they would not get lost while I'm out for recharge. I'll finish my review when I return on Jan. 5th. Enjoy your break!

klgill · 2025-12-23T14:22:48Z

docs_user/assemblies/assembly_adopting-key-manager-service-with-hsm.adoc

@@ -0,0 +1,19 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="adopting-key-manager-service-with-hsm"]


Suggested change

[id="adopting-key-manager-service-with-hsm"]

[id="adopting-key-manager-service-with-hsm_{context}"]

:context: hsm-integration

klgill · 2025-12-23T14:28:58Z

docs_user/assemblies/assembly_adopting-key-manager-service-with-hsm.adoc

@@ -0,0 +1,19 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="adopting-key-manager-service-with-hsm"]
+= Adopting the {key_manager} with Hardware Security Module integration


Suggested change

= Adopting the {key_manager} with Hardware Security Module integration

= Adopting the {key_manager} with HSM integration

klgill · 2025-12-23T14:33:59Z

docs_user/assemblies/assembly_adopting-key-manager-service-with-hsm.adoc

+[id="adopting-key-manager-service-with-hsm"]
+= Adopting the {key_manager} with Hardware Security Module integration
+
+This assembly describes how to adopt the {key_manager_first_ref} from {OpenStackPreviousInstaller} to {rhos_long} when your source environment includes Hardware Security Module (HSM) integration.


Suggested change

This assembly describes how to adopt the {key_manager_first_ref} from {OpenStackPreviousInstaller} to {rhos_long} when your source environment includes Hardware Security Module (HSM) integration.

[role="_abstract"]

Adopt the {key_manager_first_ref} from {OpenStackPreviousInstaller} to {rhos_long} when your source environment includes hardware security module (HSM) integration to preserve HSM functionality and maintain access to HSM-backed secrets. HSM provides enhanced security for cryptographic operations by storing encryption keys in dedicated hardware devices.

klgill · 2025-12-23T14:36:50Z

docs_user/assemblies/assembly_adopting-key-manager-service-with-hsm.adoc

+
+This assembly describes how to adopt the {key_manager_first_ref} from {OpenStackPreviousInstaller} to {rhos_long} when your source environment includes Hardware Security Module (HSM) integration.
+
+Hardware Security Modules provide enhanced security for cryptographic operations by storing encryption keys in dedicated hardware devices. When migrating from {OpenStackPreviousInstaller} to {rhos_acro}, it is essential to preserve HSM functionality and maintain access to HSM-backed secrets.


Suggested change

Hardware Security Modules provide enhanced security for cryptographic operations by storing encryption keys in dedicated hardware devices. When migrating from {OpenStackPreviousInstaller} to {rhos_acro}, it is essential to preserve HSM functionality and maintain access to HSM-backed secrets.

klgill · 2025-12-23T14:44:12Z

docs_user/assemblies/assembly_adopting-openstack-control-plane-services.adoc

 include::../modules/proc_configuring-ldap-with-domain-specific-drivers.adoc[leveloffset=+1]

 include::../modules/proc_adopting-key-manager-service.adoc[leveloffset=+1]



@mauricioharley Did you intend for the following assembly to be placed here as well?assembly_adopting-key-manager-service-with-hsm.adoc
It's currently not included in the guide.

@klgill, thank you for catching this! The assembly_adopting-key-manager-service-with-hsm.adoc
was designed to be a standalone assembly that could be published separately for users who
specifically need HSM integration guidance.

The individual modules (proc_adopting-key-manager-service-with-proteccio-hsm.adoc and
ref_troubleshooting-key-manager-proteccio-adoption.adoc) are already included directly
in the main control plane services assembly (lines 19 and 21) to provide the HSM procedures
within the main adoption workflow.

Would you prefer that I:
A) Keep the current structure (modules included directly), or
B) Replace the direct module includes with the assembly include for better organization?

klgill · 2025-12-23T16:48:18Z

docs_user/modules/con_key-manager-service-support-for-crypto-plugins.adoc

+* 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.


Suggested change

HSM integration is configured through a simple boolean flag (`barbican_hsm_enabled`) during the adoption process.

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

klgill · 2025-12-23T16:48:58Z

docs_user/modules/con_key-manager-service-support-for-crypto-plugins.adoc

 //*TODO: Talk about Ceph Storage and Swift Storage nodes, HCI deployments,
 //etc.*
+
+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].


Suggested change

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

Note: I moved this line to line 30.

klgill · 2025-12-23T16:49:53Z

docs_user/modules/con_key-manager-service-support-for-crypto-plugins.adoc

+
+== HSM Integration
+
+The Key Manager service supports Hardware Security Module (HSM) integration through the PKCS#11 plugin. This enables:


Suggested change

The Key Manager service supports Hardware Security Module (HSM) integration through the PKCS#11 plugin. This enables:

The {key_manager} supports HSM integration through the PKCS#11 plugin. This enables:

klgill · 2025-12-23T16:52:43Z

docs_user/modules/con_key-manager-service-support-for-crypto-plugins.adoc

+== HSM Integration
+


Suggested change

== HSM Integration

klgill · 2025-12-23T16:58:04Z

docs_user/modules/proc_adopting-key-manager-service.adoc


 [NOTE]
-This procedure configures the {key_manager} to use the `simple_crypto` back end. Additional back ends, such as PKCS11 and DogTag, are currently not supported in {rhos_long}.
+This procedure configures the {key_manager} to use the `simple_crypto` back end. For Hardware Security Module (HSM) integration with Proteccio HSM, see xref:adopting-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].


Suggested change

This procedure configures the {key_manager} to use the `simple_crypto` back end. For Hardware Security Module (HSM) integration with Proteccio HSM, see xref:adopting-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].

This procedure configures the {key_manager} to use the `simple_crypto` back end. To configure hardware security module (HSM) integration with Proteccio HSM, see xref:adopting-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].

mauricioharley · 2025-12-24T10:40:28Z

@mauricioharley I'm not finished with my review yet. I submitted my comments so they would not get lost while I'm out for recharge. I'll finish my review when I return on Jan. 5th. Enjoy your break!

Thank you for your review, @klgill. I'll address your suggestions real soon.

Add comprehensive documentation for Barbican service adoption from OpenStack 17.1 to RHOSO 18 with Proteccio HSM integration. This PR introduces documentation for extending the Barbican adoption approach that preserves Proteccio Hardware Security Module (HSM) integration during the migration from TripleO-based OpenStack 17.1 to RHOSO 18. Fixes: OSPRH-20143 Signed-off-by: Mauricio Harley <mharley@redhat.com>

Addresses feedback from PR 1058 review Fixes: OSPRH-20143 Signed-off-by: Mauricio Harley <mharley@redhat.com>

This commit implements all suggestions from klgill's review on PR openstack-k8s-operators#1058: assembly_adopting-key-manager-service-with-hsm.adoc: - Add context preservation with ifdef/ifndef directives - Add {context} suffix to module ID - Shorten title to use "HSM integration" instead of full text - Consolidate abstract into single paragraph with [role="_abstract"] - Change ".Additional resources" to proper heading format con_key-manager-service-hsm-adoption-approaches.adoc: - Use {key_manager} variable in title - Restructure abstract with bullet points for clarity - Convert section headings to definition list format (::) - Consolidate HSM vendor support info into HSM-enabled approach - Fix terminology: "backend" -> "back end", "etc." -> "and so on" - Simplify table header and remove redundant sections con_key-manager-service-support-for-crypto-plugins.adoc: - Use {key_manager_first_ref} in abstract - Remove redundant "== Supported crypto plug-ins" heading - Move xref to end of content section con_adoption-limitations.adoc: - Remove Key Manager plug-in line (not a limitation) proc_adopting-key-manager-service.adoc: - Update phrasing to "To configure hardware security module" Signed-off-by: Mauricio Harley <mharley@redhat.com>

mauricioharley force-pushed the adopt_proteccio_doc branch 3 times, most recently from c8a1a0b to 523d445 Compare September 23, 2025 09:51

mauricioharley requested review from jistr, klgill and xek September 23, 2025 14:34

jistr requested changes Sep 24, 2025

View reviewed changes

docs_user/modules/proc_adopting-key-manager-service-with-proteccio-hsm.adoc Outdated Show resolved Hide resolved

mauricioharley force-pushed the adopt_proteccio_doc branch 7 times, most recently from ed1b655 to 1c4f6b4 Compare October 2, 2025 09:58

mauricioharley requested a review from jistr October 2, 2025 10:49

mauricioharley force-pushed the adopt_proteccio_doc branch from 1c4f6b4 to 5a5d7b0 Compare October 6, 2025 10:03

mauricioharley force-pushed the adopt_proteccio_doc branch from 5a5d7b0 to 3f68299 Compare October 6, 2025 11:52

mauricioharley force-pushed the adopt_proteccio_doc branch from 3f68299 to a748b92 Compare October 14, 2025 12:02

mauricioharley requested a review from vakwetu October 14, 2025 12:15

mauricioharley force-pushed the adopt_proteccio_doc branch from a748b92 to 551f4a6 Compare October 14, 2025 12:28

github-actions bot added the Stale label Oct 30, 2025

github-actions bot closed this Nov 6, 2025

mauricioharley reopened this Dec 10, 2025

github-actions bot removed the Stale label Dec 11, 2025

mauricioharley force-pushed the adopt_proteccio_doc branch from 551f4a6 to 43c97e0 Compare December 19, 2025 12:08

klgill requested changes Dec 23, 2025

View reviewed changes

Mauricio Harley added 3 commits December 24, 2025 11:01

Fix documentation to align with PR 1059 implementation

b01ffe0

Addresses feedback from PR 1058 review Fixes: OSPRH-20143 Signed-off-by: Mauricio Harley <mharley@redhat.com>

mauricioharley force-pushed the adopt_proteccio_doc branch from 43c97e0 to b749ff0 Compare December 24, 2025 11:06

		@@ -0,0 +1,19 @@
		:_mod-docs-content-type: ASSEMBLY
		[id="adopting-key-manager-service-with-hsm"]

-[id="adopting-key-manager-service-with-hsm"]
+[id="adopting-key-manager-service-with-hsm_{context}"]
+:context: hsm-integration

	= Adopting the {key_manager} with Hardware Security Module integration
	= Adopting the {key_manager} with HSM integration

	This assembly describes how to adopt the {key_manager_first_ref} from {OpenStackPreviousInstaller} to {rhos_long} when your source environment includes Hardware Security Module (HSM) integration.
	[role="_abstract"]
	Adopt the {key_manager_first_ref} from {OpenStackPreviousInstaller} to {rhos_long} when your source environment includes hardware security module (HSM) integration to preserve HSM functionality and maintain access to HSM-backed secrets. HSM provides enhanced security for cryptographic operations by storing encryption keys in dedicated hardware devices.


		This assembly describes how to adopt the {key_manager_first_ref} from {OpenStackPreviousInstaller} to {rhos_long} when your source environment includes Hardware Security Module (HSM) integration.

		Hardware Security Modules provide enhanced security for cryptographic operations by storing encryption keys in dedicated hardware devices. When migrating from {OpenStackPreviousInstaller} to {rhos_acro}, it is essential to preserve HSM functionality and maintain access to HSM-backed secrets.

		include::../modules/proc_configuring-ldap-with-domain-specific-drivers.adoc[leveloffset=+1]

		include::../modules/proc_adopting-key-manager-service.adoc[leveloffset=+1]

	HSM integration is configured through a simple boolean flag (`barbican_hsm_enabled`) during the adoption process.
	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].


		== HSM Integration

		The Key Manager service supports Hardware Security Module (HSM) integration through the PKCS#11 plugin. This enables:

	The Key Manager service supports Hardware Security Module (HSM) integration through the PKCS#11 plugin. This enables:
	The {key_manager} supports HSM integration through the PKCS#11 plugin. This enables:

	This procedure configures the {key_manager} to use the `simple_crypto` back end. For Hardware Security Module (HSM) integration with Proteccio HSM, see xref:adopting-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].
	This procedure configures the {key_manager} to use the `simple_crypto` back end. To configure hardware security module (HSM) integration with Proteccio HSM, see xref:adopting-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].

Add Barbican adoption with Proteccio HSM integration documentation #1058

Are you sure you want to change the base?

Add Barbican adoption with Proteccio HSM integration documentation #1058

Conversation

mauricioharley commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci bot commented Sep 19, 2025

Uh oh!

Uh oh!

klgill commented Oct 2, 2025

Uh oh!

softwarefactory-project-zuul bot commented Oct 6, 2025

Uh oh!

softwarefactory-project-zuul bot commented Oct 6, 2025

Uh oh!

mauricioharley commented Oct 14, 2025

Uh oh!

github-actions bot commented Oct 30, 2025

Uh oh!

klgill commented Dec 19, 2025

Uh oh!

mauricioharley commented Dec 23, 2025

Uh oh!

klgill left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mauricioharley commented Dec 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mauricioharley commented Sep 19, 2025 •

edited

Loading