Multi-Tenant Design with Vault Namespaces: Operations and Exam Prep

Namespaces are a Vault Enterprise feature that creates strong logical isolation inside a single cluster, letting you safely run multi-tenant workloads split by team, environment, or customer. Each namespace independently manages its auth methods, secrets engines, policies, entities/groups, and tokens.

In practice, the keys are which isolation mechanism you pick and how consistent your operations are. On exams, the X-Vault-Namespace header, token/policy scope, and replication and snapshot behavior are frequently tested. This article grounds the design axes and operational procedures in stable official specifications.

Vault Namespaces Basics and Choosing the Right Isolation

Namespaces are the logical tenant boundary in Vault Enterprise. Each namespace has its own policy evaluation, token issuance, auth methods, and secrets engines, so identical paths in different namespaces never collide. The API selects a namespace via the X-Vault-Namespace header, and the CLI uses the -namespace flag or the VAULT_NAMESPACE environment variable.

The classic operational and exam trap is whether you are actually operating on the namespace you intended. A missing header or environment variable can mount engines or apply policies in the wrong namespace. Remember that even a root token is scoped to the namespace where it was issued.

• Enterprise feature. Namespaces do not exist in OSS Vault.
• Without X-Vault-Namespace, the current namespace is targeted. For the CLI, explicitly setting VAULT_NAMESPACE is the safe default.
• Tokens are scoped to the namespace where they were issued. They have no authority in other namespaces.

Namespace-based isolation inside a single cluster

Selecting a namespace via API and CLI (create, list)

# 1) root 名前空間で team-a を作成（API）
curl -sS \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "X-Vault-Namespace: root" \
  -X POST $VAULT_ADDR/v1/sys/namespaces/team-a

# 2) 一覧（LISTメソッド）。ヘッダの指定が必須
curl -sS -X LIST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "X-Vault-Namespace: root" \
  $VAULT_ADDR/v1/sys/namespaces | jq .

# 3) CLIはVAULT_NAMESPACEで明示
export VAULT_NAMESPACE=team-a
auth_method=$(vault auth list -detailed -format=json | jq 'keys')

Hierarchy Design and Naming Conventions

Start from who needs to operate what independently. A common pattern places organizations or customers at the first level and environments (dev/stg/prod) at the second. Going deeper than 2-3 levels hurts both operations and visibility.

Adopt a consistent naming scheme (lowercase, hyphens, environment suffixes) and keep names short and collision-free. Park short-lived experiments under something like sandbox and review them on a regular cadence.

• Recommended: org/tenant → env (e.g. team-a/prod)
• Codify the naming convention in a repo and detect deviations in CI
• Run audit jobs to surface empty namespaces and unused mounts

Listing namespaces and checking existence (API)

# root配下の第1階層を列挙
curl -sS -X LIST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "X-Vault-Namespace: root" \
  $VAULT_ADDR/v1/sys/namespaces | jq '.data.keys'

# team-a配下の環境を列挙
curl -sS -X LIST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "X-Vault-Namespace: team-a" \
  $VAULT_ADDR/v1/sys/namespaces | jq '.data.keys'

Policy and Token Boundary Design

ACL policies act on paths within the namespace being evaluated. Tokens are scoped to a namespace too, so a token issued in team-a cannot read team-b secrets. Even root-level privileges cannot reach outside their scope.

In practice, give each tenant a namespace-level admin role (e.g. ns-admin) and delegate policy registration, mounts, and entity management to it. Automate issuance and revocation per tenant so audits stay easy.

• Default policies exist per namespace. Don't accidentally write them under root.
• Revoke tokens from the namespace where they were issued; that is the reliable path.
• Auth mappings for OIDC and similar methods are also per-namespace.

Creating a policy and issuing a token in team-a

# 対象の名前空間を明示
export VAULT_NAMESPACE=team-a

# 最小権限ポリシーを登録
echo '
path "kv/data/app/*" { capabilities = ["read"] }
' > read-app.hcl
vault policy write app-read read-app.hcl

# ポリシーを付与したトークン発行
vault token create -policy=app-read -period=24h -orphan

Separating Auth Methods and Secrets Engines

Each namespace can enable auth methods (userpass, OIDC, Kubernetes, GitHub, etc.) independently. Likewise, mount secrets engines like kv, pki, and database per tenant. Because path collisions are absorbed by the namespace, every tenant can use identical path conventions without interfering with one another.

TTLs, rotations, and role definitions are entirely namespace-local. Always make the target namespace explicit when performing standard operational tasks like creating roles, enabling engines, or tuning them.

• Identical paths do not collide across different namespaces.
• Mount and auth enable/disable can be delegated per tenant.
• Maintain a baseline HCL template to prevent configuration drift.

Enabling auth and secrets engines per namespace

# team-a で GitHub 認証を有効化
export VAULT_NAMESPACE=team-a
vault auth enable github
vault write auth/github/config organization=my-org

# 同名パスで kv-v2 を有効化（team-a と team-b は独立）
vault secrets enable -path=kv -version=2 kv

export VAULT_NAMESPACE=team-b
vault secrets enable -path=kv -version=2 kv

Operations: Replication and Backup

Enterprise DR/Performance replication replicates state including namespaces. Tenant boundaries survive failover, so your cutover plan should spell out which namespaces ride on which endpoints.

When using Integrated Storage (Raft), snapshots cover the whole cluster and include namespaces on both backup and restore. Take them during planned maintenance windows and rehearse restores periodically in non-production environments.

• X-Vault-Namespace must still be specified after a replication switchover.
• Raft snapshots are cluster-wide. Plan workarounds for partial restore at design time.
• After a restore, automate health checks for mounts and policies in every namespace.

Snapshot operations (Integrated Storage)

# 取得（権限: 適切な管理トークン、通常はroot名前空間で実施）
vault operator raft snapshot save /backups/vault_$(date +%Y%m%d%H%M).snap

# 復元（事前にクラスタ停止/隔離した検証環境で）
vault operator raft snapshot restore /backups/vault_YYYYMMDDHHMM.snap

Automation and Quota Enforcement

Codifying namespaces, mounts, and policies with the Terraform Vault provider keeps configuration drift in check as tenant count grows. Pin the operating namespace with the provider's namespace argument and split tenants into separate workspaces for safety.

Enterprise quotas (such as rate limits) can be enforced per namespace. Define limits per tenant based on their SLAs to prevent noisy-neighbor problems.

• Make the scope explicit via provider.vault's namespace argument.
• To stop unintended cross-namespace operations, fail CI when X-Vault-Namespace or VAULT_NAMESPACE is unset.
• Roll out quotas in stages, monitor the metrics, and then raise the limits.

Example: creating a namespace and rate limit with Terraform

# Terraform (vault >= 3.x)
provider "vault" {
  address   = var.vault_addr
  token     = var.vault_token
  namespace = "root"
}

resource "vault_namespace" "team_a" {
  path = "team-a"
}

# team-a 内で kv をマウント（別プロバイダでスコープ）
provider "vault" {
  alias     = "team_a"
  address   = var.vault_addr
  token     = var.vault_token
  namespace = "team-a"
}

resource "vault_mount" "kv" {
  provider = vault.team_a
  path     = "kv"
  type     = "kv-v2"
}

# クォータ（API例）：team-a に毎秒100リクエスト
curl -sS -X POST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "X-Vault-Namespace: root" \
  -H "Content-Type: application/json" \
  $VAULT_ADDR/v1/sys/quotas/rate-limit/team-a-rl \
  -d '{
        "rate": 100,
        "interval": "1s",
        "namespace": "team-a"
      }'

Check Your Understanding

Frequently Asked Questions