From 4276616d28e86ac10315533e559ad486e8a4063a Mon Sep 17 00:00:00 2001
From: Lisa Kim <lisa@goteleport.com>
Date: Thu, 7 Nov 2024 18:38:16 -0800
Subject: [PATCH] Add doc on new field `request.kubernetes_resources` (#48480)

* Add doc on new field

* Address reviews

* fix lint
---
 .../access-requests/resource-requests.mdx     | 67 +++++++++++++++++++
 docs/pages/includes/role-spec.mdx             |  7 ++
 2 files changed, 74 insertions(+)

diff --git a/docs/pages/admin-guides/access-controls/access-requests/resource-requests.mdx b/docs/pages/admin-guides/access-controls/access-requests/resource-requests.mdx
index 569e29df64358..96520bfe90a89 100644
--- a/docs/pages/admin-guides/access-controls/access-requests/resource-requests.mdx
+++ b/docs/pages/admin-guides/access-controls/access-requests/resource-requests.mdx
@@ -406,6 +406,73 @@ Requesting access to a Kubernetes Namespace allows you to access all resources
 in that namespace but you won't be able to access any other supported resources
 in the cluster.
 
+##### Restrict Access Requests to specific Kubernetes resource kinds
+
+The `request.kubernetes_resources` field allows you to restrict what kinds of Kubernetes 
+resources a user can request access to. Configuring this field to any value will disallow
+requesting access to the entire Kubernetes cluster.
+
+If the `request.kubernetes_resources` field is not configured, then a user can request access 
+to any Kubernetes resources, including the entire Kubernetes cluster.
+
+The following role allows users to request access to Kubernetes namespaces. 
+Requests for Kubernetes resources other than `namespace` will not be allowed.
+
+```yaml
+kind: role
+metadata:
+  name: requester-kube-access
+version: v7
+spec:
+  allow:
+    request:
+      search_as_roles:
+        - "kube-access"
+      kubernetes_resources:
+        - kind: "namespace"
+```
+
+The following role allows users to request access only to Kubernetes namespaces and/or pods.
+
+```yaml
+kind: role
+metadata:
+  name: requester-kube-access
+version: v7
+spec:
+  allow:
+    request:
+      search_as_roles:
+        - "kube-access"
+      kubernetes_resources:
+        - kind: "namespace"
+        - kind: "pod"
+```
+
+The following role allows users to request access to any specific Kubernetes resources.
+
+```yaml
+kind: role
+metadata:
+  name: requester-kube-access
+version: v7
+spec:
+  allow:
+    request:
+      search_as_roles:
+        - "kube-access"
+      kubernetes_resources:
+        - kind: "*"
+```
+
+See related section about [Kubernetes Resources](../../../enroll-resources/kubernetes-access/controls.mdx#kubernetes_resources) 
+to see a list of supported `kind` values.
+
+The `request.kubernetes_resources` field only restricts what `kinds` of Kubernetes resource requests are allowed.
+To control Kubernetes access to these resources see 
+[Preventing unintended access to Kubernetes resources](#preventing-unintended-access-to-kubernetes-resources) 
+section for more details.
+
 #### `db`
 
 You can restrict access to searching `db` resources by assigning values to the
diff --git a/docs/pages/includes/role-spec.mdx b/docs/pages/includes/role-spec.mdx
index 3030a255d21f0..caa60ae7e2503 100644
--- a/docs/pages/includes/role-spec.mdx
+++ b/docs/pages/includes/role-spec.mdx
@@ -350,6 +350,13 @@ spec:
       # resources accessible by the listed roles (enterprise-only)
       search_as_roles: ['access']
 
+      # 'kubernetes_resources' restricts what kinds of Kubernetes resources
+      # a user can request access to. In the below example, users can
+      # request only Kubernetes namespaces. Default (when nothing is defined) allows
+      # access requests to any Kubernetes resource or the entire cluster.
+      kubernetes_resources:
+        - kind: "namespace"
+
       # thresholds specifies minimum amount of approvers and deniers,
       # defaults to 1 for both (enterprise-only)
       thresholds: