Skip to content

Onboard teams as a tenant

In this tutorial you are the admin of tenant-a, with admin rights in the Kubernetes namespace tenant-a and nothing else. You onboard two of your teams, devteam and payments: each gets a child OpenBao namespace with a generated secret that only its own workloads can read. Then you try to leave your tenant and watch the boundary hold.

It takes about five minutes.

Before you begin

Finish Onboard two tenants. Every command that acts as the tenant admin carries --as tenant-a-admin, so the API server applies that user's rights, not yours. Commands that read OpenBao through kubectl -n openbao exec run with your rights and, unless they set BAO_TOKEN, the dev server's root token, to show you the result.

1. Onboard the team devteam

One file onboards a team, all in the Kubernetes namespace tenant-a and through its connection openbao:

  • the ServiceAccount devteam, which the team's workloads run as;
  • the OpenBao namespace devteam, created under tenant-a;
  • a KV version 2 mount at secret in tenant-a/devteam, and a generated password at app;
  • the policy team-devteam and the Kubernetes auth role team-devteam in tenant-a, which give the ServiceAccount devteam read access to tenant-a/devteam and nothing else.
examples/tutorials/team-onboarding/devteam.yaml
# The team devteam, onboarded by the tenant-a admin through tenant-a's connection: the ServiceAccount its workloads run
# as, the OpenBao namespace tenant-a/devteam with a KV version 2 mount and a generated password, and a policy and
# Kubernetes auth role in tenant-a that give the team's ServiceAccount read access to its own namespace only.
apiVersion: v1
kind: ServiceAccount
metadata:
  name: devteam
  namespace: tenant-a
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: OpenBaoNamespace
metadata:
  name: devteam
  namespace: tenant-a
spec:
  connectionRef:
    name: openbao
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: SecretsMount
metadata:
  name: devteam-secret
  namespace: tenant-a
spec:
  connectionRef:
    name: openbao
  namespace: devteam
  path: secret
  type: kv-v2
  description: Secrets of the team devteam
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: RandomSecret
metadata:
  name: devteam-app
  namespace: tenant-a
spec:
  connectionRef:
    name: openbao
  namespace: devteam
  mountPath: secret
  path: app
  key: password
  generator:
    length: 32
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
  name: team-devteam
  namespace: tenant-a
spec:
  connectionRef:
    name: openbao
  policy: |
    path "devteam/secret/data/*" {
      capabilities = ["read"]
    }
---
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthRole
metadata:
  name: team-devteam
  namespace: tenant-a
spec:
  connectionRef:
    name: openbao
  boundServiceAccountNames:
    - devteam
  boundServiceAccountNamespaces:
    - tenant-a
  audience: openbao
  tokenTTL: 15m
  policyRefs:
    - name: team-devteam
kubectl --as tenant-a-admin apply -f examples/tutorials/team-onboarding/devteam.yaml
Expected output
serviceaccount/devteam created
openbaonamespace.sys.openbaoconfig.io/devteam created
secretsmount.sys.openbaoconfig.io/devteam-secret created
randomsecret.secrets.openbaoconfig.io/devteam-app created
policy.sys.openbaoconfig.io/team-devteam created
kubernetesauthrole.auth.openbaoconfig.io/team-devteam created

2. Onboard the team payments

payments.yaml is the same file with payments:

kubectl --as tenant-a-admin apply -f examples/tutorials/team-onboarding/payments.yaml

Wait until both teams' resources are Ready:

kubectl --as tenant-a-admin -n tenant-a wait --for=condition=Ready --timeout=3m \
  openbaonamespace.sys.openbaoconfig.io/devteam \
  openbaonamespace.sys.openbaoconfig.io/payments \
  secretsmount.sys.openbaoconfig.io/devteam-secret \
  secretsmount.sys.openbaoconfig.io/payments-secret \
  randomsecret.secrets.openbaoconfig.io/devteam-app \
  randomsecret.secrets.openbaoconfig.io/payments-app \
  policy.sys.openbaoconfig.io/team-devteam \
  policy.sys.openbaoconfig.io/team-payments \
  kubernetesauthrole.auth.openbaoconfig.io/team-devteam \
  kubernetesauthrole.auth.openbaoconfig.io/team-payments

Every resource reports condition met.

3. Check the result in OpenBao

List the child namespaces of tenant-a and read the policy of devteam:

kubectl -n openbao exec deploy/openbao -- bao namespace list -namespace=tenant-a
kubectl -n openbao exec deploy/openbao -- bao policy read -namespace=tenant-a team-devteam

You should see devteam/ and payments/, and a policy that grants read on devteam/secret/data/*. The path starts with devteam/ because the policy lives in tenant-a and reaches the child namespace by its name.

4. Log in as a devteam workload

Request a token for the ServiceAccount devteam, log in to the auth method of tenant-a with the role team-devteam, and read the team's password:

DEVTEAM_JWT=$(kubectl -n tenant-a create token devteam --audience openbao)
DEVTEAM_TOKEN=$(kubectl -n openbao exec deploy/openbao -- \
  bao write -namespace=tenant-a -field=token auth/kubernetes/login role=team-devteam jwt="$DEVTEAM_JWT")
kubectl -n openbao exec deploy/openbao -- \
  env BAO_TOKEN="$DEVTEAM_TOKEN" bao kv get -namespace=tenant-a/devteam -mount=secret -field=password app

OpenBao prints a random 32-character password. Now try the password of payments with the same token:

kubectl -n openbao exec deploy/openbao -- \
  env BAO_TOKEN="$DEVTEAM_TOKEN" bao kv get -namespace=tenant-a/payments -mount=secret -field=password app

OpenBao refuses the read with a 403 error, and the command fails: the token's only policy besides default is team-devteam.

5. Try to leave your tenant

First, write a policy in the OpenBao root namespace through the platform's ClusterOpenBaoConnection:

examples/tutorials/team-onboarding/reach-root.yaml
# A tenant-a attempt to write a policy in the OpenBao root namespace through the platform's ClusterOpenBaoConnection.
# The connection admits only the Kubernetes namespace platform, so the resource stays not Ready with reason
# ConnectionDenied and nothing is written.
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
  name: reach-root
  namespace: tenant-a
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
  name: tenant-a-in-root
  policy: |
    path "sys/*" {
      capabilities = ["read"]
    }
kubectl --as tenant-a-admin apply -f examples/tutorials/team-onboarding/reach-root.yaml

Kubernetes accepts the resource, because you may create policies in tenant-a. The operator does not use the connection for it. Read why:

kubectl --as tenant-a-admin -n tenant-a get policy.sys.openbaoconfig.io/reach-root \
  -o jsonpath='{.status.conditions[?(@.type=="Synced")].message}{"\n"}'

The message contains namespace tenant-a is not in allowedNamespaces; the resource stays Ready False with the reason ConnectionDenied, and the root namespace has no policy tenant-a-in-root.

Second, use the connection of tenant-b. A resource can only use a connection of its own Kubernetes namespace, so it must live in tenant-b:

examples/tutorials/team-onboarding/reach-tenant-b.yaml
# A tenant-a attempt to write a policy through tenant-b's connection. The resource must live in the Kubernetes
# namespace tenant-b, where the tenant-a admin has no rights, so the API server refuses it.
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
  name: reach-tenant-b
  namespace: tenant-b
spec:
  connectionRef:
    name: openbao
  name: team-tenant-a
  policy: |
    path "+/secret/data/*" {
      capabilities = ["read"]
    }
kubectl --as tenant-a-admin apply -f examples/tutorials/team-onboarding/reach-tenant-b.yaml

The API server refuses it: tenant-a-admin is forbidden in the namespace tenant-b.

Your own connection cannot leave either: its base is tenant-a, and a resource's spec.namespace can only go deeper. CI also logs in as the identity of that connection and checks that OpenBao refuses its writes in the root and in tenant-b.

What you built

  • Two teams onboarded by a tenant admin without any cluster rights: child OpenBao namespaces, KV mounts, generated secrets, policies and auth roles.
  • Proof that each team's workloads read only their own child namespace.
  • Proof that the tenant cannot write to the root namespace or to another tenant.

Next steps