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:

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. Diagram showing a logical model of Vault namespaces
starting with the root namespace which is reserved for platform operations, the
admin namespace where all HCP Vault Dedicated configuration begins, and tenant specific
namespaces that can be created

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.

Tip

In environments where there are multiple independent namespaces (e.g. not parent/child namespaces), you can also enable the group_policy_application_mode flag which permits secret sharing across multiple independent namespaces.

For a detailed walk through of enabling cross namespace secret sharing, refer to the Secrets management across namespaces without hierarchial relationships tutorial.

Tutorial

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