Secure lifecycle management for OpenBao on Kubernetes.

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.

Installation, Operations, Day-2 Tasks	Component Design, Boundaries, Flows
Threat Model, Hardening, RBAC	Dev Setup, Coding Standards, Release
Validated K8s/OpenBao Versions	Ready-to-apply Example Manifests

Recommended entry points:

• Deployment Decision Guide
• Operator Invariants
• Production Checklist

Compatibility

For full details, see the Compatibility Matrix.

• Kubernetes: requires v1.33+; release validation runs on v1.34–v1.36
• OpenBao: primary validation on 2.6.2, with config compatibility checks for 2.4.4, 2.5.5, and 2.6.2
• 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 (Tenant Boundaries)
• Guardrails: Validating admission policies that block dangerous settings before they reach the cluster (Admission Policies)
• Multi-tenancy: Namespace isolation guarantees and limits (Tenant Boundaries)

Quick Start

Install and verify the operator before continuing. If it is not running, complete Installation first. 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.6.2"
  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 wait \
  --for=condition=Provisioned \
  openbaotenant/openbao-demo \
  --timeout=2m

kubectl apply -f cluster.yaml

# Wait for the cluster, then inspect its Pods.
kubectl -n openbao-demo wait \
  --for=condition=Available \
  openbaocluster/my-cluster \
  --timeout=10m
kubectl -n openbao-demo get pods -l openbao.org/cluster=my-cluster

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:

• Deployment Decision Guide
• Operator Installation
• Onboard the Target Namespace
• Create Your First Cluster
• Security Profiles
• Production Checklist
• Production samples in config/samples/production/

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 (devenv test followed by the operator:bootstrap, operator:doctor, and operator:ci-core Devenv tasks).
• Our AI-Assisted Contribution Policy.

Official OpenBao Documentation

• OpenBao Documentation
• OpenBao Upgrade Guide

License

Apache-2.0. See LICENSE.