vault namespace and VAULT_NAMESPACE in CI
Namespaces partition a Vault Enterprise or HCP Vault into isolated tenants; CI selects one with VAULT_NAMESPACE or -namespace.
On Enterprise and HCP Vault, every mount and policy lives inside a namespace. A CI job that omits the namespace queries the root tenant and gets confusing 404s. This is a frequent and easily missed cause of failures.
What it does
A namespace is an isolated Vault environment with its own auth methods, secrets engines, policies, and tokens. You target one by setting VAULT_NAMESPACE or passing -namespace=<path> per command. vault namespace list and vault namespace create manage them (Enterprise/HCP only).
Common usage
export VAULT_NAMESPACE="team-ci"
vault kv get secret/db
# per-command instead of env
vault kv get -namespace=team-ci secret/db
# manage namespaces (Enterprise/HCP)
vault namespace list
vault namespace create team-ciOptions
| Item | What it does |
|---|---|
| VAULT_NAMESPACE | Env var selecting the namespace for all commands |
| -namespace=<path> | Per-command namespace override |
| vault namespace list | List child namespaces |
| vault namespace create <name> | Create a namespace (Enterprise/HCP) |
In CI
Set VAULT_NAMESPACE once in the job environment so every command targets the right tenant; HCP Vault always uses admin as the top namespace, so HCP users typically set VAULT_NAMESPACE=admin (or a child). Namespaces are an Enterprise/HCP feature; on open-source Vault these commands do not apply.
Common errors in CI
"no handler for route 'secret/data/db'" or unexpected 404s on a path that exists usually means the wrong (or missing) namespace; the mount lives in another tenant. "namespaces feature not enabled" means you ran namespace commands against open-source Vault. "permission denied" can mean the token belongs to a different namespace than the one you are targeting.