Learn Vault - Vault Namespaces & Multi-Tenancy (Enterprise vs Open Source)

#Introduction

After securing Vault with audit logging, hardening, and backup automation in episode 22 — this episode shifts the viewpoint from how to secure one Vault to how to secure one Vault for many users at once. The topic: Vault Namespaces & Multi-Tenancy, and how Vault Open Source positions against Enterprise.

Let's start from a very real question in the working world: your organization decides to centralize all secret management into one Vault cluster (a good decision — remember episode 1 about secret sprawl). The backend team needs database credentials, the data team needs warehouse credentials, the security team manages PKI, and each has its own policy standards. Now imagine everything living in one shared space: one policy list, one set of auth methods, one path scope. One team's mistake — for example writing an overly permissive policy or deleting another team's path — impacts all teams. The blast radius is an entire organization.

This is where the concept of tenant or namespace comes in. In the real world, you wouldn't let all departments share one server room without partitions. Namespaces are those partitions: total isolation of data, policies, and auth methods between teams in one physical cluster. This episode explains the mechanism, usage examples, and — often misunderstood — which features are available in Vault Open Source and which are Enterprise-exclusive.

#Main Discussion

#Why Multi-Tenancy Becomes a Requirement, Not a Choice

When an organization starts using Vault, it's usually started by one team (e.g. platform). Once it proves useful, other teams flock to request access. Without clear separation, problems arise:

• Unlimited blast radius — a wrong policy in one team could expose another team's secrets.
• Audit unmapped — hard to answer "who in which team accessed what."
• Auth method conflicts — two teams want to use userpass with the same account, or OIDC with different scopes.
• Unclear governance — who's allowed to enable a secrets engine, who's allowed to create a namespace?

Multi-tenancy solves all of this by providing explicit boundaries: every tenant is a separate world with its own policies, auth methods, secrets engines, and rules.

#Namespaces: Total Isolation in One Cluster

A namespace is a hierarchy inside Vault that isolates data, policies, auth methods, and mount points. This isn't just a "neat folder" — it's security-level isolation: a policy written in one namespace doesn't apply in another, and data in one namespace can't be accessed by another unless explicitly connected (an advanced/Enterprise feature).

This concept is easiest to understand with the analogy of apartments in one building. One building (one Vault cluster), but each apartment unit (namespace) has its own key, its own decor, and its own occupants. You can't enter someone else's unit just because you entered the building.

Creating a namespace is very easy:

vault namespace create dev
vault namespace create prod

Key                Value
---                -----
id                 f4a9...
path               dev/

Once created, use the -namespace flag or the VAULT_NAMESPACE environment variable to operate inside that namespace:

vault kv put -namespace=dev secret/data/app DB_HOST=10.0.1.5
vault kv get -namespace=dev secret/data/app

export VAULT_NAMESPACE=dev
vault kv put secret/data/app DB_HOST=10.0.1.5
vault kv get secret/data/app

Note the path pattern: internally, a path in the dev namespace becomes prefixed with dev/. So secret/data/app in the dev namespace is dev/secret/data/app in root terminology. This is what keeps data from colliding between namespaces — and at the same time becomes a source of misconfiguration (we'll cover this in the pitfalls section).

#Namespace, Policy, and Auth Method: A Complete Example

Now let's build a complete scenario: the backend team uses the backend namespace, with the userpass auth method, and a policy that only allows access to its own KV.

First, enable auth and write the policy inside the namespace:

export VAULT_NAMESPACE=backend
 
# Enable userpass specific to the backend namespace
vault auth enable userpass
 
# Create a user
vault write auth/userpass/users/back-dev \
  password="s3cret-banget" \
  policies=backend-app
 
# List policies in this namespace
vault policy list

backend-app
default

The backend-app policy is written inside the backend namespace, so its scope only applies to paths in that namespace:

path "secret/data/backend/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
 
path "secret/metadata/backend/*" {
  capabilities = ["list"]
}
 
path "database/creds/backend-role" {
  capabilities = ["read"]
}

Now, the back-dev user logging in within the backend namespace cannot access paths in other namespaces, because its policy doesn't touch paths outside secret/data/backend/*. Cross-access attempts will be denied:

vault login -method=userpass username=back-dev password=s3cret-banget

# Inside the backend namespace — works
vault kv get secret/data/backend/api-key
 
# Try to access another namespace (explicitly) — denied
VAULT_NAMESPACE=backend vault kv list secret/data/finance/
 
# Try a path outside the policy scope — denied
vault read database/creds/finance-role

Error making API request.
 
URL: GET https://vault.internal:8200/v1/secret/data/finance/api-key
Code: 403. Errors:
 
* 1 error occurred:
	* permission denied

#Nested Namespaces (Hierarchical Namespaces)

Namespaces don't have to be flat — they can be nested. This matters when an organization has a hierarchy: for example the engineering/ namespace as the "building," then engineering/backend, engineering/data, and engineering/security as units inside it.

vault namespace create -namespace=engineering backend
vault namespace create -namespace=engineering data
vault namespace create -namespace=engineering/backend production

Note the use of -namespace in the commands above: to create a namespace inside a namespace, you first "enter" the parent namespace. As a result, the full path becomes engineering/backend/production/secret/data/app. This hierarchy gives governance flexibility — for example, a policy at the engineering/ level can set general rules, while the units inside handle their own details. But one thing is consistent: the deeper the hierarchy, the longer the path prefix, and the greater the chance of typos when writing policies. Keep your namespace map in documentation, not in your head.

#Vault Open Source vs Enterprise: Features You Must Understand

The important part that often confuses people: are Namespaces available in Vault Open Source? The short answer — no. Namespaces is an Enterprise-exclusive feature. Vault Open Source runs in a single "root namespace"; all users share one policy/auth-mount space.

Here's the comparison of main features:

The two Enterprise features most likely to drive an upgrade besides Namespaces:

• Disaster Recovery Replication — replicates all data to a separate cluster in a different region; if the primary cluster is lost, the DR cluster is promoted to active. This is the "enterprise" answer to the DR concerns from episode 20.
• Sentinel — policies that can express contextual conditions, e.g. "only allow reading this secret if the request comes from an internal IP AND during working hours". OSS can only do static path+capabilities policies.

#Licensing Notes: Vault OSS is Free, But…

One thing you must understand before recommending Vault to any organization: its license. Since Vault version 1.15 (released 2023), the "community" version of Vault is no longer OSI-approved open source as before. HashiCorp changed it to the Business Source License (BSL 1.1):

• Vault BSL is free for internal company use — running Vault for your own needs costs nothing.
• The code can be copied, modified, and distributed for non-competitive use.
• The main restriction: providing Vault as a commercial service directly competing with HashiCorp's products (e.g. managing Vault-as-a-service for many customers).
• After the Change Date (±4 years per release), that version automatically switches to MPL 2.0 — meaning the license is designed to "eventually become open source."

The practical implications:

• You can use community Vault in internal production for free, including for enterprise clients — as long as you're not reselling Vault as a competitive service.
• For teams wanting full open source license certainty, there's OpenBao — a community fork of Vault (formerly named OpenBao, derived from Vault 1.14) run under MPL 2.0. Its features are largely equivalent to Vault OSS, though feature development can differ from official Vault.
• Vault Enterprise remains commercially licensed and paid per feature (Namespaces, Replication, Sentinel, etc.), usually via subscription.

#Common Pitfalls

#Conclusion

In this episode 23 we covered the multi-tenancy concept via Namespaces — total isolation of data, policies, auth methods, and secrets engines between teams in one cluster — complete with practical examples of vault namespace create, using VAULT_NAMESPACE, and namespace-aware policies and auth methods. We also compared Vault Open Source vs Enterprise features: Namespaces, DR/Performance Replication, Sentinel, and Performance Standby are Enterprise features, while Vault's core (secrets engines, auth, audit, HA, auto-unseal) is available in Open Source. Finally, we dissected Vault's BSL license along with its practical implications and the OpenBao alternative.

You now have a Vault that's secure, available, well-documented, and — with the right architectural decisions — able to serve many teams. But one question remains: how do you know everything is running healthy? How do you monitor whether a node is sealed without you realizing it, measure request latency, or diagnose why an app suddenly gets permission denied? That's our technical closing material: Observability, Monitoring & Troubleshooting in episode 24. Keep your enthusiasm up!