Skip to content

Onboard two tenants

In this tutorial you are the platform admin on day 1 of two tenant teams, tenant-a and tenant-b. For each one you create a Kubernetes namespace that the tenant administers and nothing more, an OpenBao namespace with a login inside it, and the connection that keeps the tenant there. Two tenants let you see the boundary between them in the next tutorial.

It takes about five minutes.

Before you begin

Finish Set up the platform. This tutorial uses its OpenBaoServer openbao and its ClusterOpenBaoConnection platform.

1. Create the tenants' Kubernetes namespaces

For each tenant, namespaces.yaml holds:

  • the namespace, with the label openbaoconfig.io/tenant: "true" that the server openbao admits;
  • the ServiceAccount openbao-config, which the tenant's connection will log in as;
  • a RoleBinding that gives the user tenant-a-admin (or tenant-b-admin) the built-in ClusterRole admin in that namespace only.
examples/tutorials/tenant-onboarding/namespaces.yaml
# The Kubernetes side of two tenants. Each tenant namespace carries the label the OpenBaoServer openbao admits, holds
# the ServiceAccount openbao-config that its connection logs in as, and makes the user <tenant>-admin a namespace
# admin through the built-in ClusterRole admin, bound in that namespace only.
apiVersion: v1
kind: Namespace
metadata:
  name: tenant-a
  labels:
    openbaoconfig.io/tenant: "true"
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: openbao-config
  namespace: tenant-a
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: tenant-a-admins
  namespace: tenant-a
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: admin
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: User
    name: tenant-a-admin
---
apiVersion: v1
kind: Namespace
metadata:
  name: tenant-b
  labels:
    openbaoconfig.io/tenant: "true"
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: openbao-config
  namespace: tenant-b
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: tenant-b-admins
  namespace: tenant-b
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: admin
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: User
    name: tenant-b-admin
kubectl apply -f examples/tutorials/tenant-onboarding/namespaces.yaml
Expected output
namespace/tenant-a created
serviceaccount/openbao-config created
rolebinding.rbac.authorization.k8s.io/tenant-a-admins created
namespace/tenant-b created
serviceaccount/openbao-config created
rolebinding.rbac.authorization.k8s.io/tenant-b-admins created

2. Check what a tenant admin may do

The chart aggregates its <release>-tenant-editor role into admin, so a namespace admin may create the operator's resources. Ask the API server, impersonating tenant-a-admin:

kubectl auth can-i create openbaonamespaces.sys.openbaoconfig.io -n tenant-a --as tenant-a-admin
kubectl auth can-i create kubernetesauthroles.auth.openbaoconfig.io -n tenant-a --as tenant-a-admin

Both answers are yes. Now ask for what the tenant must not do: create a connection (which chooses the OpenBao identity), touch tenant-b, use a ClusterOpenBaoConnection, or create a namespace:

kubectl auth can-i create openbaoconnections.core.openbaoconfig.io -n tenant-a --as tenant-a-admin
kubectl auth can-i create policies.sys.openbaoconfig.io -n tenant-b --as tenant-a-admin
kubectl auth can-i create clusteropenbaoconnections.core.openbaoconfig.io --as tenant-a-admin
kubectl auth can-i create namespaces --as tenant-a-admin

Every answer is no. Hardening: RBAC explains the roles.

3. Create the tenants' OpenBao namespaces and logins

Through the platform connection, create for each tenant:

  • the OpenBao namespace tenant-a;
  • a Kubernetes auth method inside it, and its configuration;
  • the policy tenant-admin, which lets the tenant create child namespaces, secrets engines in them and KV data in their secret mounts, and policies and auth roles whose names start with team-; a role can bind only ServiceAccounts of the tenant's own Kubernetes namespace. Everything stays inside the OpenBao namespace tenant-a;
  • the role operator, which lets only the ServiceAccount openbao-config of the Kubernetes namespace tenant-a log in, with that policy.

Both manifests are applied by the command below. Inspect each tenant's namespace and bindings:

examples/tutorials/tenant-onboarding/openbao-tenant-a.yaml
# The OpenBao side of tenant-a, created by the platform: the OpenBao namespace tenant-a, a Kubernetes auth method inside it, and
# the role operator that lets the ServiceAccount openbao-config of the Kubernetes namespace tenant-a log in with the
# policy tenant-admin. The policy keeps the tenant inside its OpenBao namespace: child namespaces and their secrets engines, team-* policies, and team-* roles that bind only ServiceAccounts of its own Kubernetes namespace.
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: OpenBaoNamespace
metadata:
  name: tenant-a
  namespace: platform
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: AuthMount
metadata:
  name: tenant-a-kubernetes
  namespace: platform
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
  namespace: tenant-a
  path: kubernetes
  type: kubernetes
---
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthConfig
metadata:
  name: tenant-a-kubernetes
  namespace: platform
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
  namespace: tenant-a
  mountPath: kubernetes
  kubernetesHost: https://kubernetes.default.svc
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
  name: tenant-a-admin
  namespace: platform
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
  namespace: tenant-a
  name: tenant-admin
  policy: |
    path "sys/namespaces/*" {
      capabilities = ["create", "read", "update", "patch", "delete"]
    }
    path "+/sys/mounts" {
      capabilities = ["read"]
    }
    path "+/sys/mounts/*" {
      capabilities = ["create", "read", "update", "delete"]
    }
    path "+/secret/data/*" {
      capabilities = ["create", "read", "update"]
    }
    path "+/secret/metadata/*" {
      capabilities = ["read", "delete"]
    }
    path "sys/policies/acl/team-*" {
      capabilities = ["create", "read", "update", "delete"]
    }
    path "auth/kubernetes/role/team-*" {
      capabilities = ["create", "read", "update", "delete"]
      allowed_parameters = {
        "bound_service_account_namespaces"         = [["tenant-a"]]
        "bound_service_account_namespace_selector" = [""]
        "*"                                        = []
      }
    }
---
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthRole
metadata:
  name: tenant-a-operator
  namespace: platform
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
  namespace: tenant-a
  mountPath: kubernetes
  name: operator
  boundServiceAccountNames:
    - openbao-config
  boundServiceAccountNamespaces:
    - tenant-a
  audience: openbao
  tokenPolicies:
    - tenant-admin
  tokenTTL: 1h
examples/tutorials/tenant-onboarding/openbao-tenant-b.yaml
# The OpenBao side of tenant-b, created by the platform: the OpenBao namespace tenant-b, a Kubernetes auth method inside it, and
# the role operator that lets the ServiceAccount openbao-config of the Kubernetes namespace tenant-b log in with the
# policy tenant-admin. The policy keeps the tenant inside its OpenBao namespace: child namespaces and their secrets engines, team-* policies, and team-* roles that bind only ServiceAccounts of its own Kubernetes namespace.
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: OpenBaoNamespace
metadata:
  name: tenant-b
  namespace: platform
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: AuthMount
metadata:
  name: tenant-b-kubernetes
  namespace: platform
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
  namespace: tenant-b
  path: kubernetes
  type: kubernetes
---
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthConfig
metadata:
  name: tenant-b-kubernetes
  namespace: platform
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
  namespace: tenant-b
  mountPath: kubernetes
  kubernetesHost: https://kubernetes.default.svc
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
  name: tenant-b-admin
  namespace: platform
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
  namespace: tenant-b
  name: tenant-admin
  policy: |
    path "sys/namespaces/*" {
      capabilities = ["create", "read", "update", "patch", "delete"]
    }
    path "+/sys/mounts" {
      capabilities = ["read"]
    }
    path "+/sys/mounts/*" {
      capabilities = ["create", "read", "update", "delete"]
    }
    path "+/secret/data/*" {
      capabilities = ["create", "read", "update"]
    }
    path "+/secret/metadata/*" {
      capabilities = ["read", "delete"]
    }
    path "sys/policies/acl/team-*" {
      capabilities = ["create", "read", "update", "delete"]
    }
    path "auth/kubernetes/role/team-*" {
      capabilities = ["create", "read", "update", "delete"]
      allowed_parameters = {
        "bound_service_account_namespaces"         = [["tenant-b"]]
        "bound_service_account_namespace_selector" = [""]
        "*"                                        = []
      }
    }
---
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthRole
metadata:
  name: tenant-b-operator
  namespace: platform
spec:
  connectionRef:
    kind: ClusterOpenBaoConnection
    name: platform
  namespace: tenant-b
  mountPath: kubernetes
  name: operator
  boundServiceAccountNames:
    - openbao-config
  boundServiceAccountNamespaces:
    - tenant-b
  audience: openbao
  tokenPolicies:
    - tenant-admin
  tokenTTL: 1h
kubectl apply -f examples/tutorials/tenant-onboarding/openbao-tenant-a.yaml \
  -f examples/tutorials/tenant-onboarding/openbao-tenant-b.yaml
kubectl -n platform wait --for=condition=Ready --timeout=3m \
  openbaonamespace.sys.openbaoconfig.io/tenant-a \
  openbaonamespace.sys.openbaoconfig.io/tenant-b \
  authmount.sys.openbaoconfig.io/tenant-a-kubernetes \
  authmount.sys.openbaoconfig.io/tenant-b-kubernetes \
  kubernetesauthconfig.auth.openbaoconfig.io/tenant-a-kubernetes \
  kubernetesauthconfig.auth.openbaoconfig.io/tenant-b-kubernetes \
  policy.sys.openbaoconfig.io/tenant-a-admin \
  policy.sys.openbaoconfig.io/tenant-b-admin \
  kubernetesauthrole.auth.openbaoconfig.io/tenant-a-operator \
  kubernetesauthrole.auth.openbaoconfig.io/tenant-b-operator

Every resource reports condition met.

4. Connect each tenant to its OpenBao namespace

Each tenant gets an OpenBaoConnection in its own Kubernetes namespace, based in its OpenBao namespace (namespace: tenant-a). You create it because the tenant cannot.

examples/tutorials/tenant-onboarding/connections.yaml
# One connection per tenant, created by the platform because tenants cannot create connections. Each one is based in
# the tenant's OpenBao namespace and logs in there as the tenant's ServiceAccount openbao-config.
apiVersion: core.openbaoconfig.io/v1alpha1
kind: OpenBaoConnection
metadata:
  name: openbao
  namespace: tenant-a
spec:
  serverRef:
    name: openbao
  namespace: tenant-a
  auth:
    kubernetes:
      role: operator
      serviceAccountRef:
        name: openbao-config
      audiences:
        - openbao
---
apiVersion: core.openbaoconfig.io/v1alpha1
kind: OpenBaoConnection
metadata:
  name: openbao
  namespace: tenant-b
spec:
  serverRef:
    name: openbao
  namespace: tenant-b
  auth:
    kubernetes:
      role: operator
      serviceAccountRef:
        name: openbao-config
      audiences:
        - openbao
kubectl apply -f examples/tutorials/tenant-onboarding/connections.yaml
kubectl -n tenant-a wait openbaoconnection/openbao --for=condition=Ready --timeout=2m
kubectl -n tenant-b wait openbaoconnection/openbao --for=condition=Ready --timeout=2m
Expected output
openbaoconnection.core.openbaoconfig.io/openbao created
openbaoconnection.core.openbaoconfig.io/openbao created
openbaoconnection.core.openbaoconfig.io/openbao condition met
openbaoconnection.core.openbaoconfig.io/openbao condition met

Every resource that tenant-a creates through this connection starts in the OpenBao namespace tenant-a, and its own spec.namespace can only go deeper.

5. Check the result in OpenBao

List the namespaces and read the tenant's role:

kubectl -n openbao exec deploy/openbao -- bao namespace list
kubectl -n openbao exec deploy/openbao -- bao read -namespace=tenant-a auth/kubernetes/role/operator

Read the second tenant's role too:

kubectl -n openbao exec deploy/openbao -- bao read -namespace=tenant-b auth/kubernetes/role/operator

You should see platform/, tenant-a/ and tenant-b/. Each role is bound to ServiceAccount openbao-config in its own Kubernetes namespace (tenant-a or tenant-b), with the policy tenant-admin in that OpenBao namespace.

What you built

  • Two tenant namespaces whose admins hold no cluster rights and cannot create connections.
  • Two OpenBao namespaces, each with its own Kubernetes login and a policy that scopes the tenant.
  • One OpenBaoConnection per tenant, based in its OpenBao namespace and admitted by the server's label and audience rules.

Next steps