Skip to content

Commit c9adacc

Browse files
klgillklgill
committed
fixed linting error
1 parent 1401c14 commit c9adacc

12 files changed

Lines changed: 395 additions & 330 deletions

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,22 @@ ifdef::context[:parent-context: {context}]
1010
[role="_abstract"]
1111
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.
1212

13+
For additional information about the {key_manager} before you start the adoption, see the following resources:
14+
15+
* {key_manager} service configuration documentation
16+
* Hardware security module vendor-specific documentation
17+
* OpenStack Barbican PKCS#11 plugin documentation
18+
1319
include::../modules/con_key-manager-service-hsm-adoption-approaches.adoc[leveloffset=+1]
1420

1521
include::../modules/proc_adopting-key-manager-service-with-proteccio-hsm.adoc[leveloffset=+1]
1622

1723
include::../modules/proc_adopting-key-manager-service-with-hsm-integration.adoc[leveloffset=+1]
1824

19-
include::../modules/ref_troubleshooting-key-manager-hsm-adoption.adoc[leveloffset=+1]
25+
include::../assemblies/assembly_troubleshooting-key-manager-hsm-adoption.adoc[leveloffset=+1]
2026

2127
include::../modules/ref_troubleshooting-key-manager-proteccio-adoption.adoc[leveloffset=+1]
2228

23-
[role="_additional-resources"]
24-
== Additional resources
25-
26-
* {key_manager} service configuration documentation
27-
* Hardware security module vendor-specific documentation
28-
* OpenStack Barbican PKCS#11 plugin documentation
2929

3030
ifdef::parent-context[:context: {parent-context}]
3131
ifndef::parent-context[:!context:]

‎docs_user/assemblies/assembly_troubleshooting-key-manager-hsm-adoption.adoc‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
ifdef::context[:parent-context: {context}]
3+
4+
[id="troubleshooting-key-manager-hsm-adoption_{context}"]
5+
6+
= Troubleshooting Key Manager HSM adoption
7+
8+
:context: troubleshooting-hsm
9+
10+
[role="_abstract"]
11+
Review troubleshooting guidance for common issues that you might encounter while you perform the HSM-enabled Key Manager (Barbican) service adoption.
12+
13+
If issues persist after following the troubleshooting guide:
14+
15+
* Collect adoption logs and configuration for analysis.
16+
* Check the HSM vendor documentation for vendor-specific troubleshooting.
17+
* Verify HSM server status and connectivity independently.
18+
* Review the adoption summary report for additional diagnostic information.
19+
20+
include::../modules/proc_resolving-config-validation-failures.adoc[leveloffset=+1]
21+
22+
include::../modules/proc_resolving-missing-HSM-file-prerequisites.adoc[leveloffset=+1]
23+
24+
include::../modules/proc_resolving-connectivity-issues.adoc[leveloffset=+1]
25+
26+
include::../modules/proc_resolving-HSM-secret-creation-failures.adoc[leveloffset=+1]
27+
28+
include::../modules/proc_resolving-custom-image-registry-issues.adoc[leveloffset=+1]
29+
30+
include::../modules/proc_resolving-hsm-backend-detection-failures.adoc[leveloffset=+1]
31+
32+
include::../modules/proc_resolving-database-migration-issues.adoc[leveloffset=+1]
33+
34+
include::../modules/proc_resolving-service-startup-failures.adoc[leveloffset=+1]
35+
36+
include::../modules/proc_resolving-performance-and-connectivity-issues.adoc[leveloffset=+1]
37+
38+
39+
40+
ifdef::parent-context[:context: {parent-context}]
41+
ifndef::parent-context[:!context:]

‎docs_user/modules/proc_resolving-HSM-secret-creation-failures.adoc‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="resolving-HSM-secret-creation-failures_{context}"]
3+
4+
= Resolving HSM secret creation failures
5+
6+
[role="_abstract"]
7+
If hardware security module (HSM) secrets cannot be created in the target environment, check whether you need to update the names of your secrets in your source configuration file.
8+
9+
Example error:
10+
11+
----
12+
TASK [Create HSM secrets in target environment] ****
13+
fatal: [localhost]: FAILED! => {
14+
"msg": "Failed to create secret proteccio-data"
15+
}
16+
----
17+
18+
.Procedure
19+
20+
. Verify target environment access:
21+
+
22+
[source,bash]
23+
----
24+
$ export KUBECONFIG=/path/to/.kube/config
25+
$ oc get secrets -n openstack
26+
----
27+
28+
. Check if secrets already exist:
29+
+
30+
[source,bash]
31+
----
32+
$ oc get secret proteccio-data hsm-login -n openstack
33+
----
34+
35+
. If secrets exist with different names, update the configuration variables:
36+
+
37+
[source,yaml]
38+
----
39+
proteccio_login_secret_name: "your-hsm-login-secret"
40+
proteccio_client_data_secret_name: "your-proteccio-data-secret"
41+
----

‎docs_user/modules/proc_resolving-config-validation-failures.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="resolving-configuration-validation-failures_{context}"]
3+
4+
= Resolving configuration validation failures
5+
6+
[role="_abstract"]
7+
If the adoption fails with validation errors about placeholder values, replace the placeholder values with your environment's configuration values.
8+
9+
Example error:
10+
11+
----
12+
TASK [Validate all required variables are set] ****
13+
fatal: [localhost]: FAILED! => {
14+
"msg": "Required variable proteccio_certs_path contains placeholder value."
15+
}
16+
----
17+
18+
.Procedure
19+
20+
. Edit your hardware security module configuration in the Zuul job vars or CI framework configuration file.
21+
22+
. Check the following key variables and replace all placeholder values with actual configuration values for your environment:
23+
+
24+
----
25+
cifmw_hsm_password: <your_actual_hsm_password>
26+
cifmw_barbican_proteccio_partition: <VHSM1>
27+
cifmw_barbican_proteccio_mkek_label: <your_mkek_label>
28+
cifmw_barbican_proteccio_hmac_label: <your_hmac_label>
29+
cifmw_hsm_proteccio_client_src: <https://your-server/path/to/Proteccio.iso>
30+
cifmw_hsm_proteccio_conf_src: <https://your-server/path/to/proteccio.rc>
31+
----
32+
33+
. Verify that no placeholder values remain in your configuration.

‎docs_user/modules/proc_resolving-connectivity-issues.adoc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="resolving-source-environment-connectivity-issues_{context}"]
3+
4+
= Resolving source environment connectivity issues
5+
6+
[role="_abstract"]
7+
If the adoption cannot connect to the source {rhos_prev_long} environment to extract the configuration, check your SSH connectivity to the source Controller node and update the configuration if needed.
8+
9+
Example error:
10+
11+
----
12+
TASK [detect source environment HSM configuration] ****
13+
fatal: [localhost]: FAILED! => {
14+
"msg": "SSH connection to source environment failed"
15+
}
16+
----
17+
18+
.Procedure
19+
20+
. Verify SSH connectivity to the source Controller node:
21+
+
22+
[source,bash]
23+
----
24+
$ ssh -o StrictHostKeyChecking=no tripleo-admin@controller-0.ctlplane
25+
----
26+
27+
. Update the `controller1_ssh` variable if needed:
28+
+
29+
----
30+
$ controller1_ssh: "ssh -o StrictHostKeyChecking=no tripleo-admin@<controller_ip>"
31+
----
32+
+
33+
where:
34+
35+
`<controller_ip>`::
36+
Specifies the IP address of your Controller node.
37+
38+
. Ensure that the SSH keys are properly configured for passwordless access.

‎docs_user/modules/proc_resolving-custom-image-registry-issues.adoc‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="resolving-custom-image-registry-issues_{context}"]
3+
4+
= Resolving custom image registry issues
5+
6+
[role="_abstract"]
7+
If custom Barbican images cannot be pushed to or pulled from the configured registry, you can verify the authentication, test image push permissions, and then update the configuration as needed.
8+
9+
Example error:
10+
11+
----
12+
TASK [Create Proteccio-enabled Barbican images] ****
13+
fatal: [localhost]: FAILED! => {
14+
"msg": "Failed to push image to registry"
15+
}
16+
----
17+
18+
.Procedure
19+
20+
. Verify registry authentication:
21+
+
22+
[source,bash]
23+
----
24+
$ podman login <registry_url>
25+
----
26+
+
27+
where:
28+
29+
`<registry_url>`::
30+
Specifies the URL of your configured registry.
31+
32+
. Test image push permissions:
33+
+
34+
[source,bash]
35+
----
36+
$ podman tag hello-world <registry>/<namespace>/test:latest
37+
$ podman push <registry>/<namespace>/test:latest
38+
----
39+
+
40+
where:
41+
42+
`<registry>`::
43+
Specifies the name of your registry server.
44+
`<namespace>`::
45+
Specifies the namespace of your container image.
46+
47+
. Update registry configuration variables if needed:
48+
+
49+
[source,yaml]
50+
----
51+
cifmw_update_containers_registry: "your-registry:5001"
52+
cifmw_update_containers_org: "your-namespace"
53+
cifmw_image_registry_verify_tls: false
54+
----

‎docs_user/modules/proc_resolving-database-migration-issues.adoc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="resolving-database-migration-issues_{context}"]
3+
4+
= Resolving database migration issues
5+
6+
[role="_abstract"]
7+
If hardware security module (HSM) metadata is not preserved during database migration, check the database logs for any errors and verify that the source database includes the HSM secrets.
8+
9+
Example error:
10+
11+
----
12+
TASK [Verify database migration preserves HSM references] ****
13+
ok: [localhost] => {
14+
"msg": "HSM secrets found in migrated database: 0"
15+
}
16+
----
17+
18+
.Procedure
19+
20+
. Verify that the source database contains the HSM secrets:
21+
+
22+
[source,bash]
23+
----
24+
$ ssh tripleo-admin@controller-0.ctlplane \
25+
"sudo mysql barbican -e 'SELECT COUNT(*) FROM secret_store_metadata WHERE key=\"plugin_name\" AND value=\"PKCS11\";'"
26+
----
27+
28+
. Check the database migration logs for errors:
29+
+
30+
[source,bash]
31+
----
32+
$ oc logs deployment/barbican-api | grep -i migration
33+
----
34+
35+
. If the migration failed, restore the database from backup and retry.

‎docs_user/modules/proc_resolving-hsm-backend-detection-failures.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="resolving-HSM-back-end-detection-failures_{context}"]
3+
4+
== Resolving HSM back-end detection failures
5+
6+
[role="_abstract"]
7+
If the adoption role cannot detect hardware security module (HSM) configuration in the source environment, you must force the HSM adoption.
8+
9+
Example error:
10+
11+
----
12+
TASK [detect source environment HSM configuration] ****
13+
ok: [localhost] => {
14+
"msg": "No HSM configuration found - using standard adoption"
15+
}
16+
----
17+
18+
.Procedure
19+
20+
. Manually verify that the HSM configuration exists in the source environment:
21+
+
22+
[source,bash]
23+
----
24+
$ ssh tripleo-admin@controller-0.ctlplane \
25+
"sudo grep -A 10 '\[p11_crypto_plugin\]' \
26+
/var/lib/config-data/puppet-generated/barbican/etc/barbican/barbican.conf"
27+
----
28+
29+
. If HSM is configured but not detected, force HSM adoption by setting the `barbican_hsm_enabled` variable:
30+
+
31+
[source,yaml]
32+
----
33+
# In your Zuul job vars or CI framework configuration
34+
barbican_hsm_enabled: true
35+
----
36+
+
37+
This configuration ensures that the `barbican_adoption` role uses the HSM-enabled patch for {key_manager_first_ref} deployment.

‎docs_user/modules/proc_resolving-missing-HSM-file-prerequisites.adoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="resolving-missing-HSM-file-prerequisites_{context}"]
3+
4+
= Resolving missing HSM file prerequisites
5+
6+
[role="_abstract"]
7+
If the adoption fails because hardware security module (HSM) certificates or client software cannot be found, update your configuration to point to the files in their specific locations.
8+
9+
Example error:
10+
11+
----
12+
TASK [Validate Proteccio prerequisites exist] ****
13+
fatal: [localhost]: FAILED! => {
14+
"msg": "Proteccio client ISO not found: /opt/proteccio/Proteccio3.06.05.iso"
15+
}
16+
----
17+
18+
.Procedure
19+
20+
. Verify that all required HSM files are accessible from the configured URLs. For example:
21+
+
22+
[source,bash]
23+
----
24+
$ curl -I https://your-server/path/to/Proteccio3.06.05.iso
25+
$ curl -I https://your-server/path/to/proteccio.rc
26+
$ curl -I https://your-server/path/to/client.crt
27+
$ curl -I https://your-server/path/to/client.key
28+
----
29+
30+
. If the files are in different locations, update the URL variables in your configuration. For example:
31+
+
32+
----
33+
cifmw_hsm_proteccio_client_src: "https://correct-server/path/to/Proteccio3.06.05.iso"
34+
cifmw_hsm_proteccio_conf_src: "https://correct-server/path/to/proteccio.rc"
35+
cifmw_hsm_proteccio_client_crt_src: "https://correct-server/path/to/client.crt"
36+
cifmw_hsm_proteccio_client_key_src: "https://correct-server/path/to/client.key"
37+
----
38+
39+
. Check the network connectivity and authentication to ensure that the URLs are accessible from the CI environment.

‎docs_user/modules/proc_resolving-performance-and-connectivity-issues.adoc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="resolving-performance-and-connectivity-issues_{context}"]
3+
4+
= Resolving performance and connectivity issues
5+
6+
[role="_abstract"]
7+
If the hardware security module (HSM) operations are slow or fail intermittently, check the HSM connectivity and monitor the HSM server logs.
8+
9+
.Procedure
10+
11+
. Test HSM connectivity from {key_manager_first_ref} pods:
12+
+
13+
[source,bash]
14+
----
15+
$ oc exec barbican-api-xyz -- pkcs11-tool --module /usr/lib64/libnethsm.so --list-slots
16+
----
17+
18+
. Check HSM server connectivity:
19+
+
20+
[source,bash]
21+
----
22+
$ oc exec barbican-api-xyz -- nc -zv <hsm_server_ip> <hsm_port>
23+
----
24+
+
25+
where:
26+
27+
`<hsm_server_ip>`::
28+
Specifies the IP address of the HSM server.
29+
`<hsm_port>`::
30+
Specifies the port of your HSM server.
31+
32+
. Monitor HSM server logs for authentication or capacity issues.

0 commit comments

Comments
 (0)