Skip to content

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:

spec:
  connectionRef:
    name: openbao
  path: obco-pki-root
  type: pki
  maxLeaseTTL: 87600h

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