secure k8 s

Namespaces

Summary: Namespaces give OpenBao secure multi-tenancy — each namespace is an isolated “mini-OpenBao” with its own mounts, policies, entities, and tokens. Unlike Vault, this lives in the OSS build.

Sources: raw/docs/concepts/namespaces/index.md, raw/blog/2025-05-30-namespaces-announcement.md, raw/blog/2025-02-26-vision-for-namespaces.md.

Last updated: 2026-05-19

What you get inside a namespace

A namespace functions as an isolated OpenBao instance with its own (source: raw/docs/concepts/namespaces/index.md):

  • secrets engines
  • auth methods
  • ACL / EGP / RGP policies
  • password policies
  • identity entities and groups
  • tokens

Why it matters here

In HashiCorp Vault, namespaces are an Enterprise-only feature. OpenBao shipped them in OSS — announced 2025-05-30 (source: raw/blog/2025-05-30-namespaces-announcement.md). This was a deliberate scope choice driven by Alex’s “Vision for Namespaces” (source: raw/blog/2025-02-26-vision-for-namespaces.md), which also frames namespaces as the unit of future horizontal scalability — i.e. per-namespace sharding.

Hierarchy

Namespaces nest. Path A/B/C:

  • A is under the root namespace.
  • B is a child of A.
  • C is a child of B.

Children inherit from parents (policies in child namespaces may reference parent entities/groups; parents can assert policies on children) (source: raw/docs/concepts/namespaces/index.md).

Naming rules

Cannot end with /, cannot contain spaces, and cannot match any of the reserved strings: ., .., root, sys, audit, auth, cubbyhole, identity (source: raw/docs/concepts/namespaces/index.md).

Storage limits documented in raw/docs/internals/limits.md.

API addressing

Two equivalent ways to target a namespace (source: raw/docs/concepts/namespaces/index.md):

  1. Absolute path: ns1/ns2/secret/foo.
  2. Relative path with X-Vault-Namespace: ns1/ns2/ header (yes, the header still says X-Vault- for compatibility).

CLI: bao namespace ... (raw/docs/commands/namespace.md).

Delegation

Operators can hand a namespace to delegate admins who self-manage it, create child namespaces, and assign subordinate admins — bounded by the parent (source: raw/docs/concepts/namespaces/index.md).

Restricted sys/ endpoints

Some sys/ endpoints require a root-namespace token regardless of namespace context (source: raw/docs/concepts/namespaces/index.md).

  • identity — entities/groups have namespace scope but can be referenced across the parent chain
  • policies — policies are namespace-scoped
  • overview — namespaces are a headline differentiator from upstream Vault
  • blog-timeline — namespaces announcement and vision posts