mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-11-01 19:17:58 +00:00
[DOCS] Administrative namespace updates (#23208)
This commit is contained in:
Sarah Chavis
@@ -6,6 +6,8 @@ description: The `/sys/audit` endpoint is used to enable and disable audit devic
|
||||
|
||||
# `/sys/audit`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/audit` endpoint is used to list, enable, and disable audit devices.
|
||||
Audit devices must be enabled before use, and more than one device may be
|
||||
enabled at a time.
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/config/auditing` endpoint is used to configure auditing s
|
||||
|
||||
# `/sys/config/auditing/request-headers`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/config/auditing` endpoint is used to configure auditing settings.
|
||||
|
||||
## Read all audited request headers
|
||||
|
||||
@@ -8,6 +8,8 @@ description: >-
|
||||
|
||||
# `/sys/config/cors`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/config/cors` endpoint is used to configure CORS settings.
|
||||
|
||||
- **`sudo` required** – All CORS endpoints require `sudo` capability in
|
||||
|
||||
@@ -8,6 +8,8 @@ description: The '/sys/config/group-policy-application' endpoint is used to conf
|
||||
|
||||
@include 'alerts/enterprise-and-hcp-plus.mdx'
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `sys/config/group-policy-application` endpoint can be used to configure the
|
||||
mode of policy application for identity groups in Vault. This setting dictates
|
||||
the behavior across all groups in all namespaces in Vault.
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The '/sys/config/reload' endpoint is used to reload specific parts
|
||||
|
||||
# `/sys/config/reload`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `sys/config/reload` endpoint allows reloading specific parts of Vault's configuration.
|
||||
Currently, it only supports reloading license information from files on disk.
|
||||
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The '/sys/config/state' endpoint is used to retrieve the configurat
|
||||
|
||||
# `/sys/config/state`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The endpoints under `sys/config/state` return Vault's configuration state.
|
||||
Currently, it only supports returning a sanitized version of the configuration.
|
||||
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The '/sys/config/ui' endpoint configures the UI.
|
||||
|
||||
# `/sys/config/ui`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/config/ui` endpoint is used to configure UI settings.
|
||||
|
||||
- **`sudo` required** – All UI endpoints require `sudo` capability in
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/decode-token` endpoint is used to decode the encoded toke
|
||||
|
||||
# `/sys/decode-token`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/decode-token` endpoint is used to decode the encoded token which is the result of the [/sys/generate-root](/vault/api-docs/system/generate-root) API.
|
||||
|
||||
## Parameters
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/experiments` endpoint returns information about experimen
|
||||
|
||||
# `/sys/experiments`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/experiments` endpoint returns information about experiments on the Vault node.
|
||||
|
||||
## Read experiments
|
||||
|
||||
@@ -8,6 +8,8 @@ description: |-
|
||||
|
||||
# `/sys/generate-recovery-token`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/generate-recovery-token` endpoint is used to create a new recovery
|
||||
token for Vault.
|
||||
|
||||
|
||||
@@ -8,6 +8,8 @@ description: |-
|
||||
|
||||
# `/sys/generate-root`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/generate-root` endpoint is used to create a new root key for Vault.
|
||||
|
||||
## Read root generation progress
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/health` endpoint is used to check the health status of Va
|
||||
|
||||
# `/sys/health`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/health` endpoint is used to check the health status of Vault.
|
||||
|
||||
## Read health information
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The '/sys/host-info' endpoint is used to retrieve host information
|
||||
|
||||
# `/sys/host-info`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/host-info` endpoint is used retrieve information about the
|
||||
host instance that the Vault server is running on.
|
||||
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/in-flight-req` endpoint is used to get information on in-
|
||||
|
||||
# `/sys/in-flight-req`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/in-flight-req` endpoint is used to get information on in-flight requests.
|
||||
The returned information contains the `start_time`, `client_remote_address`, `request_path`,
|
||||
`request_method`, and `client_id` of the in-flight requests.
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/init` endpoint is used to initialize a new Vault.
|
||||
|
||||
# `/sys/init`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/init` endpoint is used to initialize a new Vault.
|
||||
|
||||
## Read initialization status
|
||||
|
||||
@@ -6,12 +6,12 @@ description: >-
|
||||
---
|
||||
|
||||
# `/sys/internal/inspect/router`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/internal/inspect/router` endpoint is intended for a Vault admin to inspect the internal components of Vault's router.
|
||||
This endpoint can be accessed with a root token or sudo privileges.
|
||||
|
||||
~> **NOTE**: These endpoints are only available in Vault version 1.13+. Backwards compatibility is not guaranteed. These endpoints are subject to change or may disappear without notice.
|
||||
|
||||
|
||||
## Root
|
||||
|
||||
This endpoint returns a list of router entries in the router's root tree.
|
||||
|
||||
@@ -7,9 +7,9 @@ description: >-
|
||||
|
||||
# `/sys/internal/counters`
|
||||
|
||||
The `/sys/internal/counters` endpoints are used to return data about the number of Tokens and Entities in Vault. They return information for the entire cluster.
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
~> **NOTE**: These endpoints are only available in Vault version 1.3+. Backwards compatibility is not guaranteed. These endpoints are subject to change or may disappear without notice.
|
||||
The `/sys/internal/counters` endpoints are used to return data about the number of Tokens and Entities in Vault. They return information for the entire cluster.
|
||||
|
||||
## Entities
|
||||
|
||||
|
||||
@@ -8,6 +8,8 @@ description: |-
|
||||
|
||||
# `/sys/key-status`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/key-status` endpoint is used to query info about the current
|
||||
encryption key of Vault.
|
||||
|
||||
|
||||
@@ -8,6 +8,8 @@ description: The `/sys/quotas/lease-count` endpoint is used to create, edit and
|
||||
|
||||
@include 'alerts/enterprise-and-hcp-plus.mdx'
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/quotas/lease-count` endpoint is used to create, edit and delete lease count quotas.
|
||||
|
||||
## Create or update a lease count quota
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/loggers` endpoint is used modify the verbosity level of l
|
||||
|
||||
# `/sys/loggers`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/loggers` endpoint is used modify the verbosity level of logging.
|
||||
|
||||
!> **NOTE:** Changes made to the log level using this endpoint are not persisted and will be restored
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/managed-keys` endpoint is used to manage the managed keys
|
||||
|
||||
# `/sys/managed-keys`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/managed-keys` endpoint is used to manage the Managed Key configuration within Vault.
|
||||
See the [Managed Keys](/vault/docs/enterprise/managed-keys) section for further details on the Managed Keys system.
|
||||
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/metrics` endpoint is used to get telemetry metrics for Va
|
||||
|
||||
# `/sys/metrics`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/metrics` endpoint is used to get telemetry metrics for Vault.
|
||||
|
||||
## Read telemetry metrics
|
||||
|
||||
@@ -8,6 +8,8 @@ description: >-
|
||||
|
||||
## Configure Duo MFA method
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
This endpoint defines a MFA method of type Duo.
|
||||
|
||||
| Method | Path |
|
||||
|
||||
@@ -8,6 +8,8 @@ description: >-
|
||||
|
||||
## Configure okta MFA method
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
This endpoint defines a MFA method of type Okta.
|
||||
|
||||
| Method | Path |
|
||||
|
||||
@@ -8,6 +8,8 @@ description: >-
|
||||
|
||||
## Configure PingID MFA method
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
This endpoint defines a MFA method of type PingID.
|
||||
|
||||
| Method | Path |
|
||||
|
||||
@@ -8,6 +8,8 @@ description: >-
|
||||
|
||||
## Configure TOTP MFA method
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
This endpoint defines a MFA method of type TOTP.
|
||||
|
||||
| Method | Path |
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/pprof` endpoint is used to query profiling information.
|
||||
|
||||
# `/sys/pprof`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/pprof` endpoint is used to query. The response returned by
|
||||
these endpoints are equivalent to those returned by the `http/pprof`
|
||||
package.
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/quotas/config` endpoint is used to configure rate limit q
|
||||
|
||||
# `/sys/quotas/config`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/quotas/config` endpoint is used to configure rate limit quotas.
|
||||
|
||||
## Create or update the rate limit configuration
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/quotas/rate-limit` endpoint is used to create, edit and d
|
||||
|
||||
# `/sys/quotas/rate-limit`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/quotas/rate-limit` endpoint is used to create, edit and delete rate limit quotas.
|
||||
|
||||
## Create or update a rate limit quota
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/raw` endpoint is used to access the raw underlying store
|
||||
|
||||
# `/sys/raw`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/raw` endpoint is used to access the raw underlying store in Vault.
|
||||
|
||||
This endpoint is off by default. See the
|
||||
|
||||
@@ -8,9 +8,11 @@ description: >-
|
||||
|
||||
# `/sys/rekey-recovery-key`
|
||||
|
||||
~> **Note:** These endpoints are only applicable to seals that support recovery keys.
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/rekey-recovery-key` endpoints are used to rekey the recovery keys for Vault.
|
||||
The `/sys/rekey-recovery-key` endpoints are used to rekey the recovery keys for
|
||||
Vault. Key recovery endpoints are only applicable to seals that support recovery
|
||||
keys.
|
||||
|
||||
## Read rekey progress
|
||||
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/rekey` endpoints are used to rekey the unseal keys for Va
|
||||
|
||||
# `/sys/rekey`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault.
|
||||
|
||||
On seals that support stored keys (e.g. HSM PKCS11), the recovery key share(s)
|
||||
|
||||
@@ -10,6 +10,8 @@ description: >-
|
||||
|
||||
@include 'alerts/enterprise-and-hcp-plus.mdx'
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
## Attempt recovery
|
||||
|
||||
This endpoint attempts recovery if replication is in an adverse state. For
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/rotate/config` endpoint is used to configure automatic ke
|
||||
|
||||
# `/sys/rotate/config`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/rotate` endpoint is used to configure automatic key rotation.
|
||||
|
||||
## Configure automatic key rotation
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/rotate` endpoint is used to rotate the encryption key.
|
||||
|
||||
# `/sys/rotate`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/rotate` endpoint is used to rotate the encryption key.
|
||||
|
||||
## Rotate encryption key
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/seal` endpoint seals the Vault.
|
||||
|
||||
# `/sys/seal`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/seal` endpoint seals the Vault.
|
||||
|
||||
## Seal
|
||||
|
||||
@@ -10,6 +10,8 @@ description: >-
|
||||
|
||||
@include 'alerts/enterprise-and-hcp-plus.mdx'
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/sealwrap/rewrap` endpoint is used to rewrap all seal wrapped entries.
|
||||
This is useful when you want to upgrade seal wrapped entries to use the latest
|
||||
key, for example, after a seal migration or after rotating the remote keyring.
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/step-down` endpoint causes the node to give up active sta
|
||||
|
||||
# `/sys/step-down`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/step-down` endpoint causes the node to give up active status.
|
||||
|
||||
## Step down leader
|
||||
|
||||
@@ -6,6 +6,10 @@ description: |-
|
||||
The '/sys/storage' endpoints are used to manage Vault's storage backends.
|
||||
---
|
||||
|
||||
# `/sys/storage`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
This API sub-section is currently only used to manage [Raft](/vault/api-docs/system/storage/raft) storage backend.
|
||||
|
||||
On Enterprise there are additional endpoints for working with [Raft Automated Snapshots](/vault/api-docs/system/storage/raftautosnapshots).
|
||||
|
||||
@@ -9,6 +9,8 @@ description: |-
|
||||
|
||||
# `/sys/storage/raft`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/storage/raft` endpoints are used to manage Vault's Raft storage
|
||||
backend.
|
||||
|
||||
|
||||
@@ -9,6 +9,8 @@ description: |-
|
||||
|
||||
# `/sys/storage/raft/autopilot`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/storage/raft/autopilot` endpoints are used to manage raft clusters using autopilot
|
||||
with Vault's [Integrated Storage backend](/vault/docs/internals/integrated-storage).
|
||||
Refer to the [Integrated Storage Autopilot](/vault/tutorials/raft/raft-autopilot) tutorial to learn how to manage raft clusters using autopilot.
|
||||
|
||||
@@ -11,6 +11,8 @@ description: |-
|
||||
|
||||
# `/sys/storage/raft/snapshot-auto`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/storage/raft/snapshot-auto` endpoints are used to manage automated
|
||||
snapshots with Vault's Raft storage backend.
|
||||
|
||||
|
||||
@@ -6,6 +6,8 @@ description: The `/sys/unseal` endpoint is used to unseal the Vault.
|
||||
|
||||
# `/sys/unseal`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/unseal` endpoint is used to unseal the Vault.
|
||||
|
||||
## Submit unseal key
|
||||
|
||||
@@ -1,171 +0,0 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# Vault Enterprise namespaces
|
||||
|
||||
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_.
|
||||
|
||||
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.
|
||||
|
||||
'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.
|
||||
|
||||
## Architecture
|
||||
|
||||
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:
|
||||
|
||||
- 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.
|
||||
|
||||
### Administrative namespaces
|
||||
|
||||
The Vault API includes system backend endpoints, which are mounted under the `sys/` path.
|
||||
System endpoints let you interact with the internal features of your Vault instance.
|
||||
For security reasons, some of the system backend endpoints are restricted, and can only be called
|
||||
from the root namespace or using a token in the root namespace with elevated permissions. These endpoints
|
||||
are [documented below](/vault/docs/enterprise/namespaces#root-only-api-paths).
|
||||
|
||||
By default, Vault allows non-root calls to the less sensitive system backend endpoints.
|
||||
However, there may be instances where a Vault operator needs to provide access to a subset
|
||||
of the restricted endpoints, like `sys/audit-hash` and `sys/monitor`, without granting access
|
||||
to the full set of privileged `sys/` paths. An administrative namespace lets Vault operators grant
|
||||
access to a subset of privileged endpoints by setting a parameter in their Vault configuration file.
|
||||
|
||||
## 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/`
|
||||
|
||||
<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`
|
||||
- `sys/monitor`
|
||||
- `sys/audit-hash`
|
||||
|
||||
## Tutorial
|
||||
|
||||
Refer to the following tutorials to learn more about Vault namespaces:
|
||||
|
||||
- [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)
|
||||
|
||||
|
||||
## API
|
||||
|
||||
Vault Enterprise namespace has a full HTTP API. Please see the [/sys/namespaces
|
||||
API](/vault/api-docs/system/namespaces) for more details.
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Configure an administrative namespace
|
||||
description: >-
|
||||
Step-by-step guide for setting up an administrative namespace with Vault
|
||||
Enterprise
|
||||
---
|
||||
|
||||
# Create an administrative namespace <EnterpriseAlert product=vault inline=true />
|
||||
|
||||
Grant access to a predefined subset of privileged system backend endpoints in
|
||||
the Vault API with an administrative namespace.
|
||||
|
||||
<Tip title="HCP Vault has a built-in administrative namespace">
|
||||
|
||||
HCP Vault clusters include an administrative namespace (`admin`) by default.
|
||||
For more information on managing namespaces with HCP Vault, refer to the
|
||||
[HCP Vault namespace considerations](/vault/tutorials/cloud-ops/hcp-vault-namespace-considerations)
|
||||
guide.
|
||||
|
||||
</Tip>
|
||||
|
||||
## Before you start
|
||||
|
||||
- **You must have Vault Enterprise 1.15+ installed and running**.
|
||||
- **You must have access to your Vault configuration file**.
|
||||
- **You must have permission to create and manage namespaces for your Vault instance**.
|
||||
|
||||
## Step 1: Create your namespace
|
||||
|
||||
Use the `namespace create` CLI command to create a new namespace:
|
||||
|
||||
```shell-session
|
||||
$ vault namespace create YOUR_NAMESPACE_NAME
|
||||
```
|
||||
|
||||
For example, to create a namespace called "ns_admin" under the root namespace:
|
||||
|
||||
<CodeBlockConfig hideClipboard>
|
||||
|
||||
```shell-session
|
||||
$ vault namespace create ns_admin
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
## Step 2: Give the namespace admin permission
|
||||
|
||||
To create an administrative namespace, set the `administrative_namespace_path`
|
||||
parameter in your Vault configuration with the absolute path of your new
|
||||
namespace. We recommend setting the namespace path with the other string
|
||||
assignments in your configuration file. For example:
|
||||
|
||||
<CodeBlockConfig highlight="3">
|
||||
|
||||
```hcl
|
||||
ui = true
|
||||
api_addr = "https://127.0.0.1:8200"
|
||||
administrative_namespace_path = "ns_admin/"
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
## Step 3: Verify the new permissions
|
||||
|
||||
To verify permissions for the administrative namespace, compare API responses
|
||||
from a restricted endpoint from your new namespace and another namespace without
|
||||
elevated permissions.
|
||||
|
||||
1. If you do not already have a namespace you can use for testing, create a test
|
||||
namespace called "ns_test" with the `namespace create` CLI command:
|
||||
```shell-session
|
||||
$ vault namespace create ns_test
|
||||
```
|
||||
1. Use the `monitor` CLI command to call the `/sys/monitor` endpoint from your
|
||||
test namespace:
|
||||
```shell-session
|
||||
$ env VAULT_NAMESPACE="ns_test" vault monitor –log-level=debug
|
||||
```
|
||||
You should see an unsupported path error:
|
||||
|
||||
<CodeBlockConfig hideClipboard>
|
||||
|
||||
```shell-session
|
||||
$ env VAULT_NAMESPACE="ns_test" vault monitor –log-level=debug
|
||||
|
||||
Error starting monitor: Error making API request.
|
||||
Namespace: ns_test/
|
||||
URL: GET http://127.0.0.1:8400/v1/sys/monitor?log_format=standard&log_level=debug
|
||||
Code: 404. Errors:
|
||||
* 1 error occurred:
|
||||
* unsupported path
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
1. Now use the `monitor` command to call the `sys/monitor` endpoint from your
|
||||
administrative namespace:
|
||||
```shell-session
|
||||
$ env VAULT_NAMESPACE="ns_admin" vault monitor –log-level=debug
|
||||
```
|
||||
You should see log data from your Vault instance streaming to the terminal:
|
||||
|
||||
<CodeBlockConfig hideClipboard>
|
||||
|
||||
```shell-session
|
||||
$ env VAULT_NAMESPACE="ns_admin" vault monitor –log-level=debug
|
||||
|
||||
2023-08-31T11:54:41.846+0200 [DEBUG] replication.index.perf: saved checkpoint: num_dirty=0
|
||||
2023-08-31T11:54:41.961+0200 [DEBUG] replication.index.local: saved checkpoint: num_dirty=0
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
## Next steps
|
||||
|
||||
- Follow the [Secure multi-tenancy with namespaces](/vault/tutorials/enterprise/namespaces)
|
||||
tutorial to provide additional security and ensure teams can self-manage their
|
||||
own environments.
|
||||
- Read more about [managing namespaces in Vault Enterprise](/vault/docs/enterprise/namespaces).
|
||||
162
website/content/docs/enterprise/namespaces/index.mdx
Normal file
162
website/content/docs/enterprise/namespaces/index.mdx
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# Vault Enterprise namespaces <EnterpriseAlert product=vault inline=true />
|
||||
|
||||
Many organizations implement Vault as a service to provide centralized
|
||||
management of sensitive data and ensure that the different teams in an
|
||||
organization operate within isolated environments known as **tenants**.
|
||||
|
||||
Multi-tenant environments have the following implementation challenges:
|
||||
|
||||
- **Tenant isolation**. Teams within a Visualization as a Service (VaaS)
|
||||
environment require strong isolation for their policies, secrets, and
|
||||
identities. Tenant isolation may also be required due to organizational
|
||||
security and privacy requirements or to address compliance regulations like
|
||||
[GDPR](https://gdpr.eu).
|
||||
- **Long-term management**. Tenants typically have different policies and teams
|
||||
request changes to their tenants at different rates. As a result, managing a
|
||||
multi-tenant environment can become difficult for a single team as the number
|
||||
of tenants within the organization grows.
|
||||
|
||||
Namespaces support secure multi-tenancy (**SMT**) within a single Vault
|
||||
Enterprise instance with tenant isolation and administration delegation so Vault
|
||||
administrators can empower delegates to manage their own tenant environment.
|
||||
|
||||
When you create a namespace, you establish an isolated environment with separate
|
||||
login paths that functions as a mini-Vault instance within your Vault
|
||||
installation. Users can then create and manage their sensitive data within the
|
||||
confines of that namespace, including:
|
||||
|
||||
- secret engines
|
||||
- authentication methods
|
||||
- ACL, EGP, and RGP policies
|
||||
- password policies
|
||||
- entities
|
||||
- identity groups
|
||||
- tokens
|
||||
|
||||
<Tip>
|
||||
|
||||
Namespaces are isolated environments, but Vault administrators can still share
|
||||
and enforce global policies across namespaces with the
|
||||
[group-policy-application](/vault/api-docs/system/config-group-policy-application)
|
||||
endpoint of the Vault API.
|
||||
|
||||
</Tip>
|
||||
|
||||
## Namespace naming restrictions
|
||||
|
||||
Valid Vault namespace names:
|
||||
|
||||
- **CANNOT** end with `/`
|
||||
- **CANNOT** contain spaces
|
||||
- **CANNOT** be one of the following reserved strings:
|
||||
- `root`
|
||||
- `sys`
|
||||
- `audit`
|
||||
- `auth`
|
||||
- `cubbyhole`
|
||||
- `identity`
|
||||
|
||||
Refer to the [Namespace limits section](/vault/docs/internals/limits#namespace-limits)
|
||||
of [Vault limits and maximums](/vault/docs/internals/limits) for storage limits
|
||||
related to managing namespaces.
|
||||
|
||||
<Tip title="Related reading">
|
||||
|
||||
Read the
|
||||
[Vault namespace and mount structuring](/vault/tutorials/enterprise/namespace-structure)
|
||||
tutorial for best practices and recommendations for structuring your namespaces.
|
||||
|
||||
</Tip>
|
||||
|
||||
## Child namespaces
|
||||
|
||||
A **child namespace** is any namespace that exists entirely within the scope of
|
||||
another namespace. The containing namespace is the **parent namespace**. For
|
||||
example, given the namespace path `A/B/C`:
|
||||
|
||||
- `A` is the top-most namespace and exists under the root namespace for the
|
||||
Vault instance.
|
||||
- `B` is a child namespace of `A` and the parent namespace of `C`.
|
||||
- `C` is a child namespace of `B` and the grandchild namespace of `A`.
|
||||
|
||||
Children can inherit elements from their parent namespaces. For example,
|
||||
policies for a child namespace might reference entities or groups from the parent
|
||||
namespace. Parent namespaces can also **assert** policies on identities within
|
||||
a child namespace.
|
||||
|
||||
Vault administrators can configure the desired inheritance behavior with the
|
||||
[group-policy-application](/vault/api-docs/system/config-group-policy-application)
|
||||
endpoint of the Vault API.
|
||||
|
||||
## Delegation and administrative namespaces
|
||||
|
||||
Vault system administrators can assign administration rights to delegate
|
||||
admins to allow teams to self-manage their namespace. In addition to basic
|
||||
management, delegate admins can create child namespaces and assign admin rights
|
||||
to subordinate delegate admins.
|
||||
|
||||
Additionally, administrative namespaces let Vault administrators grant access to
|
||||
a [predefined subset of privileged endpoints](#privileged-endpoints) by setting
|
||||
the relevant namespace parameters in their Vault configuration file.
|
||||
|
||||
## Vault API and namespaces
|
||||
|
||||
Users can perform API operations under a specific namespace by setting the
|
||||
`X-Vault-Namespace` header to the absolute or relative namespace path. Relative
|
||||
namespace paths are assumed to be child namespaces of the calling namespace.
|
||||
You can also provide an absolute namespace path without using the
|
||||
`X-Vault-Namespace` header.
|
||||
|
||||
Vault constructs the fully qualified namespace path based on the calling
|
||||
namespace and the `X-Vault` header to route the request to the
|
||||
appropriate namespace. For example, the following requests all route to the
|
||||
`ns1/ns2/secret/foo` namespace:
|
||||
|
||||
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/`
|
||||
|
||||
<Tip title="Vault Enterprise has a namespaces API">
|
||||
|
||||
Use the [/sys/namespaces](/vault/api-docs/system/namespaces) API or
|
||||
[`namespace`](/vault/docs/commands/namespace) CLI command to manage
|
||||
your namespaces.
|
||||
|
||||
</Tip>
|
||||
|
||||
## Restricted API paths
|
||||
|
||||
The Vault API includes system backend endpoints, which are mounted under the
|
||||
`sys/` path. System endpoints let you interact with the internal features of
|
||||
your Vault instance.
|
||||
|
||||
By default, Vault allows non-root calls to the less-sensitive system backend
|
||||
endpoints. But, for security reasons, Vault restricts access to some of the
|
||||
system backend endpoints to calls from the root namespace or calls that use a
|
||||
token in the root namespace with elevated permissions.
|
||||
|
||||
Rather than granting access to the full set of privileged `sys/` paths, Vault
|
||||
administrators can also grant access to a predefined subset of the restricted
|
||||
endpoints with an administrative namespace.
|
||||
|
||||
@include 'api/restricted-endpoints.mdx'
|
||||
|
||||
## Learn more
|
||||
|
||||
Refer to the following tutorials to learn more about Vault namespaces:
|
||||
|
||||
- [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)
|
||||
46
website/content/partials/api/restricted-endpoints.mdx
Normal file
46
website/content/partials/api/restricted-endpoints.mdx
Normal file
@@ -0,0 +1,46 @@
|
||||
<a id="/#privileged-endpoints" />
|
||||
|
||||
API path | Root | Admin
|
||||
------------------------------------- | -------- | -----
|
||||
`sys/audit` | YES | NO
|
||||
`sys/audit-hash` | YES | YES
|
||||
`sys/config/auditing/*` | YES | NO
|
||||
`sys/config/cors` | YES | NO
|
||||
`sys/config/group-policy-application` | YES | NO
|
||||
`sys/config/reload` | YES | NO
|
||||
`sys/config/state` | YES | NO
|
||||
`sys/config/ui` | YES | NO
|
||||
`sys/decode-token` | YES | NO
|
||||
`sys/experiments` | YES | NO
|
||||
`sys/generate-recovery-token` | YES | NO
|
||||
`sys/generate-root` | YES | NO
|
||||
`sys/health` | YES | NO
|
||||
`sys/host-info` | YES | NO
|
||||
`sys/in-flight-req` | YES | NO
|
||||
`sys/init` | YES | NO
|
||||
`sys/internal/counters/*` | YES | NO
|
||||
`sys/internal/inspect/router/*` | YES | NO
|
||||
`sys/key-status` | YES | NO
|
||||
`sys/loggers` | YES | NO
|
||||
`sys/managed-keys/*` | YES | NO
|
||||
`sys/metrics` | YES | NO
|
||||
`sys/mfa/method/*` | YES | NO
|
||||
`sys/monitor` | YES | YES
|
||||
`sys/pprof` | YES | NO
|
||||
`sys/pprof/*` | YES | NO
|
||||
`sys/quotas/config` | YES | NO
|
||||
`sys/quotas/lease-count` | YES | NO
|
||||
`sys/quotas/rate-limit` | YES | NO
|
||||
`sys/raw` | YES | NO
|
||||
`sys/rekey/*` | YES | NO
|
||||
`sys/rekey-recovery-key` | YES | NO
|
||||
`sys/replication/recover` | YES | NO
|
||||
`sys/replication/reindex` | YES | NO
|
||||
`sys/replication/status` | YES | NO
|
||||
`sys/rotate` | YES | NO
|
||||
`sys/rotate/config` | YES | NO
|
||||
`sys/seal` | YES | NO
|
||||
`sys/sealwrap/rewrap` | YES | NO
|
||||
`sys/step-down` | YES | NO
|
||||
`sys/storage/*` | YES | NO
|
||||
`sys/unseal` | YES | NO
|
||||
@@ -2434,7 +2434,16 @@
|
||||
},
|
||||
{
|
||||
"title": "Namespaces",
|
||||
"path": "enterprise/namespaces"
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "enterprise/namespaces"
|
||||
},
|
||||
{
|
||||
"title": "Create an administrative namespace",
|
||||
"path": "enterprise/namespaces/create-admin-namespace"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Performance Standbys",
|
||||
|
||||
Reference in New Issue
Block a user