HashiCorp Vault — Namespaces

Namespaces provide multi-tenancy in Vault Enterprise, giving each team or application an isolated Vault environment within a shared cluster.

---

Why Namespaces?

Without Namespaces	With Namespaces
One flat path space	Isolated path trees per tenant
Shared policies (naming conflicts)	Per-namespace policies
Shared auth methods	Per-namespace auth methods
Single admin manages all	Delegated admin per namespace
Path-based isolation only	True multi-tenancy

---

Namespace Architecture

root (/)
├── engineering/
│   ├── secret/           (KV for engineering)
│   ├── auth/approle/     (Engineering AppRoles)
│   ├── policies/         (Engineering policies)
│   ├── frontend/
│   │   ├── secret/       (Frontend team's secrets)
│   │   └── auth/         (Frontend auth)
│   └── backend/
│       ├── secret/       (Backend team's secrets)
│       └── auth/         (Backend auth)
├── finance/
│   ├── secret/
│   └── auth/ldap/        (Finance uses LDAP)
└── operations/
    ├── secret/
    └── pki/              (Ops manages certificates)

---

Manage Namespaces

# Create namespaces
vault namespace create engineering
vault namespace create engineering/frontend
vault namespace create engineering/backend
vault namespace create finance
vault namespace create operations

# List namespaces
vault namespace list

# Target a namespace
export VAULT_NAMESPACE=engineering
vault kv put secret/myapp key=value

# Or use the -namespace flag
vault kv put -namespace=engineering secret/myapp key=value

# Or use the header
curl -H "X-Vault-Namespace: engineering" \
    -H "X-Vault-Token: $VAULT_TOKEN" \
    "$VAULT_ADDR/v1/secret/data/myapp"

---

Per-Namespace Configuration

# Switch to engineering namespace
export VAULT_NAMESPACE=engineering

# Enable auth methods (isolated to this namespace)
vault auth enable approle
vault auth enable userpass

# Enable secrets engines
vault secrets enable -path=secret kv-v2
vault secrets enable database

# Create policies (namespace-scoped)
vault policy write dev - <<EOF
path "secret/data/*" {
  capabilities = ["read"]
}
EOF

---

Cross-Namespace Access

Root namespace admins can access child namespaces:

# From root namespace, read a child namespace secret
vault kv get -namespace=engineering secret/myapp

# Create a policy in root that grants cross-namespace access
vault policy write engineering-admin - <<EOF
path "engineering/*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
EOF

---

Delegate Administration

# Create a namespace admin policy
vault policy write -namespace=engineering ns-admin - <<EOF
path "sys/*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
path "auth/*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
path "secret/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
EOF

# Create an admin token for the namespace
vault token create -namespace=engineering \
    -policy=ns-admin -ttl=8h

---

Quick Reference

Command	Description
vault namespace create NAME	Create a namespace
vault namespace list	List child namespaces
vault namespace delete NAME	Delete a namespace
export VAULT_NAMESPACE=NAME	Target a namespace
-namespace=NAME flag	Per-command namespace

Note: Namespaces are a Vault Enterprise feature.

---

Next: Control Groups & MFA