{"id":50514925,"url":"https://github.com/dc-tec/openbao-kubernetes-kms","last_synced_at":"2026-06-02T23:02:39.716Z","repository":{"id":357718098,"uuid":"1233208549","full_name":"dc-tec/openbao-kubernetes-kms","owner":"dc-tec","description":"OpenBao-native Kubernetes KMS v2 provider for etcd encryption at rest using OpenBao Transit.","archived":false,"fork":false,"pushed_at":"2026-05-25T19:31:50.000Z","size":8209,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T21:26:07.240Z","etag":null,"topics":["etcd-encryption","golang","kubernetes-kms","openbao","openbao-transit"],"latest_commit_sha":null,"homepage":"https://dc-tec.github.io/openbao-kubernetes-kms/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dc-tec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T17:55:56.000Z","updated_at":"2026-05-25T19:31:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dc-tec/openbao-kubernetes-kms","commit_stats":null,"previous_names":["dc-tec/openbao-kubernetes-kms"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dc-tec/openbao-kubernetes-kms","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dc-tec%2Fopenbao-kubernetes-kms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dc-tec%2Fopenbao-kubernetes-kms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dc-tec%2Fopenbao-kubernetes-kms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dc-tec%2Fopenbao-kubernetes-kms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dc-tec","download_url":"https://codeload.github.com/dc-tec/openbao-kubernetes-kms/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dc-tec%2Fopenbao-kubernetes-kms/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33840214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["etcd-encryption","golang","kubernetes-kms","openbao","openbao-transit"],"created_at":"2026-06-02T23:02:35.782Z","updated_at":"2026-06-02T23:02:39.710Z","avatar_url":"https://github.com/dc-tec.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenBao Kubernetes KMS\n\n[![CI](https://github.com/dc-tec/openbao-kubernetes-kms/actions/workflows/ci.yml/badge.svg)](https://github.com/dc-tec/openbao-kubernetes-kms/actions/workflows/ci.yml)\n[![Release](https://github.com/dc-tec/openbao-kubernetes-kms/actions/workflows/release.yml/badge.svg)](https://github.com/dc-tec/openbao-kubernetes-kms/actions/workflows/release.yml)\n[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://dc-tec.github.io/openbao-kubernetes-kms/)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n\n`bao-kms-provider` is a node-local Kubernetes KMS v2 provider backed by\nOpenBao Transit. It lets `kube-apiserver` envelope-encrypt selected Kubernetes\nAPI resources in etcd while keeping KMS protocol handling, OpenBao\nauthentication, Transit key-version selection, and decrypt validation in a\ndedicated provider process.\n\nThe provider is designed for Kubernetes control planes that want an\nOpenBao-native KMS integration without making the API server call OpenBao\nTransit directly.\n\n\u003e [!IMPORTANT]\n\u003e `bao-kms-provider` is currently a preview release. Use it for labs, staging,\n\u003e and evaluation of the deployment model. Do not use preview releases for\n\u003e production control planes, and treat only the versions and configurations in\n\u003e the compatibility matrix as tested.\n\n## Why It Exists\n\nOpenBao Transit can encrypt and decrypt caller-supplied data. Kubernetes does\nnot call Transit directly; it talks to a local KMS provider plugin over a Unix\ndomain socket. `bao-kms-provider` adapts those two contracts and adds the\nKubernetes-specific correctness rules around:\n\n- stable, opaque Kubernetes `key_id` values,\n- Transit `associated_data` binding,\n- explicit Transit `key_version` on encrypt,\n- local validation before Transit decrypt,\n- rotation and rollback safety,\n- node-local socket ownership and hardening,\n- redacted metrics, logs, diagnostics, and reports.\n\n## How It Fits\n\n```mermaid\nflowchart LR\n    API[\"kube-apiserver\"]\n    Socket[\"Unix socket\u003cbr/\u003e/run/openbao-kms/kms.sock\"]\n    Provider[\"bao-kms-provider\"]\n    Auth[\"OpenBao auth\u003cbr/\u003eJWT or scoped cert auth\"]\n    Transit[\"OpenBao Transit\u003cbr/\u003eexplicit key_version + AAD\"]\n    Etcd[\"etcd\u003cbr/\u003eKMS v2 envelope\"]\n\n    API --\u003e Socket --\u003e Provider\n    Provider --\u003e Auth --\u003e Transit\n    API --\u003e Etcd\n```\n\nThe provider runs on each control-plane host. It does not depend on the\nprotected Kubernetes API server to operate, which is required because the API\nserver may need the KMS plugin during startup to read encrypted resources.\n\n## Current Scope\n\n| Area | Current state |\n|---|---|\n| Kubernetes API | KMS v2 only. KMS v1 is not implemented. |\n| Kubernetes target | Tested against Kubernetes `1.34` and `1.35` Kind node images pinned by digest. Kubernetes `1.36` is the intended next test line once a pinned Kind image is available. Kubernetes `1.29+` KMS v2 clusters may work, but are covered only when listed in `.ci/versions.yaml`. |\n| OpenBao target | OpenBao `2.5.3` with Transit. JWT auth is the default preview auth path. |\n| Transit key type | `aes256-gcm96` is the supported and recommended default. |\n| Authentication | JWT auth by default. PKCS#11 certificate auth is opt-in and covered only when a release publishes matching artifacts and marks the path as tested. SPIFFE/SPIRE is not a supported preview configuration. OpenBao tokens stay in process memory. |\n| Deployment models | Hardened systemd unit or kubelet-managed static pod. |\n| Release maturity | Preview release line; see the [Support Policy](https://dc-tec.github.io/openbao-kubernetes-kms/reference/support-policy/). |\n| Release cadence | Event-driven releases, scheduled validation. |\n| Supply chain | Vendored builds, SBOMs, signed checksums, image signatures, provenance attestations, vulnerability scans, and reproducibility reports for public releases. |\n\nPreview support is limited to the tested matrix. Newer or adjacent Kubernetes,\nOpenBao, OS, key-type, auth, or deployment combinations are not automatically\ncovered. See the\n[Compatibility](https://dc-tec.github.io/openbao-kubernetes-kms/reference/compatibility/)\nmatrix for details.\n\n## Security Posture\n\n`bao-kms-provider` is control-plane critical software. If the provider socket,\nauth credential, OpenBao endpoint, or Transit key is unavailable,\n`kube-apiserver` may be unable to decrypt previously encrypted resources during\nstartup.\n\nThe implementation is built around fail-closed behavior:\n\n- decrypt rejects malformed or unknown `key_id` values before Transit is called,\n- decrypt requires valid KMS annotations and AAD reconstruction,\n- ciphertext is bound to provider, cluster, OpenBao instance, Transit mount,\n  key lineage, and Transit key version,\n- Status reads from cached state and does not perform live Transit decrypts,\n- the plugin does not create, rotate, export, delete, or back up Transit keys,\n- logs and metrics do not expose plaintext, JWTs, OpenBao tokens, full\n  ciphertext, raw Transit key material, raw OpenBao paths, or raw key names.\n\nFor the full model, start with\n[Threat Model](https://dc-tec.github.io/openbao-kubernetes-kms/security/threat-model/),\n[Hardening](https://dc-tec.github.io/openbao-kubernetes-kms/security/hardening/),\nand\n[AAD And Decrypt Validation](https://dc-tec.github.io/openbao-kubernetes-kms/security/aad-and-decrypt-validation/).\n\n## Deployment Models\n\n| Model | Use when | Notes |\n|---|---|---|\n| systemd | You control the host operating-system lifecycle and can install the provider before kubelet starts. | Preferred when host management and package rollback are available. |\n| Static pod | The control plane is kubeadm-style and every node can preload or reliably pull the provider image by digest. | Fits teams already operating hostPath-mounted control-plane static pods. |\n| DaemonSet | Not for protecting the same cluster's API server. | DaemonSets depend on the API server they would be required to unlock. |\n\nStart with\n[Deployment: Choosing A Model](https://dc-tec.github.io/openbao-kubernetes-kms/deployment/choosing-a-model/)\nbefore installing either deployment form.\n\n## What It Does Not Do\n\n`bao-kms-provider` does not:\n\n- encrypt raw etcd disk blocks or etcd snapshots,\n- encrypt PersistentVolumes, node filesystems, pod filesystems, or API traffic,\n- manage the lifecycle of the OpenBao Transit key,\n- provide a Helm chart that installs into the protected cluster,\n- support same-cluster DaemonSet deployment for the protected API server,\n- enable decrypt micro-batching in the current release line,\n- support production use while the release line remains preview.\n\n## Start Here\n\nThe user documentation is published on GitHub Pages:\n\n1. [Overview](https://dc-tec.github.io/openbao-kubernetes-kms/getting-started/overview/)\n2. [OpenBao Setup](https://dc-tec.github.io/openbao-kubernetes-kms/getting-started/openbao-setup/)\n3. [Install](https://dc-tec.github.io/openbao-kubernetes-kms/getting-started/install/)\n4. [Deployment: Choosing A Model](https://dc-tec.github.io/openbao-kubernetes-kms/deployment/choosing-a-model/)\n5. [Kubernetes EncryptionConfiguration](https://dc-tec.github.io/openbao-kubernetes-kms/getting-started/kubernetes-encryption-config/)\n6. [First Encrypt](https://dc-tec.github.io/openbao-kubernetes-kms/getting-started/first-encrypt/)\n\nRelease artifact verification is documented in\n[Getting Started: Install](https://dc-tec.github.io/openbao-kubernetes-kms/getting-started/install/#verify-release-artifacts).\n\n## Build And Test\n\nThe repository commits `vendor/` and CI uses `GOFLAGS=-mod=vendor`.\n\n```sh\nmake ci-core\nmake build\nbin/bao-kms-provider version\n```\n\nPublic releases produce JWT-only auth artifacts by default.\nCertificate auth variants are separate opt-in build tags:\n\n```sh\nmake build-certauth-pkcs11\n```\n\nPKCS#11 cert-auth artifacts are separate host CGO builds via\n`make release-artifact-certauth-pkcs11-host`.\n\nSPIFFE certificate-source code remains in tree for local verification, but\n`auth.cert.source: spiffe` is not a supported preview user configuration.\n\nSelected E2E entrypoints:\n\n```sh\nmake test-e2e-openbao-ci\nmake test-e2e-provider-certauth-sources-openbao-ci\nmake test-e2e-provider-ha-openbao-ci\nmake test-e2e-kind-smoke\n```\n\nBuild a local container image:\n\n```sh\nmake image\n```\n\nBuild release binaries, packages, and bundles locally:\n\n```sh\nmake release-distribution\n```\n\nLocal kubeadm VM validation is intentionally outside public CI because it\nrestarts API servers and validation VMs, and intentionally stops OpenBao in the\ntest environment. Maintainer notes live with the harness code under\n`hack/harvester/`.\n\n## Release Verification\n\nTagged releases publish GitHub Release assets and a GHCR image. Public release\nverification materials include:\n\n- SHA-256 checksums,\n- keyless checksum signature bundle,\n- SBOMs for published binaries and images,\n- image signatures,\n- GitHub build-provenance attestations,\n- release artifact attestation verification output,\n- vulnerability scan summary,\n- reproducibility report,\n- `provenance-index.json`,\n- release notes.\n\nRelease policy is documented in\n[Reference: Release Policy](https://dc-tec.github.io/openbao-kubernetes-kms/reference/release-policy/).\n\n## Upstream References\n\n- [Kubernetes: Using a KMS provider for data encryption](https://kubernetes.io/docs/tasks/administer-cluster/kms-provider/)\n- [Kubernetes: Encrypting confidential data at rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/)\n- [Kubernetes: Static Pods](https://kubernetes.io/docs/tasks/configure-pod-container/static-pod/)\n- [OpenBao Transit API](https://openbao.org/api-docs/secret/transit/)\n- [OpenBao JWT/OIDC auth API](https://openbao.org/api-docs/auth/jwt/)\n- [OpenBao TLS certificates auth method](https://openbao.org/docs/auth/cert/)\n- [SPIFFE Workload API](https://spiffe.io/docs/latest/spiffe-specs/spiffe_workload_api/)\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdc-tec%2Fopenbao-kubernetes-kms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdc-tec%2Fopenbao-kubernetes-kms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdc-tec%2Fopenbao-kubernetes-kms/lists"}