Best practices for namespaces and mount paths

Namespaces are isolated environments that functionally create "Vaults within a Vault." They have separate login paths, and support creating and managing data isolated to their namespace. This functionality enables you to provide Vault as a service to tenants.

This guide provides recommended approach to structuring Vault namespaces and mount paths, as well as some guidance around how to make decisions for namespaces and paths structuring, given the organizational structure and use cases.

Why is this topic important?

Everything in Vault is path-based. Each path corresponds to an operation or secret in Vault, and the Vault API endpoints map to these paths; therefore, writing policies configures the permitted operations to specific secret paths. For example, to grant access to manage tokens in the root namespace, the policy path is auth/token/*. To manage tokens for the education namespace, the fully-qualified path functionally becomes education/auth/token/*.

The following diagram demonstrates the API paths based on where the auth method and secrets engines are enabled.

You can isolate secrets using namespaces or mounts dedicated to each Vault client. For example, you can create a namespace for each isolated tenant and they are responsible for managing the resources under their namespace. Alternatively, you can mount a dedicated secrets engine at a path dedicated to each team within the organization.

Depending on how you isolate the secrets, it determines who is responsible for managing those secrets, and more importantly, policies related to those secrets.

Deployment considerations

To plan and design the Vault namespaces, auth method paths and secrets engine paths, you need to consider how to best structure Vault's logical objects for your organization.

Chroot namespace

Vault clients (users, applications, etc.) must be aware of which namespace to send requests, and set the target namespace using -namespace flag, X-Vault-Namespace HTTP header, or VAULT_NAMESPACE environment variable. If the target namespace is not properly set, the request will fail. This can be cumbersome.

To simplify, Vault operators can specify additional listener stanza in the configuration file, and defines chroot_namespace to specify an alternate top-level namespace.

Example:

ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"
disable_mlock = true

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_1"
}

listener "tcp" {
  address       = "127.0.0.1:8200"
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
}

listener "tcp" {
   address          = "127.0.0.1:8300"
   chroot_namespace = "usa-hq"
   tls_cert_file = "/path/to/full-chain.pem"
   tls_key_file  = "/path/to/private-key.pem"
   telemetry {
      unauthenticated_metrics_access = true
  }
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}

The chroot_namespace specifies an alternate top-level namespace for the listener, https//127.0.0.1:8300.

Example request:

$ curl --header "X-Vault-Namespace: team_1" \
   --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data '{"type": "kv-v2"}' \
   https://127.0.0.1:8300/v1/sys/mounts/team-secret

The request operates on the usa-hq/team_1 namespace since the top-level namespace is set to usa-hq for the listener address, 127.0.0.1:8300.

The top-level namespace for https://127.0.0.1:8200 is root.

General guidance

The following principles should be used to guide an appropriate namespace or mount path structure.

• Use namespaces sparingly
• Leverage Vault identities
• Understand Vault's mount points
• Granularity of paths
• Standardized onboarding process

Use namespaces sparingly

The primary purpose of namespaces is to delineate administrative boundaries. The main determining factor for encapsulating an organizational unit into its own namespace is the need for that unit to be able to directly manage policies. However, many organizations may find their deployment requirements are more nuanced, especially if they want to enable "self-service" for their consumers of Vault.

When setting up Vault to be self-service, you should first ask what does "self-service" actually mean to your organization.

• Will teams be managing Vault directly?
• Will there be an onboarding process/layer that teams interact with?

When possible, HashiCorp recommends providing the self-service capability by implementing an onboarding layer rather than directly through Vault. The onboarding layer can enforce a standard naming convention, secrets path structure, and templated policies. In this case, the administrative boundary is at the onboarding layer and not at the organizational unit level. As such, this use case should not require a separate namespace for the team.

However, these teams may roll up to a specific platform team or LOB for which the policy structuring, authentication methods, and secrets use cases are common across all teams within that LOB. Here, it makes sense that the higher-level organizational unit has its own namespace.

Additionally, in many cases, most of the desired level of isolation can be enforced via ACL policies.

The entire list of namespaces must fit into a single storage entry in Vault, and each namespace creates at least two secrets engines which also require storage space. Namespace planning should include a review of the maximum number of namespaces allowed by the storage entry size.

Leverage Vault identities

It's also critical to understand identity in order to make use of Vault ACL templates, which can ease policy management.

Vault provides an internal layer of identity management that can be used to map entities to multiple auth methods as well as provide grouping capabilities. This allows for more robust policy assignment options.

The entity aliases, based on specific information available from the auth method, maps to identity entities that you create. You can use the default names and associated metadata that are created for aliases and entities as part of policy templates and deciding on naming conventions for secrets paths/roles. This allows you to avoid having hard-coded policies for use cases that follow a certain pattern broadly.

You can define identity groups to associate entities that should have permissions in common, and reference those groups in policy templates as much as you can entities and aliases. These groups may also be created automatically for you, depending on the auth methods used.

ACL policy template example:

path "kvv1-{{identity.entity.metadata.team_name}}/*" {
   capabilities = [ "create", "read", "update", "delete", "list" ]
}

path "transit/encrypt/{{identity.entity.aliases.auth_approle_b2560218.name}}" {
   capabilities = [ "update" ]
}

Those templated values get resolved dynamically based on the requester's entity token metadata.

At line 1, the {{identity.entity.metadata.team_name}} value retrieves the team_name value set on the entity's metadata. Similarly, the {{identity.entity.aliases.auth_approle_b2560218.name}} value at line 5 returns the Role ID of the requesting client. This enables your policies to be less static.

Understand Vault's mount points

Auth methods and secrets engines can be categorized into two types:

1. Dedicated: Auth methods and secrets engines that can be managed and mapped directly to a specific organizational unit. For example, the team that manages app-1 can utilize their own AppRole and/or KV mounts without the ability to impact other teams' mounts.

2. Shared: An organization level resources such as Kubernetes auth method and the Active Directory (AD) secrets engine that are shared and managed at the company level; therefore, mounted at the company-level namespace.

It's important to understand Vault's sizing restrictions for mounts. All secrets engine and auth method mount points must each fit within a single storage entry. For Consul, the storage limit is 512KB. For Integrated Storage the limit is 1MB.

Each JSON object describing a mount uses ~500 bytes, but in compressed form it's ~75 bytes. Since auth mounts, secrets engine mount points, local-only auth methods, and local-only secrets engine mounts are stored separately the limit applies to each independently.

By default, each namespace is created with a token auth mount (/auth/), an identity mount (/identity/), and system mount (/sys/). This means that each namespace requires three different mounts and then you will add your custom mounts. Multiply that by 1,000s means that your mount tables will grow exponentially.

Granularity of paths

When thinking about Vault's logical structure, you want to find the right balance of granularity between the various mounts needed and the roles defined within the mounts.

Sharing mounts between teams has benefits and risk. It is up to you to find the right balance of granularity between the various mounts needed and the roles defined within the mounts. Below are a couple use cases with their benefits and risks.

You create a single KV mount with a sub-path for every team within the same mount.

• Benefit: reduces potential of hitting mount table limits.
• Risk: the KV mount is accidentally deleted causing all users of that secret engine to be impacted.

You create a unique mount per LOB.

• Benefit: can provide sub-paths for different teams and limit the blast-radius of an errant change to a single mount.
• Risk: unique KV mounts per team becomes inefficient from a mount management perspective.

Standardized onboarding process

When deploying Vault at scale, it is critical to Vault adoption to consider the consumer experience. Specifically, it's important to reduce the level of friction of consuming Vault. While it maybe quick to drop Vault into an environment and interact with it directly, it's important to deliberately map out how consumers will onboard to Vault and consume the service.

One of the pillars behind the Tao of Hashicorp is automation through codification. Many HashiCorp users are using Terraform for managing infrastructure on-prem and in the cloud. Terraform can also be used to codify Vault configuration tasks such as creation of namespaces, policies, and mounts. This allows Vault operators to increase their productivity, move quicker, promote repeatable processes, and reduce human error.

Tutorials

To learn more, review the following tutorials:

• Secure multi-tenancy with namespaces
• Vault recommended patterns
• Vault standard operating procedures