When OpenBao namespaces are enough to separate teams or customers
OpenBao supports namespaces for multi-tenant isolation within one cluster, so several teams or customers can keep secrets on a single deployment without each running their own. The design question is where that isolation stops. Namespaces give each tenant a separate administrative area, but the cluster underneath stays shared: one storage backend, one set of nodes, one high availability group and one upgrade cycle. Whether that is acceptable depends on what each tenant needs protected from the others and from the platform team. Write those requirements down before you choose a layout.
Teams usually use namespaces when they want delegated administration over their part of the platform, a clear boundary for who can see which secrets, and a way to keep naming and policy from colliding across groups. This fits internal teams that share a platform team, a security function and a compliance regime. Customers are a different case. If a tenant's contract or regulatory obligations require its key material, audit trail or availability to be independent of other tenants, a shared cluster needs a justification that the tenant and its auditor will accept.
Namespaces are usually sufficient when tenants sit inside one trust boundary, such as business units of one company, and the risk you accept is logical separation with a shared failure domain. They are a weaker fit when an outage or upgrade affecting one tenant could harm the others, when tenants need different key custody or encryption rules, or when a tenant's data must stay in a specific location. In those cases, separate clusters, or one cluster per region or risk tier, change the failure domain itself, not only the access model.
Before you commit, check the current OpenBao namespaces documentation and list which settings you expect to be scoped per namespace and which will remain global, such as the storage backend and cluster-level configuration. Confirm how administrators in one namespace are kept out of others, and verify that with a scripted test rather than a reading of the docs alone. Then have your security and compliance leads decide whether shared-cluster isolation meets each tenant's written requirements. Record the decision and the test results, because the same question returns at every major upgrade.
Namespaces, separate clusters or separate mounts: which tenancy model fits
This table compares three ways to separate teams or customers in OpenBao: namespaces in one cluster, separate clusters per tenant or environment, and one shared namespace with path-based conventions. Read each row as a question to answer for your own tenants, and use the takeaway that isolation strength, operational load and audit separation pull in different directions.
| Consideration | Namespaces in one cluster | Separate clusters per tenant or environment | One shared namespace with path conventions |
|---|---|---|---|
| Isolation strength | Logical separation enforced by OpenBao policy and namespace boundaries within one cluster; confirm the exact boundary behavior for your version | Strongest separation, since data, keys, seal and policies do not share a cluster with other tenants | Weakest; separation depends on path policies written correctly and kept correct as paths grow |
| Operational load | One cluster to upgrade, back up and monitor, with namespace design and policy review as the main ongoing work | Highest; each cluster needs its own upgrades, backups, HA, monitoring and unseal or recovery procedures | Lowest infrastructure load, but policy sprawl and path drift add review effort over time |
| Administrative delegation | Namespace administrators can be given scoped rights to manage their own mounts and policies; confirm which administrative capabilities can be delegated | Delegation happens at the infrastructure level, so each cluster needs its own administrators | Delegation relies on shared administrators editing shared policies, which limits safe self-service |
| Audit separation | Audit logs come from the single cluster, so tenant identification depends on request metadata and log processing; confirm what namespace context appears in your audit entries | Clean separation, since each cluster produces its own audit trail that can be routed independently | Weakest; all tenants' activity lands in the same paths and logs with no native tenant boundary |
| Blast radius of a fault | A cluster-level incident affects every namespace in that cluster | An incident is contained to one cluster | A single misconfigured policy can expose data across all tenants using the namespace |
| Typical fit | Internal teams or business units under one governance body that want self-service without many clusters | Regulated customers or production versus non-production where separation must be provable to an assessor | Small teams or early prototypes where tenants trust each other and the cost of separation outweighs the risk |
| What to confirm first | Namespace limits, supported delegation scope and audit context for your OpenBao version in the namespaces documentation | Your recovery and key custody model for each cluster, and who runs each one | Your path naming standard, policy review cadence and how you would detect cross-tenant access |
How OpenBao namespace boundaries shape policies and secrets
A namespace is the boundary that decides which secrets engines, auth methods and policies a team can see and change. Each namespace has its own mounts, so a secrets engine enabled at a path in one namespace is a separate object from an engine at the same path in another. Policies are evaluated in the namespace where the request lands, which means a policy written for one team's paths does not grant access to another team's paths. Before you build, confirm in the OpenBao namespaces documentation for your version which objects are namespace-scoped, such as mounts, auth methods, policies, identity entities and groups, and which remain cluster-wide.
Several components stay shared across all namespaces in one cluster. The storage backend holds every namespace's encrypted data, so capacity, backup and restore decisions apply to all tenants at once. The seal, whether manual unseal keys or an auto-unseal mechanism, protects the whole cluster, and losing access to it affects every namespace. High availability, with its active node and standby nodes, is also cluster-wide. Ask whether audit devices are configured per namespace or once for the cluster, because that determines who can see access records for a given tenant. A heavy workload in one namespace still draws on shared request handling and storage, so load limits and monitoring should be planned at the cluster level.
Naming and hierarchy deserve a deliberate plan because paths, policies and automation will refer to namespace names for years. Decide first whether top-level namespaces represent business units, customers or environments, and keep the hierarchy shallow enough that an operator can reason about it from a single listing. Customer names embedded in paths can expose tenant relationships to anyone who reads logs or policy files, so decide whether readable names or opaque identifiers suit your audit and support needs. Record who owns the root namespace, who can create child namespaces and which team approves changes, since these choices determine how far delegated administration can reach.
Turn these decisions into checks before onboarding real workloads. For each namespace, list its mounts and auth methods and confirm that nothing unexpected is enabled. Create a test token in one namespace and attempt to read a secret path in another, expecting a denial. Review every policy that references administrative paths or parent namespaces, because a broad grant at a higher level can reach child namespaces in ways teams do not expect. Document which roles can create namespaces, mount engines and write policies, and rehearse a restore of one namespace's data if your backup approach supports it. Treat these results as the baseline for your version, not as a permanent guarantee.
Delegated administration inside a namespace: who can manage what
A namespace only isolates tenants if the people working inside it hold the right permissions and no more. Most multi-tenant designs separate three roles: the platform team that creates namespaces, the tenant administrators who run their own auth and secrets, and the application operators who need only narrow access. The cards below describe what each role typically does and which policy decisions keep it bounded.
Platform administrators
Platform administrators create namespaces, set up the root-level auth and policy baseline, and decide what each tenant can delegate further. Because they sit above every namespace, their own tokens and policies are the highest-risk part of the design. Check who holds root-level administrative policies, how those credentials are issued and rotated, and whether this group is kept small and reviewed regularly.
Tenant administrators
Tenant administrators manage the auth methods, policies, mounts and secrets inside their own namespace without touching sibling tenants. Their effective power is set by the policies the platform team grants them, so the key decision is which capabilities on which paths are delegated, and which are kept at the platform level. Confirm in your own environment that a tenant administrator cannot create or widen namespaces beyond their own.
Application operators
Application operators are the workloads and the people who run them, such as a service team rotating a database credential or a pipeline reading one static secret. Their access should be narrow: specific read or write capabilities on specific mounts, with short-lived tokens where the auth method supports them. Review whether operators can list secret paths they do not need, since listing can reveal naming patterns even when values stay hidden.
Auth method ownership
Each namespace may configure its own auth methods, such as AppRole for servers, JWT/OIDC for CI systems, or Kubernetes for cluster workloads. Deciding which tenant may enable, configure or trust an identity source is a boundary decision, because a misconfigured trust relationship can let identities from outside the tenant obtain its tokens. Document the owner of each auth method and the identity provider it trusts.
Policy inheritance and overrides
Policies are the mechanism that limits every role, and their effect depends on where they are written and which namespace the token belongs to. Confirm how policies in parent and child namespaces interact for your OpenBao version before relying on a default. Plan a review step for any policy that grants administrative capabilities, since a single broad grant can undo the separation the roles are meant to create.
Delegation review and audit trail
Delegated administration stays safe only if changes to roles, policies and namespace settings are visible. Plan how grants are requested, approved and recorded, and confirm that audit logging captures administrative actions attributed to a specific identity and namespace. Test one revocation end to end, from removing a tenant administrator to confirming that their tokens no longer work, before relying on the model in production.
Namespaces or separate clusters: the failure domain and audit question
The first decision is whether a team or customer gets a namespace inside a shared OpenBao cluster or its own cluster. Namespaces give you policy and administrative separation, but they do not give you separate failure domains. Every namespace in a cluster shares the same cluster lifecycle, the same nodes, the same HA group and the same storage backend. An upgrade that goes wrong, a storage fault or a seal problem affects every tenant at once. Before you choose, write down how far a single failure may reach and whether each tenant can accept that reach.
Upgrade coupling and HA ownership are where this decision gets operational. The OpenBao migration and upgrade approach replaces the server process across the nodes of a cluster, so a version change is a change for all namespaces together. Ask who owns the Raft or PostgreSQL storage, who schedules maintenance windows and whether one tenant's change freeze blocks another tenant's work. If one tenant needs a different version timeline, a different backup retention period or a different disaster recovery target, a shared cluster will not meet that need, and a separate cluster will add its own HA set, backups and upgrade effort.
Regulatory and contractual obligations should settle the question before any architecture discussion. Some frameworks and customer contracts accept logical separation, while others require separate key custody, separate audit trails, or data residency for each tenant. Namespaces can support logical isolation in many designs, but an auditor will ask whether that separation still holds during a cluster-wide failure or an operator action that touches every namespace. Map each obligation to the clause or control it comes from, then mark which ones need physical or cluster-level separation. Confirm your reading with legal counsel and your assessor, since DeployOpen prepares evidence but independent auditors decide what is sufficient.
The operator model determines who can reach across namespace boundaries. A central platform team that runs one cluster for several business units has different duties from a provider that hosts external customers and must show that its own staff cannot read a tenant's data. In both cases, the people who hold unseal material, control the storage layer and administer cluster-wide paths can affect all namespaces. List every role with access to root-level or system paths, identify who holds unseal and recovery material, and decide whether that access is acceptable to each tenant's obligations.
Setting up namespaces for your first tenants
This sequence turns a tenant design into a working OpenBao cluster where each team or customer has its own namespace, auth methods, administrators and policies, and where isolation is proven by tests rather than assumed. Each step closes with a check that the next step depends on.
Confirm the OpenBao version and namespace behavior
The platform engineer pins the OpenBao version you will run and reads the namespaces documentation for that version. Record which namespace features are documented, how policies and tokens are scoped by namespace, and which behaviors you still need to test. If your team knows Vault namespaces, do not assume every behavior carried over. Confirm each one on your version before any design depends on it. The check is a short written record of the version, the documented behaviors and any open questions, reviewed by the security owner.
Define the tenant model and naming
Decide what one namespace represents: a business unit, an internal team, a customer, or an environment. Set a naming convention that stays readable in audit logs and tickets, and assign an owner to each tenant who can approve access changes. Also record which data classes each tenant may hold, so later policy choices follow from classification rather than habit. The output is a tenant register listing each name, owner, data class and parent group. The check is that the security owner and platform lead sign off on the register before any namespace is created.
Create the namespace hierarchy
The platform engineer creates the parent namespaces for tenant groups and the child namespaces for each tenant listed in the register. Keep the root and first levels small, and avoid storing tenant secrets at the parent level. Use the same naming convention in every branch so the tree is easy to scan. The check is a comparison of the created tree against the register, confirming that every tenant has exactly one namespace in the intended location and that nothing was created at the root that should belong to a tenant.
Configure auth methods per namespace
Inside each tenant namespace, the platform engineer enables only the auth methods that tenant needs. The OpenBao auth methods documentation recommends AppRole for servers and Userpass for developer machines, and lists other options such as JWT/OIDC and Kubernetes that may fit a given tenant. Configure each method with that tenant's identity source, so users and workloads authenticate where their tenant lives. The check is a login test for one identity per tenant, confirming that the returned token is scoped to that namespace and that the same credentials fail against any other namespace.
Delegate administrator roles
The platform team keeps control of the parent namespaces and the cluster. Each tenant administrator receives a role that covers only their own namespace, such as managing that tenant's auth methods, policies and secrets. Keep the number of people holding these roles small and record who holds each one. Confirm that the delegated role cannot create or change anything in the parent namespace or in sibling tenants. The check is a test where a tenant administrator completes an allowed task in their namespace and receives a denial for the same task in the parent or in another tenant.
Load tenant policies
The platform engineer writes least-privilege policies for each tenant namespace, granting only the paths and capabilities that tenant's workloads and users need. Store the policy files in version control so every change has a reviewer, a history and a reason. Load them into the matching namespace and confirm that no policy references paths belonging to another tenant. The check is a peer review of each policy file, plus a dry run for a sample identity in each tenant that lists the paths the policy allows, compared against the approved design.
Verify isolation with negative tests
The security engineer runs negative tests from each tenant's identity, attempting to read secrets in another tenant, list its auth methods, read its policies and reach its administrative endpoints. Every attempt is expected to fail, and the failures are recorded with the namespace, identity and time. Confirm that audit logging captures the attempts in your configured audit devices. Repeat the same test set after every namespace, auth or policy change. The check is a signed test report showing that each expected denial occurred, retained as evidence for internal review or a compliance readiness file.
Security risks of sharing one OpenBao cluster between tenants
Namespaces separate tenants logically, but every namespace still depends on the same policies, administrators, storage, seal material, audit stream and request capacity. The cards below cover where those shared components create risk, the control that reduces each risk, and what the operator should verify before and after go-live.
Policies that cross namespace boundaries
Policies match request paths, and a wildcard or misplaced grant can let one tenant reach another tenant's secrets engines or auth methods. A policy written in a parent namespace may also grant more than the tenant expects. Keep each tenant's policies inside its own namespace, and limit wildcards and cross-namespace grants to named platform roles. Verify by checking the effective capabilities of a token from each tenant against paths owned by the others, and repeat that check after every policy change.
Broad root-level administrator access
Any identity that holds a root token or a policy covering system paths can change mounts, auth methods and policies for every tenant on the cluster. Store root tokens under controlled custody, issue administrative access through named identities with defined expiry, and give tenant administrators only namespace-scoped roles. Verify which identities can reach system endpoints from the root namespace, and confirm that each standing grant has an owner and a review date.
Shared storage and seal material
All namespaces share one storage backend, whether integrated storage (Raft) or PostgreSQL, and one set of unseal or recovery keys. A compromise of either exposes every tenant's data at once. Restrict storage access to cluster nodes, encrypt backups, and decide early how unseal material is split among custodians or whether an external key store will hold it. Verify who holds each key share, and test a restore from backup to confirm that recovery works without a single administrator.
Audit logs that mix tenant activity
Audit entries from every namespace are written to the same cluster-level stream, so an investigation into one tenant means filtering through others' requests. Plan audit devices at the cluster level, keep sensitive values hashed in the log, and forward entries to a SIEM where they can be filtered by namespace. Verify that each entry records its namespace, and that tenant administrators cannot disable or alter audit devices. Device configuration is covered on its own page.
Noisy-neighbor effects on performance
One tenant's heavy secret reads, lease renewals or dynamic credential requests draw on the same request capacity and storage I/O as every other tenant. Size the cluster for combined peak load, and use standby read scaling only where your OpenBao version and storage backend support it. Verify latency per tenant under a realistic load test, and confirm which rate limiting or quota controls your version provides before you commit to any tenant service level.
What namespace design costs and what it asks from your team
How much does OpenBao namespace design and implementation cost?
DeployOpen does not publish a price list, so cost follows from a written scope that reflects your environment. The main components are design work, the build in your OpenBao cluster, and the time your own staff spend in workshops and approvals. Design effort rises with the number of tenants and the number of distinct policy boundaries each one needs. Build effort rises with auth integrations, such as SSO, directory groups and Kubernetes workloads, because each one needs its own mapping to namespaces and policies. Ask for a quote that lists each deliverable, the tenants covered, the auth methods in scope and the handover format, so you can compare it with an internal estimate on the same basis.
What makes namespace design take more or less effort?
The largest drivers are the number of tenants or teams, the number of auth integrations, the compliance evidence you need, and the state of your existing Vault estate. More tenants mean more boundaries to define, more delegated administrators and more policies to test. Each identity source adds mapping and test work. Compliance evidence adds effort because access decisions, audit log routing and review records must be designed so an assessor can examine them. DeployOpen prepares that evidence but does not issue audit reports. An existing estate with well-organized policies can reduce design work, while tangled policies add review and migration effort. Confirm each of these during assessment, before the scope is fixed.
Which namespace costs are one-time and which recur?
Design, the initial build, and the first set of tests and documentation are one-time costs. Recurring costs appear after go-live: onboarding new tenants, changing policies as teams change, reviewing access on a schedule, and applying OpenBao upgrades with their regression checks. Onboarding cost depends on whether each tenant request follows a standard pattern or needs a new design decision. Access reviews recur at the frequency your own control set requires, and someone on your side must own them. Upgrades recur with each release line you adopt. Ask a provider to separate one-time and recurring items in the quote, and ask whether ongoing work runs as fixed-scope changes or under a retainer. DeployOpen offers retainers for ongoing support, upgrades and testing.
Can our own platform team design OpenBao namespaces in-house?
Yes. A team that already runs OpenBao and understands its policy language can design namespaces internally, and many do. The work requires clear tenant boundaries, a policy model, a delegation model for namespace administrators, and a test plan that proves one tenant cannot read another tenant's secrets. Gaps usually show up in the test plan and the evidence rather than in the first design. Check whether your team has administered namespaces before, who will own the policies after handover, and whether anyone has time to maintain them through upgrades. A partner can review your design or build it under a fixed scope. The right choice turns on those answers.
What should a written scope for namespace work include?
A written scope should name the tenants or teams covered, the namespace hierarchy, the auth methods and directory sources in scope, and the secrets engines each tenant will use. It should list delegated administrator roles, the policy set, the audit device configuration and the access review process. It should describe the tests that prove isolation, the documentation and the handover recipients. List exclusions too, such as migration of existing secrets, changes to identity providers, or work on other clusters. Ask for acceptance criteria written as checks your team can run. Tie the schedule to these deliverables and to what your side must provide, such as approvers and environment access.
How long does namespace design and implementation take?
The duration depends on the written scope, and no general timeline applies. The biggest factors are how many tenants and auth integrations are in scope, how quickly your team makes design decisions, and how much existing policy must be reviewed or moved. Access to your environment and change windows for production clusters also set the pace. Ask the provider to show the schedule as phases tied to deliverables, with named dependencies on your side, such as directory group owners and security approvers. A schedule that omits those dependencies is incomplete. Confirm test environment access before the schedule starts, because it sets the pace of the testing phases.
What does namespace design ask from our security and platform teams?
Expect steady time from three groups. Platform engineers provide cluster access, configuration review and change windows. Security or identity owners decide which groups map to which tenant roles and approve the access model. Tenant owners confirm which secrets and engines they need and who may request changes on their side. Record each decision, because namespace boundaries are costly to change later without repeating isolation tests. Expect workshops at design and review points, and a named decision-maker for each boundary. If those people are unavailable, the work waits. Agree on who signs off each deliverable before the scope is signed.
Should we use namespaces or separate clusters to control cost?
Namespaces share one cluster, its storage and its operations, so they usually cost less to run than separate clusters. The actual difference depends on your sizing, availability requirements and the isolation your tenants need. Separate clusters add infrastructure, upgrade and backup work for each cluster, but they separate failure domains and administration more completely. Namespaces provide policy isolation inside one cluster. Where a tenant needs its own failure domain, a separate cluster is the better fit, and the cost comparison should include that tenant's availability and operational requirements from the start.
Limits to confirm for your OpenBao version and environment
Namespace behavior depends on the exact OpenBao release and environment, so confirm each limit below against the documentation for your planned version and in a test cluster. These checks connect because every namespace in one cluster shares the same release, storage backend and failure domain, and each limit changes how many tenants you can safely place there.
Which features does your release include?
Namespace behavior depends on the exact OpenBao release, so confirm the feature set in the documentation for the minor line you plan to run. The latest supplied releases are v2.7.0, released September 23, 2026, and v2.7.1, released October 1, 2026. Check the release notes for each feature your design needs, then reproduce that feature in a test cluster on the same version before you plan around it.
Which auth and secrets engines work?
Namespaces do not automatically give every auth method and secrets engine the same isolation. Confirm that the auth methods you need, such as AppRole for servers, JWT/OIDC, Kubernetes or LDAP, can be mounted and configured inside a namespace, and identify where login MFA and policies apply. Test one workload per tenant end to end, including dynamic database credentials and lease revocation, to confirm nothing reaches across namespace boundaries.
Does tenant count fit guidance?
Namespace count and nesting depth affect performance, operations and how easily administrators reason about policy. Ask OpenBao for documented guidance on tenant counts and maximum nesting depth, and confirm that the guidance applies to your release and storage backend. Load-test your expected tenant count, including token and lease volume, before committing to a layout that must grow over time.
How does your Vault layout migrate?
The migration guide describes replacing the Vault server process in place on all nodes, with configuration, endpoints and URLs unchanged. That guide was tested only against Vault 1.14.1 community edition, so confirm how your current Vault namespace structure, policies and mount paths map onto OpenBao before you settle on a tenant layout. Rehearse the move on a copy of your data and record every path that changes.
Will auditors accept shared-cluster tenancy?
Auditors judge whether tenants are separated in practice, not only in the product design. Ask your auditors whether a shared cluster with namespace isolation meets their expectations for tenant separation, access review and evidence of policy enforcement. DeployOpen prepares systems, controls and evidence for assessments, but independent auditors and certification bodies decide whether the design is acceptable.
What does one storage backend share?
All namespaces in one cluster share the storage backend, the HA lock and the unseal arrangement. Confirm whether integrated storage (Raft) or PostgreSQL fits your tenant count and recovery targets, and document what a backend outage, failed upgrade or restore affects across every tenant. The storage documentation describes PostgreSQL as easier to operate safely than Raft, which may influence the choice.
How DeployOpen scopes and delivers OpenBao namespace designs
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, so OpenBao namespaces run in the cloud accounts, data centers or air-gapped networks you control. Namespace work is agreed in a written, fixed scope before build starts, with the team, tenant model and policy boundaries defined first. Ongoing support is available as a retainer.
How we scope
- The written scope lists which tenants, teams or customers get a namespace in the cluster.
- It records the namespace hierarchy, the policy paths each tenant can reach and who administers each level.
- Scope also covers which auth methods each tenant uses, and which parts of the cluster stay under platform administrators.
How we build
- Build the namespace tree, mounts and policies in a non-production OpenBao cluster first, then promote the same definitions.
- Express tenant policies and delegated administrator roles as reviewable code, so changes pass through version control.
- Test isolation by attempting cross-namespace reads and writes with each tenant's credentials, and record the results.
How we hand over
- Hand over a namespace design document covering the tree, policy paths, delegated roles and onboarding steps.
- Walk platform administrators through creating a tenant namespace, granting access and reviewing its audit trail.
- Confirm with your team which isolation tests and documentation your compliance assessor will need before handover.
How we support
- Ongoing support can run as a retainer covering namespace changes, new tenants and policy reviews.
- Upgrade plans include re-testing namespace policies and delegated roles before each rollout to production.
- Access reviews of tenant namespaces and administrator roles can be included as part of the retainer.
