bao-kms-providerSearch GitHub

Documentation

OpenBao Kubernetes KMS Provider

The bao-kms-provider plugin terminates the Kubernetes KMS v2 protocol on a local Unix socket and forwards encrypt and decrypt operations to OpenBao Transit. It participates in Kubernetes envelope encryption for selected API resources before they are persisted to etcd. It 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, while contributors should use Development for local workflow, CI, and release process.

Start Here Read Architecture

Workflow

Read In The Order You Operate

  1. 01

    Check Fit

    Confirm that Kubernetes KMS v2 is the right encryption layer for the resources you care about, and that the OpenBao Transit model matches your trust boundary and version envelope.

    Overview Threat Model Compatibility
  2. 02

    Set Up OpenBao

    Provision a Transit mount, an aes256-gcm96 key, a least-privilege policy, and 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 and AAD shape, and exercise the observability surface before relying on the provider in production.

    First Encrypt Key ID And AAD Observability
  5. 05

    Operate Safely

    Run Transit key rotation, recover from OpenBao or etcd loss, upgrade the provider with rollback in mind, and consult the failure-mode catalog when something breaks.

    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 AAD 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, JWT-first authentication, decrypt validation, and the security review record for each workstream.

Architecture

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