Manage namespaces

Vault Enterprise and HCP Vault Dedicated clusters let you create namespaces to provide additional levels of isolation to secure Vault resources. This allows Vault administrators to implement a Vault-as-a-Service model where each namespace is dedicated to an individual tenant such as group, organization, or application.

The following Vault resources are tied to its namespace they are created in:

• Policies
• Auth methods
• Secrets engines
• Tokens
• Identity entities and groups

When working with HCP Vault Dedicated, the top-level namespace is called admin. The admin namespace is created during the deployment of your HCP Vault Dedicated cluster and provides a similar experience to Vault Enterprise clusters that utilize nested namespaces.

For HCP Vault Dedicated clusters, the root namespace is reserved for HashiCorp to perform platform operations. Visit HCP Vault Dedicated Constraints and Known Issues page for more information.

Create namespaces

You can create a namespace using namespace command with the create option.

$ vault namespace create namespaceA

Key     Value
---     -----
id      rXVUH
path    admin/namespaceA/

The namespace is created under the admin namespace.

List namespaces

You can list all namespaces using namespace command with the list option.

$ vault namespace list

Keys
----
namespaceA/

Enable plugins in a namespace

When you enable a plugin such as an auth method or secret engine, that plugin will be enabled in the namespace specified by the command flag, or a set environment variable.

Pass the -namespace flag to specify the namespace a plugin will be enabled in. The full path of the namespace must be used.

$ vault auth enable -namespace=admin/namespaceA userpass

Success! Enabled userpass auth method at: userpass/

Write policies for namespaces

All namespaces start with a default policy that provides limited access to a Vault cluster, such as enabling access to tokens cubbyhole.

By default, policies are restricted to the namespace in which they are created. This means if you have two independent namespaces; namespaceA and namespaceB, a policy created in namespaceA can not permit access to namespaceB. You can, however, write a policy in namespaceA that permits access to namespaceB if namespaceB is a child of namespaceA.

Example namespace policy

This policy can be created in any namespace, but only provides access to the namespace it was created in. For example, if you create the following policy in namespaceA it will only permit access to resources also created in namespaceA.

# Admin policy
path "*" {
   capabilities = ["sudo","read","create","update","delete","list","patch"]
}

A policy created in, and for a specific namespace does not require any additional parameters. When you write a policy in a parent namespace (admin) and wish to provide access to a child namespace (namespaceB) you must specify the namespace in the path of the policy.

Example parent/child namespace policy

This policy should be created in the HCP Vault Dedicated clusters admin namespace and provides access to namespaceB.

# Admin policy
path "namespaceB/*" {
   capabilities = ["sudo","read","create","update","delete","list","patch"]
}

For a detailed walk through of working with policies in independent and parent/child namespaces, refer to the HCP Vault Dedicated namespace considerations tutorial.

Tutorial

Refer to the following step-by-step tutorials to learn more:

• Multi-tenancy with namespaces
• HCP Vault Dedicated namespace considerations
• Secrets management across namespaces without hierarchial relationships