secure k8 s

Internals

Summary: How OpenBao actually works under the hood: the barrier, Raft-based integrated storage, HA mechanics, key rotation, telemetry, security model, and operational limits.

Sources: raw/docs/internals/architecture.md, raw/docs/internals/integrated-storage.md, raw/docs/internals/high-availability.md, raw/docs/internals/rotation.md, raw/docs/internals/security.md, raw/docs/internals/telemetry/*, raw/docs/internals/limits.md, raw/docs/internals/token.md.

Last updated: 2026-05-19

Architecture

OpenBao’s barrier is the encryption layer between core and storage. Storage is untrusted — only encrypted blobs leave the barrier. On unseal, the keyring is decrypted, then audit devices, auth methods, and secrets engines are loaded from their mount tables (source: raw/docs/internals/architecture.md).

Integrated storage (Raft)

OpenBao’s first-party storage backend is a Raft consensus implementation:

  • All nodes run Raft → no external dependency (unlike Consul/Postgres).
  • Active node is the Raft leader; standbys replicate.
  • Autopilot automates dead-server cleanup and stable-server promotion (raw/docs/concepts/integrated-storage/autopilot.md).
  • Transactional storage primitives shipped here (source: raw/blog/2024-10-16-transactions.md, raw/blog/2024-10-27-transaction-details.md).

Details: raw/docs/internals/integrated-storage.md and raw/docs/concepts/integrated-storage/.

High availability mechanics

See high-availability for the operator view. The internals page (raw/docs/internals/high-availability.md) covers request forwarding, client redirection, and how cluster_addr / api_addr interact.

Key rotation

Two distinct rotations (source: raw/docs/internals/rotation.md):

  • Encryption-key rotation (bao operator rotate) — generates a new keyring entry; new writes use it, old reads still work via prior versions.
  • Rekey (bao operator rekey) — regenerates the root key and re-encrypts the keyring under it; needs an unseal-key quorum.

Security model

raw/docs/internals/security.md documents threat assumptions: storage is hostile, network may be observed, processes may be compromised post-unseal. Mitigations: barrier encryption, audit, response wrapping (below), batch tokens, auto-unseal with hardware-backed KMS.

Response wrapping

Any response can be returned wrapped — OpenBao stores the real data in a cubbyhole and returns a single-use wrapping token. The eventual consumer unwraps it. Used to hand secrets across trust boundaries without exposing them to intermediaries (source: raw/docs/concepts/response-wrapping.md).

Tokens internals

raw/docs/internals/token.md covers what’s actually stored for service tokens, accessor IDs, and the token store’s role.

Telemetry

raw/docs/internals/telemetry/index.md documents the metrics emitted; raw/docs/internals/telemetry/metrics/ has the per-subsystem catalog. Configured via the telemetry stanza in configuration.

Limits

raw/docs/internals/limits.md enumerates hard and soft limits: max response size, max request duration, path length, namespace storage limits, etc.

Other concept pages worth knowing

These live under raw/docs/concepts/ but are conceptually internals-adjacent:

  • cel.md — CEL expressions in policies.
  • dev-server.md — bao server -dev mode.
  • duration-format.md — TTL / lease format.
  • mount-migration.md — moving mount data.
  • password-policies.md — generated password rules.
  • pgp-gpg-keybase.md — PGP-encrypted unseal key distribution.
  • recovery-mode.md — booting a corrupted cluster.
  • resource-quotas.md — rate / lease limits.
  • user-lockout.md — failed-login throttling.
  • username-templating.md — DB username templates.