Merge pull request #42270 from skrobul/validating-and-mutation-controllers

admission controllers: document types

Author: k8s-ci-robot

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

@@ -118,17 +118,23 @@ the `admissionregistration.k8s.io/v1alpha1` API.
 
 {{< feature-state for_k8s_version="v1.13" state="deprecated" >}}
 
+**Type**: Validating.
+
 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" >}}
 
+**Type**: Validating.
+
 Rejects all requests. AlwaysDeny is **deprecated** as it has no real meaning.
 
 ### AlwaysPullImages {#alwayspullimages}
 
+**Type**: Mutating and Validating.
+
 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
@@ -139,6 +145,8 @@ required.
 
 ### CertificateApproval {#certificateapproval}
 
+**Type**: Validating.
+
 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.
@@ -148,6 +156,8 @@ information on the permissions required to perform different actions on Certific
 
 ### CertificateSigning {#certificatesigning}
 
+**Type**: Validating.
+
 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
 requests with the `spec.signerName` requested on the CertificateSigningRequest resource.
@@ -157,12 +167,16 @@ information on the permissions required to perform different actions on Certific
 
 ### CertificateSubjectRestriction {#certificatesubjectrestriction}
 
+**Type**: Validating.
+
 This admission controller observes creation of CertificateSigningRequest resources that have a `spec.signerName`
 of `kubernetes.io/kube-apiserver-client`. It rejects any request that specifies a 'group' (or 'organization attribute')
 of `system:masters`.
 
 ### DefaultIngressClass {#defaultingressclass}
 
+**Type**: Mutating.
+
 This admission controller observes creation of `Ingress` objects that do not request any specific
 ingress class and automatically adds a default ingress class to them.  This way, users that do not
 request any special ingress class do not need to care about them at all and they will get the
@@ -179,6 +193,8 @@ classes and how to mark one as default.
 
 ### DefaultStorageClass {#defaultstorageclass}
 
+**Type**: Mutating.
+
 This admission controller observes creation of `PersistentVolumeClaim` objects that do not request any specific storage class
 and automatically adds a default storage class to them.
 This way, users that do not request any special storage class do not need to care about them at all and they
@@ -194,6 +210,8 @@ storage classes and how to mark a storage class as default.
 
 ### DefaultTolerationSeconds {#defaulttolerationseconds}
 
+**Type**: Mutating.
+
 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
@@ -203,6 +221,8 @@ The default value for `default-not-ready-toleration-seconds` and `default-unreac
 
 ### DenyServiceExternalIPs
 
+**Type**: Validating.
+
 This admission controller rejects all net-new usage of the `Service` field `externalIPs`.  This
 feature is very powerful (allows network traffic interception) and not well
 controlled by policy.  When enabled, users of the cluster may not create new
@@ -220,6 +240,8 @@ This admission controller is disabled by default.
 
 {{< feature-state for_k8s_version="v1.13" state="alpha" >}}
 
+**Type**: Validating.
+
 This admission controller mitigates the problem where the API server gets flooded by
 requests to store new Events. The cluster admin can specify event rate limits by:
 
@@ -266,6 +288,8 @@ This admission controller is disabled by default.
 
 ### ExtendedResourceToleration {#extendedresourcetoleration}
 
+**Type**: Mutating.
+
 This plug-in facilitates creation of dedicated nodes with extended resources.
 If operators want to create dedicated nodes with extended resources (like GPUs, FPGAs etc.), they are expected to
 [taint the node](/docs/concepts/scheduling-eviction/taint-and-toleration/#example-use-cases) with the extended resource
@@ -277,6 +301,8 @@ This admission controller is disabled by default.
 
 ### ImagePolicyWebhook {#imagepolicywebhook}
 
+**Type**: Validating.
+
 The ImagePolicyWebhook admission controller allows a backend webhook to make admission decisions.
 
 This admission controller is disabled by default.
@@ -439,13 +465,17 @@ In any case, the annotations are provided by the user and are not validated by K
 
 ### LimitPodHardAntiAffinityTopology {#limitpodhardantiaffinitytopology}
 
+**Type**: Validating.
+
 This admission controller denies any pod that defines `AntiAffinity` topology key other than
 `kubernetes.io/hostname` in `requiredDuringSchedulingRequiredDuringExecution`.
 
 This admission controller is disabled by default.
 
 ### LimitRanger {#limitranger}
 
+**Type**: Mutating and Validating.
+
 This admission controller will observe the incoming request and ensure that it does not violate
 any of the constraints enumerated in the `LimitRange` object in a `Namespace`.  If you are using
 `LimitRange` objects in your Kubernetes deployment, you MUST use this admission controller to
@@ -459,6 +489,8 @@ for more details.
 
 ### MutatingAdmissionWebhook {#mutatingadmissionwebhook}
 
+**Type**: Mutating.
+
 This admission controller calls any mutating webhooks which match the request. Matching
 webhooks are called in serial; each one may modify the object if it desires.
 
@@ -487,6 +519,8 @@ group/version via the `--runtime-config` flag, both are on by default.
 
 ### NamespaceAutoProvision {#namespaceautoprovision}
 
+**Type**: Mutating.
+
 This admission controller examines all incoming requests on namespaced resources and checks
 if the referenced namespace does exist.
 It creates a namespace if it cannot be found.
@@ -495,11 +529,15 @@ a namespace prior to its usage.
 
 ### NamespaceExists {#namespaceexists}
 
+**Type**: Validating.
+
 This admission controller checks all requests on namespaced resources other than `Namespace` itself.
 If the namespace referenced from a request doesn't exist, the request is rejected.
 
 ### NamespaceLifecycle {#namespacelifecycle}
 
+**Type**: Validating.
+
 This admission controller enforces that a `Namespace` that is undergoing termination cannot have
 new objects created in it, and ensures that requests in a non-existent `Namespace` are rejected.
 This admission controller also prevents deletion of three system reserved namespaces `default`,
@@ -511,6 +549,8 @@ running this admission controller.
 
 ### NodeRestriction {#noderestriction}
 
+**Type**: Validating.
+
 This admission controller limits the `Node` and `Pod` objects a kubelet can modify. In order to be limited by this admission controller,
 kubelets must use credentials in the `system:nodes` group, with a username in the form `system:node:<nodeName>`.
 Such kubelets will only be allowed to modify their own `Node` API object, and only modify `Pod` API objects that are bound to their node.
@@ -543,6 +583,8 @@ permissions required to operate correctly.
 
 ### OwnerReferencesPermissionEnforcement {#ownerreferencespermissionenforcement}
 
+**Type**: Validating.
+
 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.
 This admission controller also protects the access to `metadata.ownerReferences[x].blockOwnerDeletion`
@@ -553,6 +595,8 @@ subresource of the referenced *owner* can change it.
 
 {{< feature-state for_k8s_version="v1.24" state="stable" >}}
 
+**Type**: Validating.
+
 This admission controller implements additional validations for checking incoming
 `PersistentVolumeClaim` resize requests.
 
@@ -582,6 +626,8 @@ For more information about persistent volume claims, see [PersistentVolumeClaims
 
 {{< feature-state for_k8s_version="v1.13" state="deprecated" >}}
 
+**Type**: Mutating.
+
 This admission controller automatically attaches region or zone labels to PersistentVolumes
 as defined by the cloud provider (for example, Azure or GCP).
 It helps ensure the Pods and the PersistentVolumes mounted are in the same
@@ -597,6 +643,8 @@ This admission controller is disabled by default.
 
 {{< feature-state for_k8s_version="v1.5" state="alpha" >}}
 
+**Type**: Validating.
+
 This admission controller defaults and limits what node selectors may be used within a namespace
 by reading a namespace annotation and a global configuration.
 
@@ -663,6 +711,8 @@ admission plugin, which allows preventing pods from running on specifically tain
 
 {{< feature-state for_k8s_version="v1.25" state="stable" >}}
 
+**Type**: Validating.
+
 The PodSecurity admission controller checks new Pods before they are
 admitted, determines if it should be admitted based on the requested security context and the restrictions on permitted
 [Pod Security Standards](/docs/concepts/security/pod-security-standards/)
@@ -677,6 +727,8 @@ PodSecurity replaced an older admission controller named PodSecurityPolicy.
 
 {{< feature-state for_k8s_version="v1.7" state="alpha" >}}
 
+**Type**: Mutating and Validating.
+
 The PodTolerationRestriction admission controller verifies any conflict between tolerations of a
 pod and the tolerations of its namespace.
 It rejects the pod request if there is a conflict.
@@ -707,12 +759,16 @@ This admission controller is disabled by default.
 
 ### Priority {#priority}
 
+**Type**: Mutating and Validating.
+
 The priority admission controller uses the `priorityClassName` field and populates the integer
 value of the priority.
 If the priority class is not found, the Pod is rejected.
 
 ### ResourceQuota {#resourcequota}
 
+**Type**: Validating.
+
 This admission controller will observe the incoming request and ensure that it does not violate
 any of the constraints enumerated in the `ResourceQuota` object in a `Namespace`.  If you are
 using `ResourceQuota` objects in your Kubernetes deployment, you MUST use this admission
@@ -723,6 +779,8 @@ and the [example of Resource Quota](/docs/concepts/policy/resource-quotas/) for
 
 ### RuntimeClass {#runtimeclass}
 
+**Type**: Mutating and Validating.
+
 If you define a RuntimeClass with [Pod overhead](/docs/concepts/scheduling-eviction/pod-overhead/)
 configured, this admission controller checks incoming Pods.
 When enabled, this admission controller rejects any Pod create requests
@@ -736,6 +794,8 @@ for more information.
 
 ### SecurityContextDeny {#securitycontextdeny}
 
+**Type**: Validating.
+
 {{< feature-state for_k8s_version="v1.27" state="deprecated" >}}
 
 {{< caution >}}
@@ -777,6 +837,8 @@ article details the PodSecurityPolicy historical context and the birth of the
 
 ### ServiceAccount {#serviceaccount}
 
+**Type**: Mutating and Validating.
+
 This admission controller implements automation for
 [serviceAccounts](/docs/tasks/configure-pod-container/configure-service-account/).
 The Kubernetes project strongly recommends enabling this admission controller.
@@ -785,6 +847,8 @@ You should enable this admission controller if you intend to make any use of Kub
 
 ### StorageObjectInUseProtection
 
+**Type**: Mutating.
+
 The `StorageObjectInUseProtection` plugin adds the `kubernetes.io/pvc-protection` or `kubernetes.io/pv-protection`
 finalizers to newly created Persistent Volume Claims (PVCs) or Persistent Volumes (PV).
 In case a user deletes a PVC or PV the PVC or PV is not removed until the finalizer is removed
@@ -795,19 +859,25 @@ for more detailed information.
 
 ### TaintNodesByCondition {#taintnodesbycondition}
 
+**Type**: Mutating.
+
 This admission controller {{< glossary_tooltip text="taints" term_id="taint" >}} newly created
 Nodes as `NotReady` and `NoSchedule`. That tainting avoids a race condition that could cause Pods
 to be scheduled on new Nodes before their taints were updated to accurately reflect their reported
 conditions.
 
 ### ValidatingAdmissionPolicy {#validatingadmissionpolicy}
 
+**Type**: Validating.
+
 [This admission controller](/docs/reference/access-authn-authz/validating-admission-policy/) implements the CEL validation for incoming matched requests. 
 It is enabled when both feature gate `validatingadmissionpolicy` and `admissionregistration.k8s.io/v1alpha1` group/version are enabled.
 If any of the ValidatingAdmissionPolicy fails, the request fails.
 
 ### ValidatingAdmissionWebhook {#validatingadmissionwebhook}
 
+**Type**: Validating.
+
 This admission controller calls any validating webhooks which match the request. Matching
 webhooks are called in parallel; if any of them rejects the request, the request
 fails. This admission controller only runs in the validation phase; the webhooks it calls may not