Merge pull request #48130 from sftim/20240929_tweak_admission_control

Improve admission control reference

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

@@ -6,41 +6,62 @@ reviewers:
 - erictune
 - janetkuo
 - thockin
-title: Admission Controllers Reference
-linkTitle: Admission Controllers
+title: Admission Control in Kubernetes
+linkTitle: Admission Control
 content_type: concept
 weight: 40
 ---
 
 <!-- overview -->
-This page provides an overview of Admission Controllers.
+This page provides an overview of _admission controllers_.
 
+An admission controller is a piece of code that intercepts requests to the
+Kubernetes API server prior to persistence of the resource, but after the request
+is authenticated and authorized.
+
+Several important features of Kubernetes require an admission controller to be enabled in order
+to properly support the feature.  As a result, a Kubernetes API server that is not properly
+configured with the right set of admission controllers is an incomplete server that will not
+support all the features you expect.
 
 <!-- body -->
 ## What are they?
 
-An _admission controller_ is a piece of code that intercepts requests to the
-Kubernetes API server prior to persistence of the object, but after the request
-is authenticated and authorized.
+Admission controllers are code within the Kubernetes
+{{< glossary_tooltip term_id="kube-apiserver" text="API server" >}} that check the
+data arriving in a request to modify a resource.
 
-Admission controllers may be _validating_, _mutating_, or both. Mutating
-controllers may modify objects related to the requests they admit; validating controllers may not.
+Admission controllers apply to requests that create, delete, or modify objects.
+Admission controllers can also block custom verbs, such as a request to connect to a
+pod via an API server proxy. Admission controllers do _not_ (and cannot) block requests
+to read (**get**, **watch** or **list**) objects, because reads bypass the admission
+control layer.
 
-Admission controllers limit requests to create, delete, modify objects. Admission
-controllers can also block custom verbs, such as a request connect to a Pod via
-an API server proxy. Admission controllers do _not_ (and cannot) block requests
-to read (**get**, **watch** or **list**) objects.
+Admission control mechanisms may be _validating_, _mutating_, or both. Mutating
+controllers may modify the data for the resource being modified; validating controllers may not.
 
 The admission controllers in Kubernetes {{< skew currentVersion >}} consist of the
 [list](#what-does-each-admission-controller-do) below, are compiled into the
 `kube-apiserver` binary, and may only be configured by the cluster
-administrator. In that list, there are two special controllers:
-MutatingAdmissionWebhook and ValidatingAdmissionWebhook.  These execute the
-mutating and validating (respectively)
-[admission control webhooks](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks)
-which are configured in the API.
+administrator.
 
-## Admission control phases
+### Admission control extension points
+
+Within the full [list](#what-does-each-admission-controller-do), there are three
+special controllers:
+[MutatingAdmissionWebhook](#mutatingadmissionwebhook),
+[ValidatingAdmissionWebhook](#validatingadmissionwebhook), and
+[ValidatingAdmissionPolicy](#validatingadmissionpolicy).
+The two webhook controllers execute the mutating and validating (respectively)
+[admission control webhooks](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks)
+which are configured in the API. ValidatingAdmissionPolicy provides a way to embed
+declarative validation code within the API, without relying on any external HTTP
+callouts.
+
+You can use these three admission controllers to customize cluster behavior at
+admission time.
+
+### Admission control phases
 
 The admission control process proceeds in two phases. In the first phase,
 mutating admission controllers are run. In the second phase, validating
@@ -58,12 +79,7 @@ corresponding reclamation or reconciliation process, as a given admission
 controller does not know for sure that a given request will pass all of the
 other admission controllers.
 
-## Why do I need them?
 
-Several important features of Kubernetes require an admission controller to be enabled in order
-to properly support the feature.  As a result, a Kubernetes API server that is not properly
-configured with the right set of admission controllers is an incomplete server and will not
-support all the features you expect.
 
 ## How do I turn on an admission controller?
 
@@ -105,13 +121,6 @@ In Kubernetes {{< skew currentVersion >}}, the default ones are:
 CertificateApproval, CertificateSigning, CertificateSubjectRestriction, DefaultIngressClass, DefaultStorageClass, DefaultTolerationSeconds, LimitRanger, MutatingAdmissionWebhook, NamespaceLifecycle, PersistentVolumeClaimResize, PodSecurity, Priority, ResourceQuota, RuntimeClass, ServiceAccount, StorageObjectInUseProtection, TaintNodesByCondition, ValidatingAdmissionPolicy, ValidatingAdmissionWebhook
 ```
 
-{{< note >}}
-The [`ValidatingAdmissionPolicy`](#validatingadmissionpolicy) admission plugin is enabled
-by default, but is only active if you enable the `ValidatingAdmissionPolicy`
-[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) **and**
-the `admissionregistration.k8s.io/v1alpha1` API.
-{{< /note >}}
-
 ## What does each admission controller do?
 
 ### AlwaysAdmit {#alwaysadmit}