Merge pull request kubernetes#37734 from sftim/20221105_tweak_admissi…

…on_controllers_reference

Tweak reference for admission controllers

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

@@ -6,7 +6,8 @@ reviewers:
 - erictune
 - janetkuo
 - thockin
-title: Using Admission Controllers
+title: Admission Controllers Reference
+linkTitle: Admission Controllers
 content_type: concept
 weight: 30
 ---
@@ -18,9 +19,19 @@ This page provides an overview of Admission Controllers.
 <!-- body -->
 ## What are they?
 
-An admission controller is a piece of code that intercepts requests to the
+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.  The controllers consist of the
+is authenticated and authorized.
+
+Admission controllers may be _validating_, _mutating_, or both. Mutating
+controllers may modify related objects to the requests they admit; validating controllers may not.
+
+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.
+
+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:
@@ -29,10 +40,7 @@ mutating and validating (respectively)
 [admission control webhooks](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks)
 which are configured in the API.
 
-Admission controllers may be "validating", "mutating", or both. Mutating
-controllers may modify related objects to the requests they admit; validating controllers may not.
-
-Admission controllers limit requests to create, delete, modify objects or connect to proxy. They do not limit requests to read objects.
+## 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
@@ -52,7 +60,7 @@ other admission controllers.
 
 ## Why do I need them?
 
-Many advanced features in Kubernetes require an admission controller to be enabled in order
+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.
@@ -91,7 +99,7 @@ To see which admission plugins are enabled:
 kube-apiserver -h | grep enable-admission-plugins
 ```
 
-In the current version, the default ones are:
+In Kubernetes {{< skew currentVersion >}}, the default ones are:
 
 ```shell
 CertificateApproval, CertificateSigning, CertificateSubjectRestriction, DefaultIngressClass, DefaultStorageClass, DefaultTolerationSeconds, LimitRanger, MutatingAdmissionWebhook, NamespaceLifecycle, PersistentVolumeClaimResize, PodSecurity, Priority, ResourceQuota, RuntimeClass, ServiceAccount, StorageObjectInUseProtection, TaintNodesByCondition, ValidatingAdmissionWebhook
@@ -103,18 +111,18 @@ CertificateApproval, CertificateSigning, CertificateSubjectRestriction, DefaultI
 
 {{< feature-state for_k8s_version="v1.13" state="deprecated" >}}
 
-This admission controller allows all pods into the cluster. It is deprecated because
+This admission controller allows all pods into the cluster. It is **deprecated** because
 its behavior is the same as if there were no admission controller at all.
 
 ### AlwaysDeny {#alwaysdeny}
 
 {{< feature-state for_k8s_version="v1.13" state="deprecated" >}}
 
-Rejects all requests. AlwaysDeny is DEPRECATED as it has no real meaning.
+Rejects all requests. AlwaysDeny is **deprecated** as it has no real meaning.
 
 ### AlwaysPullImages {#alwayspullimages}
 
-This admission controller modifies every new Pod to force the image pull policy to Always. This is useful in a
+This admission controller modifies every new Pod to force the image pull policy to `Always`. This is useful in a
 multitenant cluster so that users can be assured that their private images can only be used by those
 who have the credentials to pull them. Without this admission controller, once an image has been pulled to a
 node, any pod from any user can use it by knowing the image's name (assuming the Pod is
@@ -124,8 +132,8 @@ required.
 
 ### CertificateApproval {#certificateapproval}
 
-This admission controller observes requests to 'approve' CertificateSigningRequest resources and performs additional
-authorization checks to ensure the approving user has permission to `approve` certificate requests with the
+This admission controller observes requests to approve CertificateSigningRequest resources and performs additional
+authorization checks to ensure the approving user has permission to **approve** certificate requests with the
 `spec.signerName` requested on the CertificateSigningRequest resource.
 
 See [Certificate Signing Requests](/docs/reference/access-authn-authz/certificate-signing-requests/) for more
@@ -134,7 +142,7 @@ information on the permissions required to perform different actions on Certific
 ### CertificateSigning {#certificatesigning}
 
 This admission controller observes updates to the `status.certificate` field of CertificateSigningRequest resources
-and performs an additional authorization checks to ensure the signing user has permission to `sign` certificate
+and performs an additional authorization checks to ensure the signing user has permission to **sign** certificate
 requests with the `spec.signerName` requested on the CertificateSigningRequest resource.
 
 See [Certificate Signing Requests](/docs/reference/access-authn-authz/certificate-signing-requests/) for more
@@ -159,7 +167,7 @@ must revisit their `IngressClass` objects and mark only one as default (with the
 "ingressclass.kubernetes.io/is-default-class").  This admission controller ignores any `Ingress`
 updates; it acts only on creation.
 
-See the [ingress](/docs/concepts/services-networking/ingress/) documentation for more about ingress
+See the [Ingress](/docs/concepts/services-networking/ingress/) documentation for more about ingress
 classes and how to mark one as default.
 
 ### DefaultStorageClass {#defaultstorageclass}
@@ -181,7 +189,7 @@ storage classes and how to mark a storage class as default.
 
 This admission controller sets the default forgiveness toleration for pods to tolerate
 the taints `notready:NoExecute` and `unreachable:NoExecute` based on the k8s-apiserver input parameters
-`default-not-ready-toleration-seconds` and `default-unreachable-toleration-seconds` if the pods don't already 
+`default-not-ready-toleration-seconds` and `default-unreachable-toleration-seconds` if the pods don't already
 have toleration for taints `node.kubernetes.io/not-ready:NoExecute` or
 `node.kubernetes.io/unreachable:NoExecute`.
 The default value for `default-not-ready-toleration-seconds` and `default-unreachable-toleration-seconds` is 5 minutes.
@@ -206,7 +214,7 @@ This admission controller is disabled by default.
 {{< feature-state for_k8s_version="v1.13" state="alpha" >}}
 
 This admission controller mitigates the problem where the API server gets flooded by
-event requests. The cluster admin can specify event rate limits by:
+requests to store new Events. The cluster admin can specify event rate limits by:
 
 * Enabling the `EventRateLimit` admission controller;
 * Referencing an `EventRateLimit` configuration file from the file provided to the API
@@ -223,7 +231,7 @@ plugins:
 
 There are four types of limits that can be specified in the configuration:
 
- * `Server`: All event requests received by the API server share a single bucket.
+ * `Server`: All Event requests (creation or modifications) received by the API server share a single bucket.
  * `Namespace`: Each namespace has a dedicated bucket.
  * `User`: Each user is allocated a bucket.
  * `SourceAndObject`: A bucket is assigned by each combination of source and
@@ -266,7 +274,7 @@ The ImagePolicyWebhook admission controller allows a backend webhook to make adm
 
 This admission controller is disabled by default.
 
-#### Configuration File Format
+#### Configuration file format {#imagereview-config-file-format}
 
 ImagePolicyWebhook uses a configuration file to set options for the behavior of the backend.
 This file may be json or yaml and has the following format:
@@ -377,8 +385,8 @@ An example request body:
 }
 ```
 
-The remote service is expected to fill the `ImageReviewStatus` field of the request and
-respond to either allow or disallow access. The response body's `spec` field is ignored and
+The remote service is expected to fill the `status` field of the request and
+respond to either allow or disallow access. The response body's `spec` field is ignored, and
 may be omitted. A permissive response would return:
 
 ```json
@@ -529,9 +537,9 @@ permissions required to operate correctly.
 ### OwnerReferencesPermissionEnforcement {#ownerreferencespermissionenforcement}
 
 This admission controller protects the access to the `metadata.ownerReferences` of an object
-so that only users with "delete" permission to the object can change it.
+so that only users with **delete** permission to the object can change it.
 This admission controller also protects the access to `metadata.ownerReferences[x].blockOwnerDeletion`
-of an object, so that only users with "update" permission to the `finalizers`
+of an object, so that only users with **update** permission to the `finalizers`
 subresource of the referenced *owner* can change it.
 
 ### PersistentVolumeClaimResize {#persistentvolumeclaimresize}
@@ -568,12 +576,12 @@ For more information about persistent volume claims, see [PersistentVolumeClaims
 {{< feature-state for_k8s_version="v1.13" state="deprecated" >}}
 
 This admission controller automatically attaches region or zone labels to PersistentVolumes
-as defined by the cloud provider (for example, GCE or AWS).
+as defined by the cloud provider (for example, Azure or GCP).
 It helps ensure the Pods and the PersistentVolumes mounted are in the same
 region and/or zone.
 If the admission controller doesn't support automatic labelling your PersistentVolumes, you
 may need to add the labels manually to prevent pods from mounting volumes from
-a different zone. PersistentVolumeLabel is DEPRECATED and labeling persistent volumes has been taken over by
+a different zone. PersistentVolumeLabel is **deprecated** as labeling for persistent volumes has been taken over by
 the {{< glossary_tooltip text="cloud-controller-manager" term_id="cloud-controller-manager" >}}.
 
 This admission controller is disabled by default.
@@ -745,7 +753,8 @@ pod privileges.
 
 This admission controller implements automation for
 [serviceAccounts](/docs/tasks/configure-pod-container/configure-service-account/).
-We strongly recommend using this admission controller if you intend to make use of Kubernetes
+The Kubernetes project strongly recommends enabling this admission controller.
+You should enable this admission controller if you intend to make any use of Kubernetes
 `ServiceAccount` objects.
 
 ### StorageObjectInUseProtection