Troubleshooting
Start with the health of the connector, which reports every Config Profile separately, and with the log of the failing sidecar, which names the path or setting it could not use. For problems of the Connector resource itself, such as a failed registration or a missing Secret, read its conditions as The Connector CR describes.
| Symptom | Cause | Fix |
|---|---|---|
| A Config Profile is down while its sidecar runs | The address or configId of the profile does not match the sidecar | Compare proxyAddress with the listen address of the sidecar. For SoftHSM, configId is softhsm-default |
A sidecar exits with no PKCS#11 module at /opt/pkcs11/module.so | The image is not finalized, or a volume is mounted over the library | Use the finalized image, and check the volume mounts of the sidecar |
A sidecar exits with cannot be loaded by this image | The base variant or the CPU architecture does not match the vendor library | Build on the -rocky base, and schedule the pod on amd64 nodes for Utimaco and nShield |
A sidecar exits with unknown module in config | The proxy configuration names a module that the proxy does not provide | Use the modules block from the vendor page |
A sidecar exits with address already in use | Two sidecars of a Connector resource listen on the same port | Give each sidecar its own PKCS11_PROXY_LISTEN_ADDRESS, and update its Config Profile and probes |
A vendor sidecar stays in ImagePullBackOff | The pod has no pull secret for the registry of the finalized image | Add one to imagePullSecrets of the Helm chart, or to spec.image.pullSecrets of the Connector |
| Key operations fail with a PIN error | The token rejected the PIN, or has locked it | Correct the secret that the User PIN attribute of the Token references. Unlock a locked PIN on the HSM |
| Requests fail with a temporary service-unavailable error | The sidecar or the HSM partition has no free session | When the partition has spare sessions, raise max_sessions within them. Otherwise reduce the load, or free sessions of other clients |
| A slow operation fails after 35 or 60 seconds, or with a gateway timeout | A timeout on the way of the request expired | Order the timeouts around the slowest operation, see Timeouts |
| Utimaco reports a removed device during a slow command | CommandTimeout expired inside the library | Raise it above the slowest operation and above PKCS11_REQUEST_TIMEOUT, then restart the pod |
| The Securosys sidecar does not start while the HSM is unreachable | connect_on_init is true | Set it to false in primus.cfg |
ppin -t succeeds, but the Securosys profile offers no token | primus.cfg names a partition that the enrolled secret does not cover | Correct the partition in primus.cfg |
| The nShield profile stays down | The HSM is down, does not permit the address of the pod, or the ESN or KNETI hash is wrong | Read the log of the sidecar, then check the source address, the ESN and the KNETI hash |
| The nShield sidecar restarts while the HSM is down | The sidecar has probes | Remove its probes |
| nShield cannot write its key store | The volume does not admit the group of the sidecar | Set an fsGroup that may write the volume |
| nShield keys disappear when the pod is replaced | The key store is not on a persistent volume | Mount a persistent volume at /var/lib/pkcs11-vendor, and restore the key store from its backup |
| SoftHSM cannot initialize its token | The token directory is missing or read-only | Mount a writable volume at /var/lib/pkcs11-vendor/tokens |
| Two connector pods run during an update | The Connector resource rolls with the default rolling update | Set strategy.type: Recreate |