Understand the shared-operator boundary before you rely on multi-tenancy.

Multi-tenant mode is the default production model because namespace introduction is explicit, the Provisioner and Controller stay separate, tenant access stays scoped, and guardrails are applied before a cluster ever lands in the namespace.

Default production model

Multi-tenant mode is the recommended production operating model for OpenBao Operator. Use Single-Tenant Mode only when one team directly owns one namespace and intentionally bypasses the default tenant-onboarding boundary.

Diagram

Why the control plane is split

Namespace introduction and tenant guardrails stay with the Provisioner. Workload reconciliation stays with the tenant-scoped Controller. That separation prevents one long-running identity from both granting and consuming tenant access.

Decision matrix

The control-plane split is the security model

The control-plane split is the security model.

Surface	Primary owner	Why it stays separate	If you shortcut it
Namespace introduction	Provisioner	The Provisioner can introduce tenant RBAC and guardrails without becoming the steady-state workload reconciler.	You blur the boundary between granting namespace access and consuming it.
Workload reconciliation	Controller	The Controller stays namespace-scoped and only acts where onboarding already introduced access.	A cluster-wide controller increases blast radius for config and Secret-facing mistakes.
Tenant user access	Tenant-scoped roles	Users can manage clusters without automatically gaining Secret read access.	Operators and tenant users start sharing too much of the same trust surface.
Backup and restore execution	Job-specific identities	Day 2 jobs need narrower, time-bounded capabilities than the main controller.	The controller role quietly becomes a universal credential for routine and destructive operations.

Reference table

Default tenant roles

Default tenant roles.

Role	Scope	Use it for	What it does not allow
openbaocluster-admin-role	Cluster	Platform-level administration and exceptional cluster ownership.	It should not be the normal tenant user path.
openbaocluster-editor-role	Namespace	Managing OpenBaoCluster resources in an onboarded tenant namespace.	It does not grant broad Secret read access.
openbaotenant-editor-role	Namespace	Self-service onboarding through OpenBaoTenant in the same namespace.	It does not allow arbitrary cross-namespace onboarding.

Decision matrix

Isolation layers to validate

Isolation layers to validate.

Layer	Default model	Validate this	Go deeper
RBAC	Namespace-scoped operator access introduced by OpenBaoTenant, with editor roles that avoid direct Secret reads.	Check RoleBindings and kubectl auth can-i results for tenant users and operator identities.	RBAC architecture
Network policy	OpenBao workloads default toward restricted ingress, and backup or restore jobs use their own network contract.	Confirm cross-tenant traffic is blocked and backup egress is intentionally scoped.	Network security
Quota and namespace guardrails	Onboarding applies default tenant quotas, limit ranges, and guardrail labels before the first cluster lands.	Inspect the tenant namespace for the expected quota, limit range, and labels after onboarding.	Onboard the target namespace
Backup storage isolation	Each tenant should use object-storage credentials or prefixes that do not overlap with other tenants.	Make sure backup credentials cannot list or read other tenants' snapshot paths.	Backup operations

Validate the shared-operator boundary

Inspect

Inspect tenant guardrails after onboarding

bash

kubectl get openbaotenant <name> -n <namespace> -o yaml
kubectl get rolebinding,resourcequota,limitrange,networkpolicy -n <target-namespace>

This gives you the fast check: the onboarding request is provisioned, the namespace-scoped RBAC exists, and the expected tenant guardrails were actually introduced.

Verify

Check tenant access stays scoped

bash

kubectl auth can-i create openbaoclusters.openbao.org -n <target-namespace> --as <tenant-user>
kubectl auth can-i get secrets -n <target-namespace> --as <tenant-user>

The normal tenant editor path should allow cluster lifecycle work without granting broad Secret reads by default.

Supplemental policy engines are optional

Kyverno or Gatekeeper can still add cluster-wide guardrails, but they are not the primary tenant-isolation mechanism here. The primary controls are the split-controller model, namespace introduction through OpenBaoTenant, built-in RBAC, and admission policy enforcement.

Go deeper

Tenancy & governanceReturn to the higher-level OpenBaoTenant model when you need the control-plane rationale rather than the security checklist.Onboard the target namespaceUse the task page when you are actually creating the first tenant onboarding request.RBAC architectureReview the exact Kubernetes permission boundaries behind the Provisioner and Controller split.Network securityGo deeper on workload and job network policy assumptions in shared clusters.