Onboard the target namespace

In the default multi-tenant model, you onboard a namespace with OpenBaoTenant before creating the first cluster there. This task installs the RBAC and tenant guardrails the operator depends on.

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.

Platform-managed Pod Security labels

By default, tenant onboarding applies Restricted Pod Security labels to the target namespace. On Rancher or other clusters where namespace labels are owned by platform admission, install the chart with tenancy.namespacePodSecurityLabels.mode=external. In that mode the Provisioner still writes tenant RBAC, quotas, limits, and Secret allowlists, but it does not mutate Namespace objects. The platform policy layer must enforce the namespace Pod Security baseline.

GitOps can submit tenant and cluster together

If your GitOps pipeline applies OpenBaoTenant and OpenBaoCluster in the same sync, the cluster controllers pause cleanly until tenant onboarding is finished. The handoff is complete once the Provisioner has written the tenant RoleBinding and OpenBaoTenant reports status.provisioned: true.

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

Inspect

Inspect the OpenBaoTenant status

bash

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

Confirm status.provisioned: true and a healthy Provisioned condition. In multi-tenant mode, that is the signal that the namespace-scoped RBAC handoff is complete and cluster reconciliation can proceed.

Verify

Verify the tenant RBAC handoff exists

bash

kubectl get rolebinding openbao-operator-tenant-rolebinding -n <target-namespace>

This is the concrete handoff marker the controller waits for before it starts mutating OpenBaoCluster resources in that namespace.

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 or clusters keep requeueing without creating workload resources	The Provisioner is missing, unhealthy, or cannot write the tenant guardrails and tenant RoleBinding	Operator install health, the Provisioner deployment, and the tenant RoleBinding in the target namespace
Provisioning reports an admission or Unauthorized error while updating the target namespace	A platform policy layer owns namespace labels while the chart is still in default Pod Security label enforcement mode	Use tenancy.namespacePodSecurityLabels.mode=external when platform policy owns those labels
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.