open-vault/website/content/docs/enterprise/namespaces.mdx

163 lines
5.7 KiB
Plaintext
Raw Normal View History

2018-08-16 00:44:00 +00:00
---
layout: docs
page_title: Namespaces - Vault Enterprise
description: >-
Vault Enterprise has support for Namespaces, a feature to enable Secure
Multi-tenancy (SMT) and self-management.
2018-08-16 00:44:00 +00:00
---
# Vault enterprise namespaces
2018-08-16 00:44:00 +00:00
<Note>
2018-08-16 00:44:00 +00:00
This feature is available in all versions of [Vault
Enterprise](https://www.hashicorp.com/products/vault/).
</Note>
Many organizations implement Vault as a "service", providing centralized
management for teams within an organization while ensuring that those teams
operate within isolated environments known as _tenants_.
2018-08-16 00:44:00 +00:00
There are two common challenges when implementing this architecture in Vault:
- **Tenant isolation**
Frequently teams within a VaaS environment require strong isolation from other
users in their policies, secrets, and identities. Tenant isolation is typically a
result of compliance regulations such as [GDPR](https://gdpr.eu/), though it may
be necessitated by corporate or organizational infosec requirements.
- **Self-management**
As new tenants are added, there is an additional human cost in the management
overhead for teams. Given that tenants will likely have different policies and
request changes at a different rate, managing a multi-tenant environment can
become very difficult for a single team as the number of tenants within that
organization grow.
2018-08-16 00:44:36 +00:00
'Namespaces' is a set of features within Vault Enterprise that allows Vault
environments to support _Secure Multi-tenancy_ (or _SMT_) within a single Vault
infrastructure. Through namespaces, Vault administrators can support tenant isolation
for teams and individuals as well as empower delegated administrators to manage their
own tenant environment.
2018-08-16 00:44:00 +00:00
## Architecture
2018-08-16 00:44:36 +00:00
Namespaces are isolated environments that functionally exist as "Vaults within a Vault."
They have separate login paths and support creating and managing data isolated to their
namespace. This data includes the following:
2018-08-16 00:44:00 +00:00
- Secret Engines
- Auth Methods
- ACL, EGP, and RGP Policies
- Password Policies
- Identities (Entities, Groups)
- Tokens
Rather than rely on Vault system admins, namespaces can be managed by delegated admins who
can be prescribed administration rights for their namespace. These delegated admins can also
create their own child namespaces, thereby prescribing admin rights on a subordinate group
of delegate admins.
Child namespaces can share policies from their parent namespaces. For example, a child namespace
may refer to parent identities (entities and groups) when writing policies that function only
within that child namespace. Similarly, a parent namespace can have policies asserted on child
identities. This behavior can be configured using the [group-policy-application](/vault/api-docs/system/config-group-policy-application) API, and
can be set to allow policies to be applied irrespective of namespace hierarchy, allowing sharing
across any namespace.
## Usage
API operations performed under a namespace can be done by providing the relative
request path along with the namespace path using the `X-Vault-Namespace` header.
Similarly, the namespace header value can be provided in full or partially when
reaching into nested namespaces. When provided partially, the remaining
namespace path must be provided in the request path in order to reach into the
desired nested namespace.
Alternatively, the fully qualified path can be provided without using the
`X-Vault-Namespace` header. In either scenario, Vault will construct the fully
qualified path from these two sources to correctly route the request to the
appropriate namespace.
For example, these three requests are equivalent:
1. Path: `ns1/ns2/secret/foo`
2. Path: `secret/foo`, Header: `X-Vault-Namespace: ns1/ns2/`
3. Path: `ns2/secret/foo`, Header: `X-Vault-Namespace: ns1/`
2018-08-16 00:44:00 +00:00
<Tip>
See the [Commands (CLI) - namespace](/vault/docs/commands/namespace) page to
learn more about the `namespace` command and subcommands to create and manage
namespaces.
</Tip>
## Namespace naming restrictions
Consider the following namespace name restrictions:
- Cannot end with `/`
- Cannot contain spaces
- The `root` is the top-level namespace. You cannot create another namespace
named "root" under the `root` namespace
In addition, the following paths are reserved by Vault so that they cannot be
the namespace name.
- `sys/`
- `audit/`
- `auth/`
- `cubbyhole/`
- `identity/`
<Tip>
Refer to the [Namespace limits section of the Limits and
Maximums](/vault/docs/internals/limits#namespace-limits) documentation for the
limits associated with the Vault's storage backend.
To learn more about the recommended approach to structure your namespaces, read
the [Vault Namespace and Mount Structuring
Guide](/vault/tutorials/enterprise/namespace-structure) tutorial.
</Tip>
## Root-only API paths
There are certain API paths that can only be called from the **root** namespace:
- `sys/init`
- `sys/leader`
- `sys/health`
- `sys/metrics`
- `sys/config/group-policy-application`
- `sys/config/state`
- `sys/host-info`
- `sys/key-status`
- `sys/storage`
- `sys/storage/raft`
- `sys/quotas`
- `sys/plugins`
2018-08-16 00:44:00 +00:00
## Tutorial
2018-08-16 00:44:00 +00:00
Refer to the following tutorials to learn more about Vault namespaces:
2018-08-16 00:44:00 +00:00
- [Secure Multi-Tenancy with Namespaces](/vault/tutorials/enterprise/namespaces)
- [Secrets Management Across Namespaces without Hierarchical
Relationship](/vault/tutorials/enterprise/namespaces-secrets-sharing)
- [Vault Namespace and Mount Structuring
Guide](/vault/tutorials/enterprise/namespace-structure)
- [HCP Vault namespace
considerations](/vault/tutorials/cloud-ops/hcp-vault-namespace-considerations)
2018-08-16 00:44:00 +00:00
## API
2018-08-16 00:44:00 +00:00
Vault Enterprise namespace has a full HTTP API. Please see the [/sys/namespaces
API](/vault/api-docs/system/namespaces) for more details.