VAULT-12491 Add docs for group policy config (#18616)

* VAULT-12491 Add docs for group policy config

* VAULT-12491 typo

* VAULT-12491 typo

* VAULT-12491 Update language a bit

* VAULT-12491 Update language a bit

* VAULT-12491 Update language a bit

website/content/api-docs/system/config-group-policy-application.mdx

@@ -0,0 +1,81 @@
+---
+layout: api
+page_title: /sys/config/group-policy-application - HTTP API
+description: The '/sys/config/group-policy-application' endpoint is used to configure the global mode for group policy application.
+---
+
+# `/sys/config/group-policy-application`
+
+~> **Enterprise Only** – These endpoints require Vault Enterprise Platform.
+
+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.
+
+Vault allows you to add entities and groups from any namespace into an identity group.
+However, historically, any policies attached to that group would only apply when the
+Vault token authorizing a request was created in the same namespace as that group,
+or a descendent namespace. This endpoint allows relaxing that restriction: when the mode is set to the default,
+`within_namespace_hierarchy`, the historical behaviour is maintained,
+but when set to `any`, group policies apply to all members of a group,
+regardless of what namespace the request token came from.
+
+Note that this configuration will be replicated between primary and secondaries, that
+is to say, primaries cannot have a different policy application mode to secondaries.
+
+## Get Group Policy Application Information
+
+This endpoint returns the current group policy application mode, which will be
+either `within_namespace_hierarchy` or `any`.
+
+
+| Method | Path                          |
+| :----- | :---------------------------- |
+| `GET`  | `/sys/config/group-policy-application` |
+
+### Sample Request
+
+```shell-session
+$ curl \
+  --header "X-Vault-Token: ..." \
+    'http://127.0.0.1:8200/v1/sys/config/group-policy-application'
+```
+
+### Sample Response
+
+```json
+{
+   "group_policy_application_mode": "within_namespace_hierarchy"
+}
+```
+
+## Set Group Policy Application Information
+
+This endpoint allows you to modify the current group policy application mode, which can be
+either `within_namespace_hierarchy` or `any`. `within_namespace_hierarchy`
+restricts policy application to only policies from groups from parent namespaces, and
+`any` does not restrict policy application in any way, and policies will apply from any namespace,
+irrespective of namespace hierarchy.
+
+
+| Method | Path                          |
+| :----- | :---------------------------- |
+| `POST`, `PUT`  | `/sys/config/group-policy-application` |
+
+### Sample Payload
+
+```json
+{
+   "group_policy_application_mode": "any"
+}
+```
+
+### Sample Request
+
+```shell-session
+$ curl \
+  --request POST \
+  --header "X-Vault-Token: ..." \
+  --data @payload.json \
+  'http://127.0.0.1:8200/v1/sys/config/group-policy-application'
+```

website/content/docs/enterprise/namespaces.mdx

@@ -67,6 +67,7 @@ There are certain API paths that can only be called from the root namespace:
 - `sys/leader`
 - `sys/health`
 - `sys/metrics`
+- `sys/config/group-policy-application`
 - `sys/config/state`
 - `sys/host-info`
 - `sys/key-status`
@@ -95,7 +96,9 @@ 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.
+identities. This behavior can be configured using the [group-policy-application](/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.
 
 ## Tutorial
 

website/data/api-docs-nav-data.json

@@ -421,6 +421,15 @@
         "title": "<code>/sys/config/cors</code>",
         "path": "system/config-cors"
       },
+      {
+        "title": "<code>/sys/config/group-policy-application</code>",
+        "path": "system/config-group-policy-application",
+        "badge": {
+          "text": "ENT",
+          "type": "outlined",
+          "color": "neutral"
+        }
+      },
       {
         "title": "<code>/sys/config/reload</code>",
         "path": "system/config-reload"