Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs for Structured Authz beta #45138

Merged
merged 1 commit into from
Mar 12, 2024
Merged

Add docs for Structured Authz beta #45138

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 15 additions & 18 deletions content/en/docs/reference/access-authn-authz/authorization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,33 +211,31 @@ so an earlier module has higher priority to allow or deny a request.

## Configuring the API Server using an Authorization Config File

{{< feature-state state="alpha" for_k8s_version="v1.29" >}}
{{< feature-state state="beta" for_k8s_version="v1.30" >}}

The Kubernetes API server's authorizer chain can be configured using a
configuration file.

You specify the path to that authorization configuration using the
`--authorization-config` command line argument. This feature enables
creation of authorization chains with multiple webhooks with well-defined
parameters that validate requests in a certain order and enables fine grained
control - such as explicit Deny on failures. An example configuration with
all possible values is provided below.
This feature enables the creation of authorization chains with multiple webhooks with well-defined parameters that validate requests in a particular order and allows fine-grained control – such as explicit Deny on failures. The configuration file approach even allows you to specify [CEL](/docs/reference/using-api/cel/) rules to pre-filter requests before they are dispatched to webhooks, helping you to prevent unnecessary invocations. The API server also automatically reloads the authorizer chain when the configuration file is modified. An example configuration with all possible values is provided below.

In order to customise the authorizer chain, you need to enable the
`StructuredAuthorizationConfiguration` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
You must specify the path to the authorization configuration using the `--authorization-config`command line argument. If you want to keep using command line flags instead of a configuration file, those will continue to work as-is. To gain access to new authorization webhook capabilities like multiple webhooks, failure policy, and pre-filter rules, switch to putting options in an `--authorization-config` file.

Note: When the feature is enabled, setting both `--authorization-config` and
Starting Kubernetes 1.30, the configuration file format is
beta-level, and only requires specifying `--authorization-config` since the `StructuredAuthorizationConfiguration` feature gate is enabled by default.

{{< caution >}}
If you want to keep using command line flags to configure authorization instead of a configuration file, those will continue to work as-is.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally, we would write this so it makes sense to someone who is setting up a cluster from scratch. This text assumes that someone has upgraded.


When the feature is enabled, setting both `--authorization-config` and
configuring an authorization webhook using the `--authorization-mode` and
`--authorization-webhook-*` command line flags is not allowed. If done, there
will be an error and API Server would exit right away.

{{< caution >}}
While the feature is in Alpha/Beta, there is no change if you want to keep on
using command line flags. When the feature goes Beta, the feature flag would
be turned on by default. The feature flag would be removed when feature goes GA.
Authorization Config file reloads when an observed file event occurs or a 1 minute poll is encountered. All non-webhook authorizer types are required to remain unchanged in the file on reload. Reload must not add or remove Node or RBAC
authorizers. They can be reordered, but cannot be added or removed.

When configuring the authorizer chain using a config file, make sure all the
apiserver nodes have the file. Also, take a note of the apiserver configuration
apiserver nodes have the file. Take a note of the apiserver configuration
when upgrading/downgrading the clusters. For example, if upgrading to v1.29+
clusters and using the config file, you would need to make sure the config file
exists before upgrading the cluster. When downgrading to v1.28, you would need
Expand All @@ -248,9 +246,8 @@ to add the flags back to their bootstrap mechanism.
#
# DO NOT USE THE CONFIG AS IS. THIS IS AN EXAMPLE.
#
apiVersion: apiserver.config.k8s.io/v1alpha1
apiVersion: apiserver.config.k8s.io/v1beta1
kind: AuthorizationConfiguration
# authorizers are defined in order of precedence
authorizers:
- type: Webhook
# Name used to describe the authorizer
Expand Down Expand Up @@ -283,7 +280,7 @@ authorizers:
# MatchConditionSubjectAccessReviewVersion specifies the SubjectAccessReview
# version the CEL expressions are evaluated against
# Valid values: v1
# Required only if matchConditions are specified, no default value
# Required, no default value
matchConditionSubjectAccessReviewVersion: v1
# Controls the authorization decision when a webhook request fails to
# complete or returns a malformed response or errors evaluating
Expand Down