bao-kms-providerSearch GitHub

Documentation

OpenBao Kubernetes KMS Provider

The bao-kms-provider process implements the Kubernetes Key Management Service (KMS) v2 protocol on a local Unix socket. It forwards encrypt and decrypt operations to OpenBao Transit. Kubernetes uses the provider for envelope encryption of selected API resources before persisting them to etcd. The provider does not encrypt etcd disk blocks, application volumes, or node filesystems.

Operators usually move through Start Here , Deployment , Operations , Reference , and Security . Maintainers should use Architecture for design rationale and trust boundaries. Contributors should use Development for local workflow, continuous integration, and release process.

Start Here Read Architecture

Workflow

Read In The Order You Operate

  1. 01

    Check Fit

    Confirm that Kubernetes KMS v2 covers the API resources you plan to encrypt. Check that the OpenBao Transit model matches your trust boundary and tested versions.

    Overview Threat Model Compatibility
  2. 02

    Set Up OpenBao

    Provision a Transit mount, an aes256-gcm96 key, a least-privilege policy, and JSON Web Token (JWT) authentication for the Kubernetes API server identity.

    OpenBao Setup Auth Model Transit Policy Examples
  3. 03

    Install And Wire The Provider

    Install bao-kms-provider, choose between systemd and static-pod deployment, and write the EncryptionConfiguration that the Kubernetes API server consumes.

    Install Choosing A Model EncryptionConfiguration
  4. 04

    Verify End-To-End

    Run the first-encrypt smoke test. Confirm key_id stability, additional authenticated data (AAD), metrics, health endpoints, and redacted logs before production use.

    First Encrypt Key ID And AAD Observability
  5. 05

    Operate And Recover

    Rotate Transit keys, recover from OpenBao or etcd loss, and test provider rollback during upgrades. Use the failure-mode catalog to diagnose faults.

    Rotation Disaster Recovery Troubleshooting

Sections

Documentation Map

Start Here Confirm the deployment fits, set up OpenBao Transit, install the provider, wire Kubernetes encryption, and verify end-to-end. Deployment Choose between systemd and static-pod, then apply the matching Linux identity, file paths, and runtime hardening. Operations Task-focused operator guidance for rotation, disaster recovery, upgrade, and troubleshooting. Reference Exact behavior, configuration shape, KMS v2 contract, key_id and additional authenticated data format, observability surface, and policy boundaries. Security Threat model, hardening, authentication and decrypt validation. Architecture Maintainer-facing design rationale: components, KMS v2 and Transit background, key model, rotation model, failure modes, and prior art. Development Contributor-facing workflow: contributing, code quality, testing, CI, release process, docs style, and the docs site itself.

Reference

Support, Security, And Internals

Reference

CLI behavior, configuration shape, KMS v2 contract, key_id and AAD format, observability surface, and Transit policy boundaries.

Security

Threat model, hardening requirements, JWT-first authentication, decrypt validation, and documented security limitations.

Architecture

Component model, OpenBao Transit key design, rotation invariants, failure-mode catalog, and prior-art comparison.