From 5dab30d474bf12aaeb515bb857b49eba60c95392 Mon Sep 17 00:00:00 2001 From: Jordan Liggitt Date: Wed, 26 Jun 2024 14:12:51 -0400 Subject: [PATCH] KEP-4601: alpha docs --- .../docs/reference/access-authn-authz/node.md | 7 +++ .../validating-admission-policy.md | 1 + .../reference/access-authn-authz/webhook.md | 46 ++++++++++++++++++- .../authorize-node-with-selectors.md | 14 ++++++ .../feature-gates/authorize-with-selectors.md | 17 +++++++ content/en/docs/reference/using-api/cel.md | 12 +++++ 6 files changed, 95 insertions(+), 2 deletions(-) create mode 100644 content/en/docs/reference/command-line-tools-reference/feature-gates/authorize-node-with-selectors.md create mode 100644 content/en/docs/reference/command-line-tools-reference/feature-gates/authorize-with-selectors.md diff --git a/content/en/docs/reference/access-authn-authz/node.md b/content/en/docs/reference/access-authn-authz/node.md index f47a481170..d39b404c0c 100644 --- a/content/en/docs/reference/access-authn-authz/node.md +++ b/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 diff --git a/content/en/docs/reference/access-authn-authz/validating-admission-policy.md b/content/en/docs/reference/access-authn-authz/validating-admission-policy.md index 2d0ae27344..925d0e5c0c 100644 --- a/content/en/docs/reference/access-authn-authz/validating-admission-policy.md +++ b/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 diff --git a/content/en/docs/reference/access-authn-authz/webhook.md b/content/en/docs/reference/access-authn-authz/webhook.md index d5362e0acf..cb91ac34c6 100644 --- a/content/en/docs/reference/access-authn-authz/webhook.md +++ b/content/en/docs/reference/access-authn-authz/webhook.md @@ -164,6 +164,46 @@ 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/*`, @@ -171,6 +211,8 @@ 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). diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/authorize-node-with-selectors.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/authorize-node-with-selectors.md new file mode 100644 index 0000000000..9c09c59f97 --- /dev/null +++ b/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. diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/authorize-with-selectors.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/authorize-with-selectors.md new file mode 100644 index 0000000000..4626d486b1 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/content/en/docs/reference/using-api/cel.md b/content/en/docs/reference/using-api/cel.md index 28adf0bb07..f8c4ed4bcf 100644 --- a/content/en/docs/reference/using-api/cel.md +++ b/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