Use single-tenant mode when one team owns one namespace.

Single-tenant mode removes the Provisioner and lets the controller watch one target namespace directly. It is a good fit for dedicated team environments, but it is a branch from the default platform path rather than the starting point for every install.

Decision matrix

Stay on multi-tenant unless this is true

Stay on multi-tenant unless this is true.

Question	Multi-tenant default	Choose single-tenant when	Go deeper
Namespace ownership	Platform teams or shared operators manage multiple target namespaces.	One team directly owns one namespace and does not need the OpenBaoTenant onboarding flow.	Tenant onboarding and RBAC
Control-plane shape	Controller plus Provisioner	Controller only is the right operational model for this environment.	Architecture overview
Operational tradeoff	More default platform structure in exchange for clearer shared-operator boundaries.	A simpler dedicated setup matters more than cross-namespace platform workflows.	Deployment decision guide

Diagram

Single-tenant control path

The controller watches one target namespace directly. There is no Provisioner and no tenant onboarding layer in front of the cluster resources.

Install the single-tenant branch

Helm

Apply

Install the operator in single-tenant mode with Helm

bash

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

Replace openbao-operator-system and openbao with the namespaces you actually intend to keep operating. In this mode the target namespace is the controller watch scope, not just an example value.

Reference table

Helm settings to care about

Helm settings to care about.

Setting	What it controls	Default or note
tenancy.mode	Switches the operator to the controller-only path	single for this branch
tenancy.targetNamespace	Sets the watched namespace and target RoleBinding scope	Defaults to the release namespace when unset
fullnameOverride or release name	Changes the rendered controller identity	Recheck JWT auth and RoleBinding subjects after custom naming
admissionPolicies.enabled	Controls ValidatingAdmissionPolicies for the install	Keep enabled unless your platform does not support them

Raw manifests

Apply

Apply the single-tenant overlay

bash

kubectl apply -k config/overlays/single-tenant

Use config/overlays/single-tenant-custom-identity instead when you need both the single-tenant branch and a custom operator identity.

Configure

Set the target namespace before you apply the overlay

yaml

apiVersion: v1
kind: ConfigMap
metadata:
name: single-tenant-settings
annotations:
  config.kubernetes.io/local-config: "true"
data:
WATCH_NAMESPACE: my-openbao

The target namespace must match both the controller WATCH_NAMESPACE value and the generated RoleBinding namespace.

Verify

Render the overlay once before you apply it

bash

kubectl kustomize config/overlays/single-tenant

Confirm that the controller ServiceAccount subject, RoleBinding namespace, and WATCH_NAMESPACE value all point at the same intended target.

What changes in this branch

Single-tenant mode removes the Provisioner, skips OpenBaoTenant, and gives the controller direct namespace-scoped access instead. That is simpler for a dedicated team, but it also means the operator is no longer modeling the default shared-platform boundary for you.

Verify the install before you create a cluster

Inspect

Check that only the controller is running

bash

kubectl get pods -n <operator-namespace>

In single-tenant mode you should see the controller deployment running, but not a Provisioner pod.

Verify

Confirm the watched namespace matches the intended target

bash

kubectl get deploy -n <operator-namespace> openbao-operator-controller \
-o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="WATCH_NAMESPACE")].value}'

This value should match the target namespace you plan to use for the first OpenBaoCluster.

Migration guidance

Decision matrix

When to migrate between tenancy modes

When to migrate between tenancy modes.

Move	Use it when	Main work before or after	Watch for
Multi-tenant to single-tenant	A dedicated team is taking full ownership of one namespace and no longer needs tenant onboarding.	Re-render the operator, remove OpenBaoTenant usage, and verify the direct RoleBinding scope.	Direct namespace permissions replace the previous tenant boundary.
Single-tenant to multi-tenant	You need shared platform ownership or want to return to the default onboarding model.	Re-enable the Provisioner and model namespace access through OpenBaoTenant resources.	Manual single-tenant RoleBindings must not linger after the switch.

Return to the main path

Install the operatorGo back to the install guide once the tenancy branch and rendered namespaces are clear.Create your first clusterMove into the first cluster guide after the controller watch scope and target namespace are verified.Review operator identity and accessDouble-check auth and RoleBinding surfaces when you are also customizing names or namespaces.