Namespaces

Namespaces give Vault a tenant model: every namespace has its own mount tables, identity store, policies, and tokens, isolated from siblings and parents. The Community Edition has a single root namespace; nested namespaces are an Enterprise feature, but the OSS code carries the seams. Source: helper/namespace/, vault/namespaces.go, vault/namespaces_oss.go, plus Core.namespaceRouter in vault/router.go.

Purpose

• Multi-tenant a single Vault cluster cleanly: each tenant sees its own world.
• Make policies, identities, mounts, and tokens scoped without forcing operators to run multiple clusters.
• Inherit certain configurations (auth methods, policies) from parent namespaces while keeping data isolated.

In OSS

Vault CE has a single namespace called root. The plumbing is present:

• helper/namespace/ defines the Namespace type and the context plumbing.
• vault/namespaces.go exposes namespace info to other subsystems.
• vault/namespaces_oss.go is the CE stub that always returns root.
• API requests honor the X-Vault-Namespace header, but in CE only "" and "root/" resolve.

This means CLI commands that look like they should fail in OSS (vault namespace list) actually work — they just return the root namespace.

In Enterprise

Enterprise adds nested namespace creation (vault namespace create dev/team-1), per-namespace mount tables, tokens scoped to a namespace tree, and replication-aware namespace inheritance. The OSS files retain the shape so that Enterprise can drop in the real implementation.

How requests are namespaced

graph LR
    Req[HTTP request] --> H[http/handler.go]
    H -->|X-Vault-Namespace header<br/>or path prefix| NS[helper/namespace/Context]
    NS --> Core[Core.HandleRequest]
    Core --> NSRouter[Per-namespace mount lookup]
    NSRouter --> Backend[Backend.HandleRequest]

Everything the backend touches — storage view, identity store handle, policy evaluation — comes through a namespace-scoped abstraction. A backend mounted in namespace team-a/ can't see data in namespace team-b/.

CLI surface

• vault namespace list — list direct children of the current namespace.
• vault namespace lookup <path> — fetch info about a namespace.
• vault namespace create <path> — create a child (Enterprise).
• vault namespace patch <path> — update metadata (Enterprise).
• vault namespace delete <path> — remove (Enterprise).
• vault namespace lock <path> / unlock <path> — temporarily disable an API (Enterprise).
• -namespace=<path> global flag — execute a command against a specific namespace.

Everything is implemented in command/namespace*.go.

Identity in namespaces

Each namespace has its own identity store: entities, aliases, and groups created in one namespace are not visible in others by default. Inheritance is controlled by group.member_group_ids references that can cross namespaces (Enterprise feature).

The OIDC provider (Enterprise + CE) is namespace-scoped: every namespace can host its own OIDC issuer at <ns>/identity/oidc/....

Policy inheritance

Policies live in a namespace and apply only to tokens in that namespace. Tokens carry their origin namespace and operate within it. Enterprise adds explicit policy inheritance from parents.

Integration points

• helper/namespace/ is imported nearly everywhere — when a function needs to resolve "what namespace am I in", it pulls from context.Context.
• Core.HandleRequest injects namespace context early in the pipeline.
• Audit events record the namespace path so logs are always attributable.
• Replication groups namespaces by performance/DR scope.
• The UI displays the active namespace prominently and supports tree-style switching.

Entry points for modification

• Adding namespace-aware behavior: read the namespace from context.Context via namespace.FromContext(ctx).
• New API endpoint: scope it correctly by reading req.Namespace and routing accordingly.
• New stub for Enterprise: mirror an existing *_oss.go pattern. Remember Enterprise adds the corresponding *_ent.go.