Enable multi-tenancy in HCP Vault with namespaces

6min
|
HCP
Vault

When Vault is primarily used as a central location to manage secrets, different teams may need to manage their secrets in a self-serving manner. You can implement a Vault-as-a-Service model, allowing each business unit or team (tenant) to manage their own secrets and policies. Most importantly, tenants work within their Vault scope. vault-namespace-multi-tenant

HCP Vault Dedicated uses the namespace feature. A namespace allows you to create separate groups of secrets, and apply policies to those namespaces to ensure each tenant can only access the secrets they have permission to. When you create a new HCP Vault Dedicated cluster, a Vault cluster with a default namespace of admin is provisioned.

In this tutorial, you will explore the creation of namespaces and learn how to navigate between them.

Note

This step assumes that you created and connected to the HCP Vault Dedicated cluster in the Create a Vault Cluster on HashiCorp Cloud Platform (HCP) step.

Characteristics of Vault namespaces

A Vault namespace enables teams, organizations, or applications a dedicated, isolated environment. Each namespace has its own:

Policies
Auth methods
Secrets engines
Tokens
Identity entities and groups

Note

Vault creates tokens in a namespace or child-namespaces. Identity groups can pull in entities and groups from other namespaces.

Create namespaces

You may define nested namespaces within a parent namespace. These child-namespaces enable further isolated environments under the parent namespace.

In the Vault UI, select Access from the menu.
Select Namespaces and then click the Create namespace action.
Enter education in the Path field.
Click Save.
The education namespace is now a child-namespace of the admin namespace. You can see this relationship represented in the path admin/education/.
Click the admin namespace from the menu.
The namespace selector displays the child-namespaces of the current namespace.
Select the education namespace.
The current namespace changes to the admin/education/.
Navigate to Access > Namespaces and click the Create namespace action.
Enter training in the Path field.
Click Save.
The training namespace is now a child-namespace of the admin/education namespace. You can see this relationship represented in the path admin/education/training.
Use the namespace selector to navigate to the training namespace and then to the admin namespace.

If you did not set the VAULT_ADDR and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

In a terminal, set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this environment variable.
Create a namespace called education.
```
$ vault namespace create education
Key     Value
---     -----
id      FgOVY
path    admin/education/
```
The education namespace is now a child-namespace of the admin namespace. You can see this relationship represented in the path admin/education/.
List all the namespaces.
```
$ vault namespace list

Keys
----
education/
```
The results display the education/ namespace. You can see the partial path displayed because you set the environment variable VAULT_NAMESPACE to admin/. With this environment variable set, the Vault CLI runs all commands in the context of the admin namespace.
Create a namespace called training as a child-namespace of admin/education/.
```
$ vault namespace create -namespace=admin/education training
Key     Value
---     -----
id      47O0M
path    admin/education/training/
```
The training namespace is now a child-namespace of the admin/education namespace. You can see this relationship represented in the path admin/education/training.
List the namespaces in the admin/education/ namespace.
```
$ vault namespace list -namespace=admin/education

Keys
----
training/
```
The results display the training/ namespace. The partial path is displayed because you passed the admin/education namespace to the command with the namespace parameter.

You can use the VAULT_NAMESPACE environment variable or -namespace flag to target a specific namespace. The -namespace or -ns flag overwrites the value set by the VAULT_NAMESPACE environment variable.

Each API request requires the token and Vault address. If you did not set the VAULT_ADDR and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

Create a namespace called education that is a child-namespace of the admin namespace.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: admin" \
    --request POST \
    $VAULT_ADDR/v1/sys/namespaces/education | jq -r ".data"
```
The request provides the admin namespace in the X-Vault-Namespace header. The education namespace is created as a child-namespace of the admin namespace. This relationship is represented as the path admin/education/.
Example output:
```
{
  "id": "yZWDA",
  "path": "admin/education/"
}
```
Create a namespace called training as a child-namespace of admin/education/.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    $VAULT_ADDR/v1/admin/education/sys/namespaces/training  | jq -r ".data"
```
The request provides the admin/education/ namespace through the API endpoint. The training namespace is created as a child-namespace of the admin/education education namespace. This relationship is represented as the path admin/education/training/.
Example output:
```
{
  "id": "iGp3G",
  "path": "admin/education/training/"
}
```

List the namespaces in the admin/ namespace.

Note

This example uses jq to process the JSON output for readability.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request LIST \
    $VAULT_ADDR/v1/admin/sys/namespaces | jq -r ".data"

Example output:

{
  "key_info": {
    "education/": {
      "id": "QdPD5",
      "path": "admin/education/"
    }
  },
  "keys": ["education/"]
}

List the namespaces in the admin/education/ namespace.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: admin/education" \
    --request LIST \
    $VAULT_ADDR/v1/sys/namespaces | jq -r ".data"

Example output:

{
  "key_info": {
    "training/": {
      "id": "Dbi4X",
      "path": "admin/education/training/"
    }
  },
  "keys": ["training/"]
}

You can specify the target namespace using the X-Vault-Namespace header in your HTTP request. Alternatively, you can add the namespace to the API endpoint. For example, /admin/sys/namespaces invokes the /sys/namespaces endpoint under the admin namespace.

Summary

You created and navigated through Vault Enterprise namespaces. To gain a greater understanding of namespaces complete the Secure Multi-Tenancy with Namespaces tutorial.

Access a cluster

Create and store secrets