From 1996c186dfd8aa583c7d7e5c72daf264e6771946 Mon Sep 17 00:00:00 2001 From: Sarah Chavis <62406755+schavis@users.noreply.github.com> Date: Thu, 21 Sep 2023 12:07:25 -0700 Subject: [PATCH] [DOCS] Administrative namespace updates (#23208) --- website/content/api-docs/system/audit.mdx | 2 + .../api-docs/system/config-auditing.mdx | 2 + .../content/api-docs/system/config-cors.mdx | 2 + .../config-group-policy-application.mdx | 2 + .../content/api-docs/system/config-reload.mdx | 2 + .../content/api-docs/system/config-state.mdx | 2 + website/content/api-docs/system/config-ui.mdx | 2 + .../content/api-docs/system/decode-token.mdx | 2 + .../content/api-docs/system/experiments.mdx | 2 + .../system/generate-recovery-token.mdx | 2 + .../content/api-docs/system/generate-root.mdx | 2 + website/content/api-docs/system/health.mdx | 2 + website/content/api-docs/system/host-info.mdx | 2 + .../content/api-docs/system/in-flight-req.mdx | 2 + website/content/api-docs/system/init.mdx | 2 + .../api-docs/system/inspect/router.mdx | 6 +- .../api-docs/system/internal-counters.mdx | 4 +- .../content/api-docs/system/key-status.mdx | 2 + .../api-docs/system/lease-count-quotas.mdx | 2 + website/content/api-docs/system/loggers.mdx | 2 + .../content/api-docs/system/managed-keys.mdx | 2 + website/content/api-docs/system/metrics.mdx | 2 + website/content/api-docs/system/mfa/duo.mdx | 2 + website/content/api-docs/system/mfa/okta.mdx | 2 + .../content/api-docs/system/mfa/pingid.mdx | 2 + website/content/api-docs/system/mfa/totp.mdx | 2 + website/content/api-docs/system/pprof.mdx | 2 + .../content/api-docs/system/quotas-config.mdx | 2 + .../api-docs/system/rate-limit-quotas.mdx | 2 + website/content/api-docs/system/raw.mdx | 2 + .../api-docs/system/rekey-recovery-key.mdx | 6 +- website/content/api-docs/system/rekey.mdx | 2 + .../api-docs/system/replication/index.mdx | 2 + .../content/api-docs/system/rotate-config.mdx | 2 + website/content/api-docs/system/rotate.mdx | 2 + website/content/api-docs/system/seal.mdx | 2 + .../api-docs/system/sealwrap-rewrap.mdx | 2 + website/content/api-docs/system/step-down.mdx | 2 + .../content/api-docs/system/storage/index.mdx | 4 + .../content/api-docs/system/storage/raft.mdx | 2 + .../api-docs/system/storage/raftautopilot.mdx | 2 + .../system/storage/raftautosnapshots.mdx | 2 + website/content/api-docs/system/unseal.mdx | 2 + .../content/docs/enterprise/namespaces.mdx | 171 ------------------ .../namespaces/create-admin-namespace.mdx | 120 ++++++++++++ .../docs/enterprise/namespaces/index.mdx | 162 +++++++++++++++++ .../partials/api/restricted-endpoints.mdx | 46 +++++ website/data/docs-nav-data.json | 11 +- 48 files changed, 429 insertions(+), 179 deletions(-) delete mode 100644 website/content/docs/enterprise/namespaces.mdx create mode 100644 website/content/docs/enterprise/namespaces/create-admin-namespace.mdx create mode 100644 website/content/docs/enterprise/namespaces/index.mdx create mode 100644 website/content/partials/api/restricted-endpoints.mdx diff --git a/website/content/api-docs/system/audit.mdx b/website/content/api-docs/system/audit.mdx index 7819abdd1b..53bac2af1a 100644 --- a/website/content/api-docs/system/audit.mdx +++ b/website/content/api-docs/system/audit.mdx @@ -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. diff --git a/website/content/api-docs/system/config-auditing.mdx b/website/content/api-docs/system/config-auditing.mdx index a69bff4bae..a06bac7ba1 100644 --- a/website/content/api-docs/system/config-auditing.mdx +++ b/website/content/api-docs/system/config-auditing.mdx @@ -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 diff --git a/website/content/api-docs/system/config-cors.mdx b/website/content/api-docs/system/config-cors.mdx index 3f445ae436..a6f03ae5b2 100644 --- a/website/content/api-docs/system/config-cors.mdx +++ b/website/content/api-docs/system/config-cors.mdx @@ -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 diff --git a/website/content/api-docs/system/config-group-policy-application.mdx b/website/content/api-docs/system/config-group-policy-application.mdx index 6946657b52..8ab35fc87e 100644 --- a/website/content/api-docs/system/config-group-policy-application.mdx +++ b/website/content/api-docs/system/config-group-policy-application.mdx @@ -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. diff --git a/website/content/api-docs/system/config-reload.mdx b/website/content/api-docs/system/config-reload.mdx index 3d82d4589f..73d6d948c8 100644 --- a/website/content/api-docs/system/config-reload.mdx +++ b/website/content/api-docs/system/config-reload.mdx @@ -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. diff --git a/website/content/api-docs/system/config-state.mdx b/website/content/api-docs/system/config-state.mdx index 9573633ce0..05a2f2ed7c 100644 --- a/website/content/api-docs/system/config-state.mdx +++ b/website/content/api-docs/system/config-state.mdx @@ -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. diff --git a/website/content/api-docs/system/config-ui.mdx b/website/content/api-docs/system/config-ui.mdx index 9f655443ad..99a31f7e2f 100644 --- a/website/content/api-docs/system/config-ui.mdx +++ b/website/content/api-docs/system/config-ui.mdx @@ -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 diff --git a/website/content/api-docs/system/decode-token.mdx b/website/content/api-docs/system/decode-token.mdx index ae0e3cb71a..1ab6044785 100644 --- a/website/content/api-docs/system/decode-token.mdx +++ b/website/content/api-docs/system/decode-token.mdx @@ -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 diff --git a/website/content/api-docs/system/experiments.mdx b/website/content/api-docs/system/experiments.mdx index 2b2f153f60..5483645e45 100644 --- a/website/content/api-docs/system/experiments.mdx +++ b/website/content/api-docs/system/experiments.mdx @@ -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 diff --git a/website/content/api-docs/system/generate-recovery-token.mdx b/website/content/api-docs/system/generate-recovery-token.mdx index c7d86d8224..c775a9854d 100644 --- a/website/content/api-docs/system/generate-recovery-token.mdx +++ b/website/content/api-docs/system/generate-recovery-token.mdx @@ -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. diff --git a/website/content/api-docs/system/generate-root.mdx b/website/content/api-docs/system/generate-root.mdx index 29291b2688..20d8deca4a 100644 --- a/website/content/api-docs/system/generate-root.mdx +++ b/website/content/api-docs/system/generate-root.mdx @@ -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 diff --git a/website/content/api-docs/system/health.mdx b/website/content/api-docs/system/health.mdx index f8400db27a..fe3fb76b47 100644 --- a/website/content/api-docs/system/health.mdx +++ b/website/content/api-docs/system/health.mdx @@ -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 diff --git a/website/content/api-docs/system/host-info.mdx b/website/content/api-docs/system/host-info.mdx index 7426e935d8..061f84ffa8 100644 --- a/website/content/api-docs/system/host-info.mdx +++ b/website/content/api-docs/system/host-info.mdx @@ -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. diff --git a/website/content/api-docs/system/in-flight-req.mdx b/website/content/api-docs/system/in-flight-req.mdx index efbbc5f83d..be8e762e85 100644 --- a/website/content/api-docs/system/in-flight-req.mdx +++ b/website/content/api-docs/system/in-flight-req.mdx @@ -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. diff --git a/website/content/api-docs/system/init.mdx b/website/content/api-docs/system/init.mdx index c498042a42..2b9ee679ed 100644 --- a/website/content/api-docs/system/init.mdx +++ b/website/content/api-docs/system/init.mdx @@ -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 diff --git a/website/content/api-docs/system/inspect/router.mdx b/website/content/api-docs/system/inspect/router.mdx index cb24460bd0..181553f8a5 100644 --- a/website/content/api-docs/system/inspect/router.mdx +++ b/website/content/api-docs/system/inspect/router.mdx @@ -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. diff --git a/website/content/api-docs/system/internal-counters.mdx b/website/content/api-docs/system/internal-counters.mdx index 995c42401f..0f0a861c05 100644 --- a/website/content/api-docs/system/internal-counters.mdx +++ b/website/content/api-docs/system/internal-counters.mdx @@ -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 diff --git a/website/content/api-docs/system/key-status.mdx b/website/content/api-docs/system/key-status.mdx index 77518eaece..57dc8e87ba 100644 --- a/website/content/api-docs/system/key-status.mdx +++ b/website/content/api-docs/system/key-status.mdx @@ -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. diff --git a/website/content/api-docs/system/lease-count-quotas.mdx b/website/content/api-docs/system/lease-count-quotas.mdx index bedd83dd65..4dd1b68f33 100644 --- a/website/content/api-docs/system/lease-count-quotas.mdx +++ b/website/content/api-docs/system/lease-count-quotas.mdx @@ -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 diff --git a/website/content/api-docs/system/loggers.mdx b/website/content/api-docs/system/loggers.mdx index 6275e1ae33..19ab633959 100644 --- a/website/content/api-docs/system/loggers.mdx +++ b/website/content/api-docs/system/loggers.mdx @@ -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 diff --git a/website/content/api-docs/system/managed-keys.mdx b/website/content/api-docs/system/managed-keys.mdx index 4e6e867b8a..d0ba49ffc8 100644 --- a/website/content/api-docs/system/managed-keys.mdx +++ b/website/content/api-docs/system/managed-keys.mdx @@ -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. diff --git a/website/content/api-docs/system/metrics.mdx b/website/content/api-docs/system/metrics.mdx index bafea41c0f..f574111db8 100644 --- a/website/content/api-docs/system/metrics.mdx +++ b/website/content/api-docs/system/metrics.mdx @@ -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 diff --git a/website/content/api-docs/system/mfa/duo.mdx b/website/content/api-docs/system/mfa/duo.mdx index 26a95a1008..92f8755600 100644 --- a/website/content/api-docs/system/mfa/duo.mdx +++ b/website/content/api-docs/system/mfa/duo.mdx @@ -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 | diff --git a/website/content/api-docs/system/mfa/okta.mdx b/website/content/api-docs/system/mfa/okta.mdx index 48503a79c7..07ec62f7cc 100644 --- a/website/content/api-docs/system/mfa/okta.mdx +++ b/website/content/api-docs/system/mfa/okta.mdx @@ -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 | diff --git a/website/content/api-docs/system/mfa/pingid.mdx b/website/content/api-docs/system/mfa/pingid.mdx index 32b5ee69a3..ee322bc61a 100644 --- a/website/content/api-docs/system/mfa/pingid.mdx +++ b/website/content/api-docs/system/mfa/pingid.mdx @@ -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 | diff --git a/website/content/api-docs/system/mfa/totp.mdx b/website/content/api-docs/system/mfa/totp.mdx index e1f52d53d6..b4f4057791 100644 --- a/website/content/api-docs/system/mfa/totp.mdx +++ b/website/content/api-docs/system/mfa/totp.mdx @@ -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 | diff --git a/website/content/api-docs/system/pprof.mdx b/website/content/api-docs/system/pprof.mdx index 3cabbd1de2..4f1d371f50 100644 --- a/website/content/api-docs/system/pprof.mdx +++ b/website/content/api-docs/system/pprof.mdx @@ -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. diff --git a/website/content/api-docs/system/quotas-config.mdx b/website/content/api-docs/system/quotas-config.mdx index 1039c87a07..f1cb2700c2 100644 --- a/website/content/api-docs/system/quotas-config.mdx +++ b/website/content/api-docs/system/quotas-config.mdx @@ -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 diff --git a/website/content/api-docs/system/rate-limit-quotas.mdx b/website/content/api-docs/system/rate-limit-quotas.mdx index 33581b03ee..c66d3f3bc2 100644 --- a/website/content/api-docs/system/rate-limit-quotas.mdx +++ b/website/content/api-docs/system/rate-limit-quotas.mdx @@ -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 diff --git a/website/content/api-docs/system/raw.mdx b/website/content/api-docs/system/raw.mdx index fa7d920895..7e788358b3 100644 --- a/website/content/api-docs/system/raw.mdx +++ b/website/content/api-docs/system/raw.mdx @@ -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 diff --git a/website/content/api-docs/system/rekey-recovery-key.mdx b/website/content/api-docs/system/rekey-recovery-key.mdx index e38e49c877..cca8dc3103 100644 --- a/website/content/api-docs/system/rekey-recovery-key.mdx +++ b/website/content/api-docs/system/rekey-recovery-key.mdx @@ -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 diff --git a/website/content/api-docs/system/rekey.mdx b/website/content/api-docs/system/rekey.mdx index 4b92a07d14..fc95fddc98 100644 --- a/website/content/api-docs/system/rekey.mdx +++ b/website/content/api-docs/system/rekey.mdx @@ -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) diff --git a/website/content/api-docs/system/replication/index.mdx b/website/content/api-docs/system/replication/index.mdx index 77346d076d..252eeab1db 100644 --- a/website/content/api-docs/system/replication/index.mdx +++ b/website/content/api-docs/system/replication/index.mdx @@ -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 diff --git a/website/content/api-docs/system/rotate-config.mdx b/website/content/api-docs/system/rotate-config.mdx index f9abecfb84..226189ad86 100644 --- a/website/content/api-docs/system/rotate-config.mdx +++ b/website/content/api-docs/system/rotate-config.mdx @@ -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 diff --git a/website/content/api-docs/system/rotate.mdx b/website/content/api-docs/system/rotate.mdx index f096a8005d..a94a038b4c 100644 --- a/website/content/api-docs/system/rotate.mdx +++ b/website/content/api-docs/system/rotate.mdx @@ -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 diff --git a/website/content/api-docs/system/seal.mdx b/website/content/api-docs/system/seal.mdx index 2a0dbf9a69..2eef0ea0aa 100644 --- a/website/content/api-docs/system/seal.mdx +++ b/website/content/api-docs/system/seal.mdx @@ -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 diff --git a/website/content/api-docs/system/sealwrap-rewrap.mdx b/website/content/api-docs/system/sealwrap-rewrap.mdx index cbcd4b2df7..1323d9ef9c 100644 --- a/website/content/api-docs/system/sealwrap-rewrap.mdx +++ b/website/content/api-docs/system/sealwrap-rewrap.mdx @@ -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. diff --git a/website/content/api-docs/system/step-down.mdx b/website/content/api-docs/system/step-down.mdx index 363acf0bd7..1de82823c3 100644 --- a/website/content/api-docs/system/step-down.mdx +++ b/website/content/api-docs/system/step-down.mdx @@ -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 diff --git a/website/content/api-docs/system/storage/index.mdx b/website/content/api-docs/system/storage/index.mdx index ce25488325..7dd3b67e44 100644 --- a/website/content/api-docs/system/storage/index.mdx +++ b/website/content/api-docs/system/storage/index.mdx @@ -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). diff --git a/website/content/api-docs/system/storage/raft.mdx b/website/content/api-docs/system/storage/raft.mdx index cc7846e513..bc18fc0d9e 100644 --- a/website/content/api-docs/system/storage/raft.mdx +++ b/website/content/api-docs/system/storage/raft.mdx @@ -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. diff --git a/website/content/api-docs/system/storage/raftautopilot.mdx b/website/content/api-docs/system/storage/raftautopilot.mdx index 6c8e7c9d5f..633aba4a8c 100644 --- a/website/content/api-docs/system/storage/raftautopilot.mdx +++ b/website/content/api-docs/system/storage/raftautopilot.mdx @@ -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. diff --git a/website/content/api-docs/system/storage/raftautosnapshots.mdx b/website/content/api-docs/system/storage/raftautosnapshots.mdx index f67c324cd5..1ec127b417 100644 --- a/website/content/api-docs/system/storage/raftautosnapshots.mdx +++ b/website/content/api-docs/system/storage/raftautosnapshots.mdx @@ -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. diff --git a/website/content/api-docs/system/unseal.mdx b/website/content/api-docs/system/unseal.mdx index 1bd635b838..86bbcfc353 100644 --- a/website/content/api-docs/system/unseal.mdx +++ b/website/content/api-docs/system/unseal.mdx @@ -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 diff --git a/website/content/docs/enterprise/namespaces.mdx b/website/content/docs/enterprise/namespaces.mdx deleted file mode 100644 index 8129eddd14..0000000000 --- a/website/content/docs/enterprise/namespaces.mdx +++ /dev/null @@ -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/` - - - -See the [Commands (CLI) - namespace](/vault/docs/commands/namespace) page to -learn more about the `namespace` command and subcommands to create and manage -namespaces. - - - -## 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/` - - - -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. - - - - -## 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. diff --git a/website/content/docs/enterprise/namespaces/create-admin-namespace.mdx b/website/content/docs/enterprise/namespaces/create-admin-namespace.mdx new file mode 100644 index 0000000000..bdfa2a0e7f --- /dev/null +++ b/website/content/docs/enterprise/namespaces/create-admin-namespace.mdx @@ -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 + +Grant access to a predefined subset of privileged system backend endpoints in +the Vault API with an 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. + + + +## 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: + + + +```shell-session +$ vault namespace create ns_admin +``` + + + +## 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: + + + +```hcl +ui = true +api_addr = "https://127.0.0.1:8200" +administrative_namespace_path = "ns_admin/" +``` + + + +## 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: + + + + ```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 + ``` + + + +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: + + + + ```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 + ``` + + + +## 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). \ No newline at end of file diff --git a/website/content/docs/enterprise/namespaces/index.mdx b/website/content/docs/enterprise/namespaces/index.mdx new file mode 100644 index 0000000000..7200fb120e --- /dev/null +++ b/website/content/docs/enterprise/namespaces/index.mdx @@ -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 + +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 + + + + 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. + + + +## 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. + + + + Read the + [Vault namespace and mount structuring](/vault/tutorials/enterprise/namespace-structure) + tutorial for best practices and recommendations for structuring your namespaces. + + + +## 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/` + + + + Use the [/sys/namespaces](/vault/api-docs/system/namespaces) API or + [`namespace`](/vault/docs/commands/namespace) CLI command to manage + your namespaces. + + + +## 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) diff --git a/website/content/partials/api/restricted-endpoints.mdx b/website/content/partials/api/restricted-endpoints.mdx new file mode 100644 index 0000000000..9d28e372b6 --- /dev/null +++ b/website/content/partials/api/restricted-endpoints.mdx @@ -0,0 +1,46 @@ + + +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 \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index a4c4fc09f5..f18db96685 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -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",