From 4e4b0ff301ab90eebe342284bd9da382f6b72212 Mon Sep 17 00:00:00 2001
From: Pawel Kopiczko <pawel.kopiczko@goteleport.com>
Date: Fri, 29 Nov 2024 12:14:13 +0000
Subject: [PATCH] Add docs for role.spec.allow.reason.mode (#49537)

---
 .../access-request-configuration.mdx          | 49 ++++++++++++++++---
 1 file changed, 42 insertions(+), 7 deletions(-)

diff --git a/docs/pages/admin-guides/access-controls/access-requests/access-request-configuration.mdx b/docs/pages/admin-guides/access-controls/access-requests/access-request-configuration.mdx
index 5b80c34ff7e30..a98b16246faf5 100644
--- a/docs/pages/admin-guides/access-controls/access-requests/access-request-configuration.mdx
+++ b/docs/pages/admin-guides/access-controls/access-requests/access-request-configuration.mdx
@@ -53,7 +53,7 @@ below:
 
 ```yaml
 kind: role
-version: v6
+version: v7
 metadata:
   name: employee
 spec:
@@ -120,7 +120,7 @@ For example, the following role enables a user to search for resources that the
 ```yaml
 # requester.yaml
 kind: role
-version: v6
+version: v7
 metadata:
   name: k8s-requester
 spec:
@@ -215,7 +215,7 @@ You can specify the `max_duration` option with a role like the following:
 
 ```yaml
 kind: role
-version: v6
+version: v7
 metadata:
   name: temp-dba
 spec:
@@ -271,7 +271,7 @@ your ticket ID":
 
 ```yaml
 kind: role
-version: v6
+version: v7
 metadata:
   name: employee
 spec:
@@ -294,6 +294,41 @@ user:
 1. If one of the user's roles includes the `reason` strategy, the user must
    provide a reason when authenticating.
 
+## Requiring request reasons
+
+The `allow.request.reason.mode` field controls whether a reason is required when users submit
+Access Requests.
+
+Allowed values are:
+
+|Value|Meaning|
+|---|---|
+| `optional` | The default. The user does not need to provide a reason when making a request. |
+| `required` | The user must provide a non-empty reason when making a request. |
+
+Example:
+
+```yaml
+kind: role
+version: v7
+metadata:
+  name: node-requester
+spec:
+  allow:
+    request:
+      roles:
+        - 'node-access'
+      search_as_roles:
+        - 'root-node-access'
+      reason:
+        mode: 'required'
+```
+
+If a user with "node-requester" role assigned makes an Access Request for "node-access" role or any
+resource allowed by "root-node-access" they will be required to provide a reason. If a user's
+role set includes multiple roles governing Access Requests to the same roles and resources,
+"require" mode takes precedence.
+
 ## Review thresholds
 
 You can configure a user's roles to specify the criteria that an Access Request
@@ -307,7 +342,7 @@ roles:
 
 ```yaml
 kind: role
-version: v6
+version: v7
 metadata:
   name: devops
 spec:
@@ -430,7 +465,7 @@ The following role adds the suggested reviewers `user1` and `user2`:
 
 ```yaml
 kind: role
-version: v6
+version: v7
 metadata:
   name: employee
 spec:
@@ -559,7 +594,7 @@ them, use the `allow.review_requests.preview_as_roles` and
 
 ```yaml
 kind: role
-version: v6
+version: v7
 metadata:
   name: reviewer
 spec: