KEP-4601: alpha docs

Author: liggitt

content/en/docs/reference/access-authn-authz/node.md

@@ -27,6 +27,13 @@ Read operations:
 * secrets, configmaps, persistent volume claims and persistent volumes related
   to pods bound to the kubelet's node
 
+{{< feature-state feature_gate_name="AuthorizeNodeWithSelectors" >}}
+
+When the `AuthorizeNodeWithSelectors` feature is enabled
+(along with the pre-requisite `AuthorizeWithSelectors` feature),
+kubelets are only allowed to read their own Node objects,
+and are only allowed to read pods bound to their node.
+
 Write operations:
 
 * nodes and node status (enable the `NodeRestriction` admission plugin to limit

content/en/docs/reference/access-authn-authz/validating-admission-policy.md

@@ -283,6 +283,7 @@ variables as well as some other useful variables:
   The value is null if the incoming object is cluster-scoped.
 - `authorizer` - A CEL Authorizer. May be used to perform authorization checks for the principal
   (authenticated user) of the request. See
+  [AuthzSelectors](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#AuthzSelectors) and
   [Authz](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz) in the Kubernetes CEL library
   documentation for more details.
 - `authorizer.requestResource` - A shortcut for an authorization check configured with the request

content/en/docs/reference/access-authn-authz/webhook.md

@@ -164,13 +164,55 @@ Access to non-resource paths are sent as:
 }
 ```
 
+{{< feature-state feature_gate_name="AuthorizeWithSelectors" >}}
+
+With the `AuthorizeWithSelectors` feature enabled, field and label selectors in the request
+are passed to the authorization webhook. The webhook can make authorization decisions
+informed by the scoped field and label selectors, if it wishes.
+
+The [SubjectAccessReview API documentation](/docs/reference/kubernetes-api/authorization-resources/subject-access-review-v1/)
+gives guidelines for how these fields should be interpreted and handled by authorization webhooks,
+specifically using the parsed requirements rather than the raw selector strings,
+and how to handle unrecognized operators safely.
+
+```json
+{
+  "apiVersion": "authorization.k8s.io/v1beta1",
+  "kind": "SubjectAccessReview",
+  "spec": {
+    "resourceAttributes": {
+      "verb": "list",
+      "group": "",
+      "resource": "pods",
+      "fieldSelector": {
+        "requirements": [
+          {"key":"spec.nodeName", "operator":"In", "values":["mynode"]}
+        ]
+      },
+      "labelSelector": {
+        "requirements": [
+          {"key":"example.com/mykey", "operator":"In", "values":["myvalue"]}
+        ]
+      }
+    },
+    "user": "jane",
+    "group": [
+      "group1",
+      "group2"
+    ]
+  }
+}
+```
+
 Non-resource paths include: `/api`, `/apis`, `/metrics`,
 `/logs`, `/debug`, `/healthz`, `/livez`, `/openapi/v2`, `/readyz`, and
 `/version.` Clients require access to `/api`, `/api/*`, `/apis`, `/apis/*`,
 and `/version` to discover what resources and versions are present on the server.
 Access to other non-resource paths can be disallowed without restricting access
 to the REST api.
 
-For further documentation refer to the authorization.v1beta1 API objects and
-[webhook.go](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/apiserver/plugin/pkg/authorizer/webhook/webhook.go).
+For further information, refer to the
+[SubjectAccessReview API documentation](/docs/reference/kubernetes-api/authorization-resources/subject-access-review-v1/)
+and
+[webhook.go implementation](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/apiserver/plugin/pkg/authorizer/webhook/webhook.go).
 

content/en/docs/reference/command-line-tools-reference/feature-gates/authorize-node-with-selectors.md

@@ -0,0 +1,14 @@
+---
+title: AuthorizeNodeWithSelectors
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.31"
+---
+Make the [Node authorizer](/docs/reference/access-authn-authz/node/) use fine-grained selector authorization.
+Requires `AuthorizeWithSelectors` to be enabled.

content/en/docs/reference/command-line-tools-reference/feature-gates/authorize-with-selectors.md

@@ -0,0 +1,17 @@
+---
+title: AuthorizeWithSelectors
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.31"
+---
+Allows authorization to use field and label selectors.
+Enables `fieldSelector` and `labelSelector` fields in the [SubjectAccessReview API](/docs/reference/kubernetes-api/authorization-resources/subject-access-review-v1/),
+passes field and label selector information to [authorization webhooks](/docs/reference/access-authn-authz/webhook/),
+enables `fieldSelector` and `labelSelector` functions in the [authorizer CEL library](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#AuthzSelectors),
+and enables checking `fieldSelector` and `labelSelector` fields in [authorization webhook `matchConditions`](/docs/reference/access-authn-authz/authorization/#using-configuration-file-for-authorization).

content/en/docs/reference/using-api/cel.md

@@ -200,7 +200,19 @@ To perform an authorization check for a service account:
 | `authorizer.serviceAccount('default', 'myserviceaccount').resource('deployments').check('delete').allowed()` | Checks if the service account is authorized to delete deployments. |
 {{< /table >}}
 
+{{< feature-state state="alpha" for_k8s_version="v1.31" >}}
+
+With the alpha `AuthorizeWithSelectors` feature enabled, field and label selectors can be added to authorization checks.
+
+{{< table caption="Examples of CEL expressions using selector authorization functions" >}}
+| CEL Expression                                                                                               | Purpose                                        |
+|--------------------------------------------------------------------------------------------------------------|------------------------------------------------|
+| `authorizer.group('').resource('pods').fieldSelector('spec.nodeName=mynode').check('list').allowed()`        | Returns true if the principal (user or service account) is allowed to list pods with the field selector `spec.nodeName=mynode`. |
+| `authorizer.group('').resource('pods').labelSelector('example.com/mylabel=myvalue').check('list').allowed()` | Returns true if the principal (user or service account) is allowed to list pods with the label selector `example.com/mylabel=myvalue`. |
+{{< /table >}}
+
 See the [Kubernetes Authz library](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz)
+and [Kubernetes AuthzSelectors library](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#AuthzSelectors)
 godoc for more information.
 
 ### Kubernetes quantity library