Vault Namespaces allow you to securely isolate secrets and configurations for different teams or applications within a single Vault instance, acting as distinct, secure partitions.
Let’s see Vault Namespaces in action. Imagine a company, "Acme Corp," using Vault for managing secrets. They have two main teams: "frontend" and "backend." Each team needs its own set of secrets, and they absolutely cannot see each other’s.
Here’s a simplified setup in Vault:
# First, enable the namespaces feature
vault auth enable approle
vault write sys/capabilities/create path="auth/approle/*"
vault write sys/capabilities/read path="auth/approle/*"
vault write sys/capabilities/list path="auth/approle/*"
vault write sys/capabilities/delete path="auth/approle/*"
# Create the 'frontend' namespace
vault write sys/namespaces/create name="frontend"
# Create the 'backend' namespace
vault write sys/namespaces/create name="backend"
Now, when a user or application interacts with Vault, they specify which namespace they are operating in. For example, to write a secret for the frontend team:
# Set the namespace for the current session
export VAULT_NAMESPACE="frontend"
# Write a secret within the 'frontend' namespace
vault kv put secret/frontend-app api-key="supersecretfrontendkey123" database-url="frontend-db.acme.local:5432"
# Now, try to access it from the 'backend' namespace (this will fail)
export VAULT_NAMESPACE="backend"
vault kv get secret/frontend-app
# Output: No value found at secret/frontend-app
Similarly, for the backend team:
# Switch to the 'backend' namespace
export VAULT_NAMESPACE="backend"
# Write a secret within the 'backend' namespace
vault kv put secret/backend-service db-password="verysecurebackendpassword!@#" cache-endpoint="cache.acme.local:6379"
# Try to access it from the 'frontend' namespace (this will also fail)
export VAULT_NAMESPACE="frontend"
vault kv get secret/backend-service
# Output: No value found at secret/backend-service
This fundamental isolation is achieved by Vault internally treating each namespace as a distinct logical Vault instance. When you interact with Vault, the VAULT_NAMESPACE environment variable (or the X-Vault-Namespace HTTP header) tells Vault which partition to look in. All paths, policies, and authentication methods are scoped to the current namespace. This means a policy written in the frontend namespace only applies to resources within frontend and doesn’t grant access to anything in backend.
The problem Vault Namespaces solve is the "noisy neighbor" or "blast radius" problem in multi-tenant environments. Without namespaces, if a credential for one team was accidentally exposed, it could potentially compromise secrets for all teams sharing the same Vault instance. Namespaces create strong boundaries, ensuring that a compromise in one namespace is contained within that namespace. This is critical for security and compliance, especially in large organizations or SaaS providers.
Internally, Vault uses a hierarchical storage structure. When namespaces are enabled, Vault prefixes all data associated with a namespace. For example, secrets in the frontend namespace might be stored under a path like sys/namespaces/frontend/kv/secret/frontend-app. This prefixing is what enforces the isolation at the data layer. When you set VAULT_NAMESPACE="frontend", Vault automatically prepends sys/namespaces/frontend/ to your requests before interacting with its storage backend.
One of the most powerful aspects, and a common point of confusion, is that authentication methods and policies are also namespaced. This means you can configure different authentication methods (like AppRole, Kubernetes, or LDAP) and different policies for each namespace independently. For instance, the frontend namespace might use AppRole authentication with a limited set of policies, while the backend namespace could use Kubernetes auth with broader access to backend-specific secrets. You can even have a root-level namespace (often referred to as the "system" namespace) where global configurations or cross-namespace management can occur, but access to this system namespace is typically highly restricted. This allows for fine-grained control over who can access what, and through which means, on a per-tenant or per-application basis.
The next step in mastering Vault’s multi-tenancy capabilities is understanding how to manage cross-namespace access, which often involves using the sys/replication or sys/policies/export functionalities to share specific secrets or policies without breaking isolation.