Home
Softono
openbao-operator

openbao-operator

Open source Apache-2.0 Go
Website GitHub
17
Stars
3
Forks
3
Issues
1
Watchers
1 week
Last Commit
Secret Management

About openbao-operator

The OpenBao Operator manages the lifecycle of OpenBao clusters on Kubernetes. It handles the orchestration complexity, PKI, backups, upgrades, and secure multi-tenancy, so you can focus on consuming secrets.

Platforms

Web Self-hosted Kubernetes

Languages

Go

Links

Website Source Code
d
Published by
dc-tec
Visit View Profile

README.md

View on GitHub
OpenBao Operator

Secure lifecycle management for OpenBao on Kubernetes.

CI Go Version License Docs Artifact Hub

Quick Start • Installation • Compatibility • Documentation • Contributing

[!WARNING] Pre-GA Release: OpenBao Operator is intended for real deployments, but the CRD API remains v1alpha1, minor releases may introduce breaking changes, and support is best-effort for the latest stable line only. For production, use the Hardened profile, keep admission enforcement enabled, pin explicit versions, and validate upgrades in staging.

OpenBao Operator is a Kubernetes operator for OpenBao that automates lifecycle management: provisioning, TLS, backups/restores, upgrades, horizontal read scaling, and multi-tenancy controls.

Documentation

Full documentation is available at dc-tec.github.io/openbao-operator.
User Guide Architecture
Installation, Operations, Day-2 Tasks Component Design, Boundaries, Flows
Security Contributing
Threat Model, Hardening, RBAC Dev Setup, Coding Standards, Release
Compatibility Samples
Validated K8s/OpenBao Versions Ready-to-apply Example Manifests

Recommended entry points:

Compatibility

For full details, see the Compatibility Matrix.

  • Kubernetes: requires v1.33+; release validation runs on v1.34–v1.35
  • OpenBao: primary validation on 2.5.4, with config compatibility checks for 2.4.4 and 2.5.4
  • Support posture: best-effort support for the latest stable release line

CRDs (API Surface)

  • OpenBaoCluster: Deploy and operate an OpenBao cluster (TLS, unseal, backups, upgrades).
  • OpenBaoRestore: Restore a cluster from a backup (separate controller).
  • OpenBaoTenant: Multi-tenant provisioning flow (multi-tenant mode).

Features

  • Two-Controller Architecture: Separate controller and provisioner components with least-privilege RBAC boundaries.
  • Security Profiles with Guardrails: Development vs Hardened, enforced by admission policies to prevent insecure combinations.
  • Self-Init + OIDC Bootstrap: OpenBao self-initialization, with optional JWT/OIDC bootstrap via spec.selfInit.oidc.enabled.
  • TLS, Your Way: Operator-managed TLS with rotation, external TLS, and ACME mode where OpenBao owns certificates (with ACME challenge Service support).
  • Streaming Raft Backups: Snapshot streaming to S3/GCS/Azure with retention controls (no local staging).
  • Declarative Restores: Restore workflows via OpenBaoRestore with operation locking and safe overrides.
  • Safe Upgrades: Rolling and blue/green upgrade strategies, including pre-upgrade snapshots. RollingUpdate is the default recommended strategy.
  • Horizontal Read Scaling: Steady-state read replicas as non-voters, with a dedicated read Service and a shared primary endpoint that can include read replicas.
  • Multi-Tenancy: Namespace-scoped tenancy model with policy enforcement via OpenBaoTenant. Multi-tenant mode is the default and recommended production operating model.

Security Model

  • Threat model: Design assumptions and attacker model (Threat Model)
  • RBAC boundaries: Least-privilege split between controller and provisioner (RBAC)
  • Guardrails: Validating admission policies that block dangerous settings before they reach the cluster (Admission Policies)
  • Multi-tenancy: Namespace isolation guarantees and limits (Tenant Isolation)

Quick Start

Once the operator is running, the next move depends on the tenancy mode you chose:

  • Multi-tenant (default): Create the target namespace, onboard it through OpenBaoTenant, then apply the first OpenBaoCluster.
  • Single-tenant: Skip OpenBaoTenant and create the first OpenBaoCluster directly in the controller's watched namespace.

Option A: Evaluation (Development Profile)

# cluster.yaml
apiVersion: openbao.org/v1alpha1
kind: OpenBaoCluster
metadata:
  name: my-cluster
  namespace: openbao-demo
spec:
  version: "2.5.4"
  replicas: 1
  profile: Development
  tls:
    enabled: true
    mode: OperatorManaged
  storage:
    size: "10Gi"
kubectl create namespace openbao-demo

# Default multi-tenant mode only: onboard the target namespace first.
# Single-tenant mode: skip this OpenBaoTenant and apply cluster.yaml
# directly in the controller's watched namespace instead.
kubectl apply -f - <<'EOF'
apiVersion: openbao.org/v1alpha1
kind: OpenBaoTenant
metadata:
  name: openbao-demo
  namespace: openbao-demo
spec:
  targetNamespace: openbao-demo
EOF

kubectl -n openbao-demo get openbaotenant openbao-demo -w

kubectl apply -f cluster.yaml

# Watch status and pods
kubectl -n openbao-demo get openbaoclusters my-cluster -w
kubectl -n openbao-demo get pods -l openbao.org/cluster=my-cluster -w

If spec.selfInit.enabled is false (default), the operator stores a root token in Secret/openbao-demo/my-cluster-root-token (key: token).

kubectl -n openbao-demo get secret my-cluster-root-token -o jsonpath='{.data.token}' | base64 -d; echo

Option B: Production (Hardened Profile)

The default production path is:

  • Multi-tenant mode
  • Target namespace onboarded through OpenBaoTenant before the first cluster
  • Hardened profile
  • spec.selfInit.enabled: true
  • spec.tls.mode: External or ACME
  • spec.upgrade.strategy: RollingUpdate
  • Admission policies enabled

The Hardened profile enforces:

  • External/ACME TLS (spec.tls.mode)
  • External unseal (spec.unseal.type)
  • Self-init enabled (spec.selfInit.enabled: true)

Start with:

Installation

Option 1: Helm (Recommended)

Install the operator from our OCI registry.

# 1. Create namespace
kubectl create namespace openbao-operator-system

# 2. Install/upgrade chart
helm upgrade --install openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \
  --version <chart-version> \
  --namespace openbao-operator-system

If you install the operator into a custom namespace, replace openbao-operator-system consistently in the install, verification, and uninstall commands.

Find the chart in Artifact Hub (indexing may lag shortly after releases): Artifact Hub search: openbao-operator

Option 2: Plain YAML

Apply a pinned release manifest directly.

kubectl apply -f https://github.com/dc-tec/openbao-operator/releases/download/X.Y.Z/install.yaml

Replace X.Y.Z with the exact release you intend to run. Use latest only for throwaway evaluation, not for production installs.

Uninstall

Helm

helm uninstall openbao-operator --namespace openbao-operator-system

Plain YAML

kubectl delete -f https://github.com/dc-tec/openbao-operator/releases/download/X.Y.Z/install.yaml

[!NOTE] The operator installation includes CRDs. If you want to remove CRDs as well, delete the openbao.org/* CRDs after uninstalling (this will delete all custom resources).

Contributing

We welcome contributions! Please see the Contributing Guide for details on:

  • Setting up your development environment.
  • Running the PR-equivalent local gate (make bootstrap && make doctor && make ci-core).
  • Our AI-Assisted Contribution Policy.

Official OpenBao Documentation

License

Apache-2.0. See LICENSE.