// Module included in the following assemblies:
//
// * security/zero_trust_workload_identity_manager/zero-trust-manager-plugins.adoc

:_mod-docs-content-type: REFERENCE
[id="zero-trust-manager-spire-vault-troubleshooting_{context}"]
= Troubleshooting SPIRE Vault UpstreamAuthority plugin

[role="_abstract"]
Resolve the most common SPIRE Vault upstream authority failures on {product-title}.

[id="zero-trust-manager-vault-quick-reference_{context}"]
== Quick reference

[cols="2,3,1",options="header"]
|===
| Symptom or error | Likely cause | Section

| Connection refused, timeout, or unreachable Vault
| Wrong `vaultAddr` or network path from the SPIRE Server pod
| <<spire-vault-troubleshooting-connection-tls_{context}>>

| `x509: certificate signed by unknown authority`
| Missing or invalid `caCertSecretRef` Secret
| <<spire-vault-troubleshooting-connection-tls_{context}>>

| Vault `403` or Kubernetes auth failure
| Vault role, ServiceAccount binding, or signing policy misconfiguration
| <<spire-vault-troubleshooting-authentication_{context}>>

| `requested TTL ... exceeds max_lease_ttl`
| `caValidity` exceeds the Vault PKI limit
| <<spire-vault-troubleshooting-ttl_{context}>>
|===

[id="spire-vault-troubleshooting-connection-tls_{context}"]
== Connection and TLS errors

*Connection failures*

* Verify `spec.upstreamAuthority.vault.vaultAddr` on the `SpireServer` CR.
* Confirm the SPIRE Server pod can reach Vault from the `zero-trust-workload-identity-manager` namespace.
* For in-cluster Vault, use the Kubernetes service URL, such as `http://vault.vault.svc:8200`.

*TLS failures*

* When Vault uses a custom CA, set `caCertSecretRef` to a Secret in the `zero-trust-workload-identity-manager` namespace with a PEM-encoded CA certificate.
* Confirm the `Secret` name and key match `caCertSecretRef`.
* Omit `caCertSecretRef` only for a public CA or in-cluster HTTP.
* Do not use `insecureSkipVerify: true` in production.

[id="spire-vault-troubleshooting-authentication_{context}"]
== Authentication and signing errors

SPIRE Server uses Vault Kubernetes authentication with the `spire-server` ServiceAccount.

Check the following:

* `k8sAuth.k8sAuthRoleName` on the `SpireServer` CR matches the Vault Kubernetes auth role.
* The Vault role binds to ServiceAccount `spire-server` in namespace `zero-trust-workload-identity-manager`.
* The role policy grants `update` on `<pki_mount>/root/sign-intermediate`.
* `pkiMountPoint` matches the PKI secrets engine mount in Vault.
* `k8sAuth.audience` matches the Vault role when you changed the default from `vault`.

Review SPIRE Server logs:

[source,terminal]
----
$ oc logs statefulset/spire-server -n zero-trust-workload-identity-manager -c spire-server --tail=100
----

[id="spire-vault-troubleshooting-ttl_{context}"]
== TTL mismatch errors

`spec.caValidity` on the `SpireServer` CR must be less than or equal to the Vault PKI `max_lease_ttl`.

* Reduce `caValidity` on the `SpireServer` CR, or increase the Vault PKI limit with `vault secrets tune -max-lease-ttl=...`.

For Vault Enterprise namespace errors, set `spec.upstreamAuthority.vault.vaultNamespace` to the correct namespace path.
