PKI¶
This guide builds a two-tier certificate authority in OpenBao from Kubernetes resources: a root CA, an intermediate CA signed by it, and a role that issues certificates from the intermediate.
Before you begin¶
A Ready connection whose OpenBao policy allows sys/mounts/<mount> for both mounts, and
<mount>/* paths for issuers, keys, configuration and roles
(OpenBao policy for the operator).
1. Enable two PKI mounts¶
Create one SecretsMount with type: pki for the root (obco-pki-root) and one for the
intermediate (obco-pki-int). Raise maxLeaseTTL to at least the lifetime of the certificates
each mount signs, as in this fragment of a spec:
2. Create the issuers¶
A PKIIssuer with type: root generates a self-signed CA. One with type: intermediate and a
signer is signed by another issuer, so the chain is built without copying a CSR by hand. The
file holds a root, an intermediate signed by it through signer.issuerRef, and a second
intermediate that uses an existing key:
examples/secrets/pkiissuer.yaml
# Generates an EC P-384 root CA issuer inside OpenBao on the obco-pki-root mount.
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: PKIIssuer
metadata:
name: obco-root-2026
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Orphan
driftDetection: Enabled
mountPath: obco-pki-root
name: obco-root-2026
type: root
key:
source: internal
name: obco-root-2026-key
type: ec
bits: 384
certificate:
commonName: OBCO Sandbox Root CA 2026
altNames:
- root-ca.openbao-config.example.com
- pki@openbao-config.example.com
ipSANs:
- 192.0.2.10
uriSANs:
- spiffe://openbao-config.example.com/ca/root
otherSANs:
- 1.3.6.1.4.1.311.20.2.3;UTF8:root-ca@openbao-config.example.com
excludeCNFromSANs: true
ou:
- Platform
organization:
- OBCO Sandbox
country:
- DE
locality:
- Berlin
province:
- Berlin
streetAddress:
- Example Street 1
postalCode:
- "10115"
serialNumber: obco-root-2026
ttl: 87600h
notBeforeDuration: 30s
maxPathLength: 1
permittedDNSDomains:
- openbao-config.example.com
signatureBits: 384
usePSS: false
leafNotAfterBehavior: err
usage:
- issuing-certificates
- crl-signing
- ocsp-signing
manualChain:
- obco-root-2026
revocationSignatureAlgorithm: ECDSAWithSHA384
issuingCertificates:
- https://openbao.openbao-config.example.com/v1/openbao-config/obco-pki-root/issuer/obco-root-2026/der
crlDistributionPoints:
- https://openbao.openbao-config.example.com/v1/openbao-config/obco-pki-root/issuer/obco-root-2026/crl/der
ocspServers:
- https://openbao.openbao-config.example.com/v1/openbao-config/obco-pki-root/ocsp
enableAIAURLTemplating: false
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: PKIIssuer
metadata:
name: obco-int-2026
namespace: openbao-config
spec:
connectionRef:
name: openbao
deletionPolicy: Orphan
mountPath: obco-pki-int
type: intermediate
key:
source: exported
name: obco-int-2026-key
type: ec
bits: 256
privateKeyFormat: pkcs8
certificate:
commonName: OBCO Sandbox Intermediate CA 2026
organization:
- OBCO Sandbox
notAfter: "2031-01-01T00:00:00Z"
maxPathLength: 0
permittedDNSDomains:
- openbao-config.example.com
addBasicConstraints: false
signer:
issuerRef:
name: obco-root-2026
writeSecretRef:
name: obco-int-2026-private-key
leafNotAfterBehavior: truncate
usage:
- issuing-certificates
- crl-signing
enableAIAURLTemplating: true
issuingCertificates:
- "{{cluster_aia_path}}/issuer/{{issuer_id}}/der"
crlDistributionPoints:
- "{{cluster_aia_path}}/issuer/{{issuer_id}}/crl/der"
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: PKIIssuer
metadata:
name: obco-int-2026b
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: obco-pki-int
type: intermediate
key:
source: existing
existing:
keyRef:
name: obco-int-key
certificate:
commonName: OBCO Sandbox Intermediate CA 2026b
ttl: 43800h
signer:
mountPath: obco-pki-root
issuerName: obco-root-2026
key.source chooses where the key comes from: internal (the default) keeps it in OpenBao,
exported also writes it once to the Secret in writeSecretRef, existing reuses a key already
stored in the mount, such as one a PKIKey created, and kms uses an OpenBao external key:
examples/secrets/pkikey.yaml
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: PKIKey
metadata:
name: obco-int-key
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Orphan
driftDetection: Enabled
mountPath: obco-pki-int
name: obco-int-key
type: internal
keyType: ec
keyBits: 256
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: PKIKey
metadata:
name: obco-exported-key
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: obco-pki-int
type: exported
keyType: rsa
keyBits: 4096
writeSecretRef:
name: obco-exported-key-private
---
apiVersion: v1
kind: Secret
metadata:
name: obco-imported-key
namespace: openbao-config
type: Opaque
stringData:
key.pem: fake-pem-private-key-not-real
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: PKIKey
metadata:
name: obco-imported-key
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: obco-pki-int
type: import
pemBundleSecretRef:
name: obco-imported-key
key: key.pem
With the default deletionPolicy: Orphan, deleting the resource keeps the CA. Delete removes it
only while the resource carries the annotation openbaoconfig.io/allow-destructive-delete: "true".
3. Configure the mounts¶
A PKIConfig sets the URLs written into certificates, the CRL and OCSP settings and the default
issuer of a mount:
examples/secrets/pkiconfig.yaml
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: PKIConfig
metadata:
name: obco-pki-int
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Orphan
driftDetection: Enabled
mountPath: obco-pki-int
cluster:
path: https://openbao.openbao-config.example.com/v1/openbao-config/obco-pki-int
aiaPath: http://openbao.openbao-config.example.com/v1/openbao-config/obco-pki-int
urls:
issuingCertificates:
- "{{cluster_aia_path}}/issuer/{{issuer_id}}/der"
crlDistributionPoints:
- "{{cluster_aia_path}}/issuer/{{issuer_id}}/crl/der"
deltaCRLDistributionPoints:
- "{{cluster_aia_path}}/issuer/{{issuer_id}}/crl/delta/der"
ocspServers:
- "{{cluster_path}}/ocsp"
enableTemplating: true
crl:
expiry: 72h
disable: false
ocspDisable: false
ocspExpiry: 12h
autoRebuild: true
autoRebuildGracePeriod: 12h
enableDelta: true
deltaRebuildInterval: 15m
allowExpiredCertRevocation: false
issuers:
default:
issuerRef:
name: obco-int-2026
defaultFollowsLatestIssuer: false
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: PKIConfig
metadata:
name: obco-pki-root
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: obco-pki-root
issuers:
default:
issuerName: obco-root-2026
PKIAutoTidy and PKIACMEConfig configure tidying and ACME on a mount
(examples/secrets/pkiautotidy.yaml,
examples/secrets/pkiacmeconfig.yaml).
4. Create a role¶
A PKIRole says which certificates a mount may issue. issuer.issuerRef names the PKIIssuer
resource:
examples/secrets/pkirole.yaml
# A certificate role on the intermediate CA mount that issues 24-hour certificates for subdomains of
# openbao-config.example.com, including a domain templated from the requester's entity metadata.
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: PKIRole
metadata:
name: obco-web
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Delete
driftDetection: Enabled
mountPath: obco-pki-int
name: obco-web
issuer:
issuerRef:
name: obco-int-2026
ttl: 24h
maxTTL: 720h
allowLocalhost: false
allowedDomains:
- openbao-config.example.com
- "{{identity.entity.metadata.team}}.openbao-config.example.com"
allowedDomainsTemplate: true
allowGlobsInIdentityTemplates: false
allowBareDomains: false
allowSubdomains: true
allowGlobDomains: false
allowWildcardCertificates: false
allowAnyName: false
enforceHostnames: true
allowIPSANs: true
allowedIPSANsCIDR:
- 10.0.0.0/8
allowedURISANs:
- spiffe://openbao-config.example.com/*
allowedURISANsTemplate: false
allowedOtherSANs:
- 1.3.6.1.4.1.311.20.2.3;UTF8:*@openbao-config.example.com
allowedSerialNumbers:
- obco-*
allowedUserIDs:
- "*"
serverFlag: true
clientFlag: true
codeSigningFlag: false
emailProtectionFlag: false
keyType: ec
keyBits: 256
signatureBits: 256
usePSS: false
keyUsage:
- DigitalSignature
- KeyAgreement
extKeyUsage:
- ServerAuth
- ClientAuth
extKeyUsageOIDs:
- 1.3.6.1.5.5.7.3.1
useCSRCommonName: true
useCSRSANs: true
ou:
- Platform
organization:
- OBCO Sandbox
country:
- DE
locality:
- Berlin
province:
- Berlin
streetAddress:
- Example Street 1
postalCode:
- "10115"
generateLease: false
noStore: false
requireCN: true
cnValidations:
- hostname
policyIdentifiers:
- 1.3.6.1.4.1.44947.1.1.1
basicConstraintsValidForNonCA: false
notBeforeDuration: 30s
notBefore: "2026-01-01T00:00:00Z"
notBeforeBound: permit
notAfter: "2030-01-01T00:00:00Z"
notAfterBound: ttl-limited
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: PKIRole
metadata:
name: obco-acme
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: obco-pki-int
issuer:
issuerName: obco-int-2026
allowedDomains:
- acme.openbao-config.example.com
allowSubdomains: true
maxTTL: 2160h
5. Check that it worked¶
kubectl -n openbao-config get pkiissuers,pkikeys,pkiconfigs,pkiroles
bao write obco-pki-int/issue/obco-web common_name=app.openbao-config.example.com ttl=1h
Every resource shows Ready True, and OpenBao returns a certificate signed by the
intermediate, with the root in its chain.
Troubleshooting¶
| symptom | check |
|---|---|
the intermediate reports ReferenceNotReady |
the signing issuer in signer exists and is Ready |
| issuing fails with a TTL error | the mount's maxLeaseTTL and the role's maxTTL against the requested TTL; leafNotAfterBehavior of the issuer |
issuing fails with common name not allowed |
allowedDomains, allowSubdomains and allowBareDomains on the role |
Related¶
- API reference: PKIIssuer, PKIKey, PKIConfig, PKIRole, PKIAutoTidy, PKIACMEConfig.