openbao-operator

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, 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: validated in CI on v1.33–v1.35
• OpenBao: validated in CI on 2.5.0, with config compatibility checks for 2.4.4 and upgrade coverage from 2.4.4 to 2.5.0
• 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.
• 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.0"
  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:

• 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 (make bootstrap && make doctor && make ci-core).
• Our AI-Assisted Contribution Policy.

Official OpenBao Documentation

• OpenBao Documentation
• OpenBao Upgrade Guide

License

Apache-2.0. See LICENSE.