Introduce the target namespace before you create the first cluster.

In the default multi-tenant model, the operator does not discover namespaces implicitly. You onboard a namespace with OpenBaoTenant, which gives the control plane the RBAC and tenant guardrails it needs before the first cluster lands there.

Skip this in single-tenant mode

If you intentionally chose Single-Tenant Mode, the controller watches one namespace directly and you do not use OpenBaoTenant for the first cluster path.

OpenBaoTenant introduces a namespace; it does not create one

Create the Kubernetes namespace through your normal platform workflow first, then apply OpenBaoTenant so the operator can install the namespace-scoped guardrails it depends on.

Decision matrix

Choose the onboarding model

Choose the onboarding model.

Model	Who creates OpenBaoTenant	Use it when	Watch for
Self-service	The namespace owner creates the OpenBaoTenant in the same target namespace.	Teams already control their own namespaces and you want the default low-friction onboarding path.	metadata.namespace and spec.targetNamespace must match.
Centrally managed	A platform admin creates the OpenBaoTenant from the operator namespace.	You want a stricter approval path or need custom quota and limit-range values for a namespace.	Use the rendered operator namespace, not a guessed default.

Diagram

What onboarding introduces

OpenBaoTenant is the explicit namespace introduction point. The Provisioner reacts to that request and installs the namespace-scoped RBAC and default guardrails the operator depends on in the multi-tenant model.

Apply the onboarding request

Self-service

Configure

Create OpenBaoTenant in the target namespace

yaml

apiVersion: openbao.org/v1alpha1
kind: OpenBaoTenant
metadata:
name: team-a-onboarding
namespace: team-a-prod
spec:
targetNamespace: team-a-prod

In the self-service path, metadata.namespace and spec.targetNamespace must match. Self-service onboarding uses the default tenant guardrails and does not allow custom quota or limitRange values.

Centrally managed

Configure

Create OpenBaoTenant from the operator namespace

yaml

apiVersion: openbao.org/v1alpha1
kind: OpenBaoTenant
metadata:
name: team-b-authorization
namespace: <rendered-operator-namespace>
spec:
targetNamespace: team-b-prod
# Optional centrally managed guardrails:
# quota:
# limitRange:

Use the rendered operator namespace from your install, not a hard-coded assumption, when platform admins create onboarding requests on behalf of teams.

Apply

Apply the onboarding request

bash

kubectl apply -f tenant-onboarding.yaml

Cross-namespace self-service is blocked

If a namespace owner creates OpenBaoTenant in one namespace and targets a different namespace, the controller rejects it with a security violation instead of silently broadening access.

Verify onboarding before you create the cluster

Inspect

Inspect the OpenBaoTenant status

bash

kubectl get openbaotenant <name> -n <namespace> -o yaml

Look for status.provisioned: true and a healthy Provisioned condition before you move on to the first cluster manifest.

Reference table

Typical onboarding failures

Typical onboarding failures.

Symptom	Most likely cause	Check first
Provisioning is rejected with a security violation	A self-service request targeted a namespace different from metadata.namespace	The requested namespace pair and the onboarding model in use
Provisioning never completes	The Provisioner is missing, unhealthy, or cannot write the tenant guardrails	Operator install health and the Provisioner deployment in the operator namespace
Custom quotas are ignored	The request came from the self-service path, which uses default guardrails only	Whether the OpenBaoTenant was created from the operator namespace

Continue the main path

Create your first clusterApply the first OpenBaoCluster only after the target namespace is provisioned and ready.Review tenancy & governanceUse the concept page when you need the mental model behind OpenBaoTenant rather than just the task steps.Review multi-tenant securityGo deeper on namespace isolation, RBAC, network policy, and guardrail assumptions in the shared-operator model.