Merge pull request #40971 from jpbetz/cel-authz

Add authz library details to CEL documentation

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

@@ -144,6 +144,44 @@ Examples:
 See the [Kubernetes URL library](https://pkg.go.dev/k8s.io/apiextensions-apiserver/pkg/apiserver/schema/cel/library#URLs)
 godoc for more information.
 
+### Kubernetes authorizer library
+
+For CEL expressions in the API where a variable of type `Authorizer` is available,
+the authorizer may be used to perform authorization checks for the principal
+(authenticated user) of the request.
+
+API resource checks are performed as follows:
+
+1. Specify the group and resource to check: `Authorizer.group(string).resource(string) ResourceCheck`
+2. Optionally call any combination of the following builder functions to further narrow the authorization check.
+   Note that these functions return the receiver type and can be chained:
+  - `ResourceCheck.subresource(string) ResourceCheck`
+  - `ResourceCheck.namespace(string) ResourceCheck`
+  - `ResourceCheck.name(string) ResourceCheck` 
+3. Call `ResourceCheck.check(verb string) Decision` to perform the authorization check.
+4. Call `allowed() bool` or `reason() string` to inspect the result of the authorization check.
+
+Non-resource authorization performed are used as follows:
+
+1. specify only a path: `Authorizer.path(string) PathCheck`
+1. Call `PathCheck.check(httpVerb string) Decision` to perform the authorization check.
+1. Call `allowed() bool` or `reason() string` to inspect the result of the authorization check.
+
+To perform an authorization check for a service account:
+
+- `Authorizer.serviceAccount(namespace string, name string) Authorizer`
+
+{{< table caption="Examples of CEL expressions using URL library functions" >}}
+| CEL Expression                                                                                               | Purpose                                        |
+|--------------------------------------------------------------------------------------------------------------|------------------------------------------------|
+| `authorizer.group('').resource('pods').namespace('default').check('create').allowed()`                       | Returns true if the principal (user or service account) is allowed create pods in the 'default' namespace. |
+| `authorizer.path('/healthz').check('get').allowed()`                                                         | Checks if the principal (user or service account) is authorized to make HTTP GET requests to the /healthz API path. |
+| `authorizer.serviceAccount('default', 'myserviceaccount').resource('deployments').check('delete').allowed()` | Checks if the service account is authorized to delete deployments. |
+{{< /table >}}
+
+See the [Kubernetes Authz library](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz)
+godoc for more information.
+
 ## Type checking
 
 CEL is a [gradually typed language](https://github.com/google/cel-spec/blob/master/doc/langdef.md#gradual-type-checking).
@@ -297,4 +335,4 @@ execute. If so, the API server prevent the CEL expression from being written to
 API resources by rejecting create or update operations containing the CEL
 expression to the API resources. This feature offers a stronger assurance that
 CEL expressions written to the API resource will be evaluate at runtime without
-exceeding the runtime cost budget.
+exceeding the runtime cost budget.