Skip to content

Single-Tenant Mode

Single-tenant mode deploys only the Controller component, optimized for individual teams managing their own OpenBao cluster without multi-namespace orchestration.

Overview

  • Target Audience

    Individual teams deploying OpenBao for their application.

  • Performance

    Event-driven reconciliation with namespace-scoped caching.

  • Simplicity

    Controller only—no Provisioner or OpenBaoTenant required.

Architecture

In single-tenant mode, the Controller directly manages resources in a single namespace using efficient event-driven watches.

graph LR
    subgraph OperatorNS["openbao-operator-system"]
        Controller["Controller"]
    end

    subgraph TargetNS["Target Namespace"]
        Cluster["OpenBaoCluster"]
        STS["StatefulSet"]
        SVC["Services"]
    end

    Controller -->|Owns| Cluster
    Cluster -.->|Creates| STS
    Cluster -.->|Creates| SVC

    classDef write fill:transparent,stroke:#22c55e,stroke-width:2px,color:#fff;
    classDef read fill:transparent,stroke:#60a5fa,stroke-width:2px,color:#fff;

    class Controller write;
    class Cluster,STS,SVC read;

Comparison

Feature Multi-Tenant (Default) Single-Tenant
Components Controller + Provisioner Controller only
RBAC Model Per-namespace via OpenBaoTenant Direct RoleBinding
Reconciliation Polling (cluster-wide) Event-driven (cached)
Use Case Platform teams, shared infrastructure Individual teams, dedicated clusters

Installation

Deploy with tenancy mode set to single:

helm install openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \
  --namespace openbao-operator-system \
  --create-namespace \
  --set tenancy.mode=single \
  --set tenancy.targetNamespace=openbao  # (1)!
  1. The namespace where you will deploy your OpenBaoCluster. Defaults to the release namespace if not specified.

Configuration Options

Parameter Description Default
tenancy.mode Set to single for single-tenant mode multi
tenancy.targetNamespace Target namespace for the controller "" (release namespace)
controller.replicas Controller replica count 1
controller.resources Resource requests/limits See values.yaml
admissionPolicies.enabled Enable ValidatingAdmissionPolicies true

Provisioner Excluded

In single-tenant mode, the Provisioner deployment, its ServiceAccounts, and related RBAC are automatically excluded.

For manual deployment without Helm:

1. Apply CRDs

kubectl apply -f https://github.com/dc-tec/openbao-operator/releases/latest/download/crds.yaml

2. Apply ClusterRole

kubectl apply -f https://raw.githubusercontent.com/dc-tec/openbao-operator/main/config/rbac/single_tenant_clusterrole.yaml

3. Create Namespace and RoleBinding

apiVersion: v1
kind: Namespace
metadata:
  name: openbao
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: openbao-operator-controller
  namespace: openbao  # (1)!
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: openbao-operator-single-tenant
subjects:
- kind: ServiceAccount
  name: openbao-operator-controller
  namespace: openbao-operator-system
  1. The target namespace where OpenBaoCluster will be deployed.

4. Patch Controller Deployment

Add the WATCH_NAMESPACE environment variable:

kubectl set env deployment/openbao-operator-controller \
  -n openbao-operator-system \
  WATCH_NAMESPACE=openbao

Verify Installation

kubectl get pods -n openbao-operator-system

Expected output (single-tenant mode):

NAME                                              READY   STATUS    RESTARTS   AGE
openbao-operator-controller-xxxxxxxxxx-xxxxx      1/1     Running   0          1m

Ready

Only the Controller is running. No Provisioner pod should be present.

Environment Variables

Variable Description
WATCH_NAMESPACE Required for manual deployments. Target namespace. Enables caching and event-driven reconciliation. Helm sets this automatically when tenancy.mode=single.

Migration

  1. Backup OpenBaoCluster manifests

    kubectl get openbaocluster -A -o yaml > clusters-backup.yaml

  2. Upgrade Helm release

    helm upgrade openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \
  --namespace openbao-operator-system \
  --set tenancy.mode=single \
  --set tenancy.targetNamespace=openbao

  3. Cleanup OpenBaoTenants

    kubectl delete openbaotenants --all

RBAC Changes

After migration, the Controller operates with direct namespace access instead of per-tenant RBAC.

  1. Upgrade Helm release

    helm upgrade openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \
  --namespace openbao-operator-system \
  --set tenancy.mode=multi

  2. Create OpenBaoTenants

    Onboard namespaces using OpenBaoTenant resources:

    apiVersion: openbao.org/v1alpha1
kind: OpenBaoTenant
metadata:
  name: openbao-tenant
spec:
  namespaces:
    - openbao

  3. Cleanup manual RoleBindings

    kubectl delete rolebinding openbao-operator-controller -n openbao

Next Steps

  • Deploy a Cluster

    Create your OpenBaoCluster in the target namespace.

    Getting Started

  • Configuration

    Configure TLS, storage, and security profiles.

    Configuration