Install in single-tenant mode · Next

Single-tenant mode runs only the controller and limits its workload permissions to one existing namespace. It does not run the Provisioner or use OpenBaoTenant.

Choose single-tenant mode

Use multi-tenant mode when	Use single-tenant mode when
A platform team operates OpenBao for several namespaces.	One team owns one operator and one target namespace.
Namespace access must pass through `OpenBaoTenant`.	The team does not need the tenant-onboarding workflow.
The controller discovers clusters across the platform and receives workload permissions only in onboarded namespaces.	The controller watches one namespace through `WATCH_NAMESPACE`.

Single-tenant mode reduces the shared-platform machinery. It also gives the dedicated controller direct permissions in the target namespace, so the platform must own that RoleBinding explicitly.

Install with Helm

Use the chart from the same source checkout as the Next behavior you are evaluating:

apply

Install a single-tenant operator

helm upgrade --install openbao-operator \
  charts/openbao-operator \
  --namespace openbao-operator-system \
  --create-namespace \
  --set image.tag=edge \
  --set operatorVersion=edge \
  --set tenancy.mode=single \
  --set tenancy.targetNamespace=openbao

Create the target namespace through the platform’s normal workflow before applying the first OpenBaoCluster. When tenancy.targetNamespace is omitted, the chart watches its release namespace.

Verify that the rendered Deployment contains WATCH_NAMESPACE=openbao, the target RoleBinding is in openbao, and no Provisioner resources exist. Custom release names or fullnameOverride values change the controller identity; keep manually managed JWT roles aligned with the rendered ServiceAccount.

Install with Kustomize

Create the operator and target namespaces through your normal platform workflow.
apply
Create the example namespaces
```
kubectl create namespace openbao-operator-system
   kubectl create namespace openbao
```

Obtain the operator source for the commit you intend to evaluate.

configure

Clone the operator source

git clone https://github.com/dc-tec/openbao-operator.git
   cd openbao-operator
   git checkout <commit>

Set the operator namespace in config/overlays/single-tenant/kustomization.yaml.
The shipped value is openbao-operator-system. Change both the namespace field and the namespace resource when your platform uses another namespace.
Set data.WATCH_NAMESPACE in config/overlays/single-tenant/target_namespace_config.yaml.
The overlay uses this value for both the controller environment and the target RoleBinding namespace. The shipped value is openbao.
Render the overlay before applying it.
inspect
Render the single-tenant install
```
kubectl kustomize config/overlays/single-tenant
```
Confirm that:
- the controller Deployment contains the intended WATCH_NAMESPACE;
- the openbao-operator-single-tenant RoleBinding is in that namespace;
- the RoleBinding subject names the rendered controller ServiceAccount and operator namespace;
- no Provisioner Deployment, ServiceAccount, Service, or binding remains.
Apply the overlay.
apply
Install the single-tenant operator
```
kubectl apply -k config/overlays/single-tenant
```

Verify the controller and namespace scope.

verify

Verify single-tenant mode

kubectl -n openbao-operator-system rollout status \
     deployment/openbao-operator-controller --timeout=2m
   kubectl -n openbao-operator-system get deployment \
     openbao-operator-controller \
     -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="WATCH_NAMESPACE")].value}{"\n"}'
   kubectl -n openbao get rolebinding openbao-operator-single-tenant

The JSONPath command must print the target namespace. No Provisioner Pod must be running.

Customize the Kustomize controller identity

Use config/overlays/single-tenant-custom-identity when you also need a custom namespace or namePrefix. That overlay updates the controller ServiceAccount, target RoleBinding, controller environment, and admission-policy identity variables together.

Render the overlay and verify every identity reference before applying it:

inspect

Render the custom-identity variant

kubectl kustomize config/overlays/single-tenant-custom-identity

Also update any manually managed OpenBao JWT role so its bound_subject matches the rendered ServiceAccount. See operator authentication.

Change tenancy modes carefully

Before moving from multi-tenant to single-tenant, remove every OpenBaoTenant dependency and verify the new direct RoleBinding before removing the Provisioner.
Before moving from single-tenant to multi-tenant, onboard the namespace and verify the tenant handoff before removing the direct single-tenant RoleBinding.
Do not leave both authorization models in place. Stale RoleBindings can preserve authority that the new model did not intend.

After verification, create the cluster in the watched namespace. Skip the onboarding step.