From fce6bfc32f8d26a4eed832b70c84e879d22bb466 Mon Sep 17 00:00:00 2001 From: Marek Skrobacki Date: Fri, 28 Jul 2023 10:56:07 +0100 Subject: [PATCH] admission controllers: document types Signed-off-by: Marek Skrobacki --- .../admission-controllers.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/content/en/docs/reference/access-authn-authz/admission-controllers.md b/content/en/docs/reference/access-authn-authz/admission-controllers.md index e5226d3ec4..73cf07b13c 100644 --- a/content/en/docs/reference/access-authn-authz/admission-controllers.md +++ b/content/en/docs/reference/access-authn-authz/admission-controllers.md @@ -121,12 +121,16 @@ the `admissionregistration.k8s.io/v1alpha1` API. 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. +**Type**: Validating. + ### AlwaysDeny {#alwaysdeny} {{< feature-state for_k8s_version="v1.13" state="deprecated" >}} Rejects all requests. AlwaysDeny is **deprecated** as it has no real meaning. +**Type**: Validating. + ### AlwaysPullImages {#alwayspullimages} This admission controller modifies every new Pod to force the image pull policy to `Always`. This is useful in a @@ -137,6 +141,8 @@ scheduled onto the right node), without any authorization check against the imag is enabled, images are always pulled prior to starting containers, which means valid credentials are required. +**Type**: Mutating and Validating. + ### CertificateApproval {#certificateapproval} This admission controller observes requests to approve CertificateSigningRequest resources and performs additional @@ -146,6 +152,8 @@ authorization checks to ensure the approving user has permission to **approve** See [Certificate Signing Requests](/docs/reference/access-authn-authz/certificate-signing-requests/) for more information on the permissions required to perform different actions on CertificateSigningRequest resources. +**Type**: Validating. + ### CertificateSigning {#certificatesigning} This admission controller observes updates to the `status.certificate` field of CertificateSigningRequest resources @@ -155,12 +163,16 @@ requests with the `spec.signerName` requested on the CertificateSigningRequest r See [Certificate Signing Requests](/docs/reference/access-authn-authz/certificate-signing-requests/) for more information on the permissions required to perform different actions on CertificateSigningRequest resources. +**Type**: Validating. + ### CertificateSubjectRestriction {#certificatesubjectrestriction} 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`. +**Type**: Validating. + ### DefaultIngressClass {#defaultingressclass} This admission controller observes creation of `Ingress` objects that do not request any specific @@ -177,6 +189,8 @@ updates; it acts only on creation. See the [Ingress](/docs/concepts/services-networking/ingress/) documentation for more about ingress classes and how to mark one as default. +**Type**: Mutating. + ### DefaultStorageClass {#defaultstorageclass} This admission controller observes creation of `PersistentVolumeClaim` objects that do not request any specific storage class @@ -192,6 +206,8 @@ This admission controller ignores any `PersistentVolumeClaim` updates; it acts o See [persistent volume](/docs/concepts/storage/persistent-volumes/) documentation about persistent volume claims and storage classes and how to mark a storage class as default. +**Type**: Mutating. + ### DefaultTolerationSeconds {#defaulttolerationseconds} This admission controller sets the default forgiveness toleration for pods to tolerate @@ -201,6 +217,8 @@ 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. +**Type**: Mutating. + ### DenyServiceExternalIPs This admission controller rejects all net-new usage of the `Service` field `externalIPs`. This @@ -216,6 +234,8 @@ of it. This admission controller is disabled by default. +**Type**: Validating. + ### EventRateLimit {#eventratelimit} {{< feature-state for_k8s_version="v1.13" state="alpha" >}} @@ -264,6 +284,8 @@ for more details. This admission controller is disabled by default. +**Type**: Validating. + ### ExtendedResourceToleration {#extendedresourcetoleration} This plug-in facilitates creation of dedicated nodes with extended resources. @@ -275,12 +297,16 @@ add these tolerations. This admission controller is disabled by default. +**Type**: Mutating. + ### ImagePolicyWebhook {#imagepolicywebhook} The ImagePolicyWebhook admission controller allows a backend webhook to make admission decisions. This admission controller is disabled by default. +**Type**: Validating. + #### Configuration file format {#imagereview-config-file-format} ImagePolicyWebhook uses a configuration file to set options for the behavior of the backend. @@ -444,6 +470,8 @@ This admission controller denies any pod that defines `AntiAffinity` topology ke This admission controller is disabled by default. +**Type**: Validating. + ### LimitRanger {#limitranger} This admission controller will observe the incoming request and ensure that it does not violate @@ -457,6 +485,8 @@ See the [LimitRange API reference](/docs/reference/kubernetes-api/policy-resourc and the [example of LimitRange](/docs/tasks/administer-cluster/manage-resources/memory-default-namespace/) for more details. +**Type**: Mutating and Validating. + ### MutatingAdmissionWebhook {#mutatingadmissionwebhook} This admission controller calls any mutating webhooks which match the request. Matching @@ -472,6 +502,8 @@ If you disable the MutatingAdmissionWebhook, you must also disable the `MutatingWebhookConfiguration` object in the `admissionregistration.k8s.io/v1` group/version via the `--runtime-config` flag, both are on by default. +**Type**: Mutating. + #### Use caution when authoring and installing mutating webhooks * Users may be confused when the objects they try to create are different from @@ -493,11 +525,15 @@ It creates a namespace if it cannot be found. This admission controller is useful in deployments that do not want to restrict creation of a namespace prior to its usage. +**Type**: Mutating. + ### NamespaceExists {#namespaceexists} 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. +**Type**: Validating. + ### NamespaceLifecycle {#namespacelifecycle} This admission controller enforces that a `Namespace` that is undergoing termination cannot have @@ -509,6 +545,8 @@ A `Namespace` deletion kicks off a sequence of operations that remove all object etc.) in that namespace. In order to enforce integrity of that process, we strongly recommend running this admission controller. +**Type**: Validating. + ### NodeRestriction {#noderestriction} This admission controller limits the `Node` and `Pod` objects a kubelet can modify. In order to be limited by this admission controller, @@ -541,6 +579,8 @@ and may be disallowed or allowed by the `NodeRestriction` admission plugin in th Future versions may add additional restrictions to ensure kubelets have the minimal set of permissions required to operate correctly. +**Type**: Validating. + ### OwnerReferencesPermissionEnforcement {#ownerreferencespermissionenforcement} This admission controller protects the access to the `metadata.ownerReferences` of an object @@ -549,6 +589,8 @@ This admission controller also protects the access to `metadata.ownerReferences[ of an object, so that only users with **update** permission to the `finalizers` subresource of the referenced *owner* can change it. +**Type**: Validating. + ### PersistentVolumeClaimResize {#persistentvolumeclaimresize} {{< feature-state for_k8s_version="v1.24" state="stable" >}} @@ -578,6 +620,8 @@ allowVolumeExpansion: true For more information about persistent volume claims, see [PersistentVolumeClaims](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims). +**Type**: Validating. + ### PersistentVolumeLabel {#persistentvolumelabel} {{< feature-state for_k8s_version="v1.13" state="deprecated" >}} @@ -593,6 +637,8 @@ the {{< glossary_tooltip text="cloud-controller-manager" term_id="cloud-controll This admission controller is disabled by default. +**Type**: Mutating. + ### PodNodeSelector {#podnodeselector} {{< feature-state for_k8s_version="v1.5" state="alpha" >}} @@ -602,6 +648,8 @@ by reading a namespace annotation and a global configuration. This admission controller is disabled by default. +**Type**: Validating. + #### Configuration file format `PodNodeSelector` uses a configuration file to set options for the behavior of the backend. @@ -673,6 +721,8 @@ documentation for more information. PodSecurity replaced an older admission controller named PodSecurityPolicy. +**Type**: Validating. + ### PodTolerationRestriction {#podtolerationrestriction} {{< feature-state for_k8s_version="v1.7" state="alpha" >}} @@ -705,12 +755,16 @@ metadata: This admission controller is disabled by default. +**Type**: Mutating and Validating. + ### Priority {#priority} 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. +**Type**: Mutating and Validating. + ### ResourceQuota {#resourcequota} This admission controller will observe the incoming request and ensure that it does not violate @@ -721,6 +775,8 @@ controller to enforce quota constraints. See the [ResourceQuota API reference](/docs/reference/kubernetes-api/policy-resources/resource-quota-v1/) and the [example of Resource Quota](/docs/concepts/policy/resource-quotas/) for more details. +**Type**: Validating. + ### RuntimeClass {#runtimeclass} If you define a RuntimeClass with [Pod overhead](/docs/concepts/scheduling-eviction/pod-overhead/) @@ -734,6 +790,8 @@ defined in the corresponding RuntimeClass. See also [Pod Overhead](/docs/concepts/scheduling-eviction/pod-overhead/) for more information. +**Type**: Mutating and Validating. + ### SecurityContextDeny {#securitycontextdeny} {{< feature-state for_k8s_version="v1.27" state="deprecated" >}} @@ -775,6 +833,8 @@ from the Kubernetes blog article about PodSecurityPolicy and its removal. The article details the PodSecurityPolicy historical context and the birth of the `securityContext` field for Pods. +**Type**: Validating. + ### ServiceAccount {#serviceaccount} This admission controller implements automation for @@ -783,6 +843,8 @@ 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. +**Type**: Mutating and Validating. + ### StorageObjectInUseProtection The `StorageObjectInUseProtection` plugin adds the `kubernetes.io/pvc-protection` or `kubernetes.io/pv-protection` @@ -793,6 +855,8 @@ Refer to the [Storage Object in Use Protection](/docs/concepts/storage/persistent-volumes/#storage-object-in-use-protection) for more detailed information. +**Type**: Mutating. + ### TaintNodesByCondition {#taintnodesbycondition} This admission controller {{< glossary_tooltip text="taints" term_id="taint" >}} newly created @@ -800,12 +864,16 @@ Nodes as `NotReady` and `NoSchedule`. That tainting avoids a race condition that to be scheduled on new Nodes before their taints were updated to accurately reflect their reported conditions. +**Type**: Mutating. + ### ValidatingAdmissionPolicy {#validatingadmissionpolicy} [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. +**Type**: Validating. + ### ValidatingAdmissionWebhook {#validatingadmissionwebhook} This admission controller calls any validating webhooks which match the request. Matching @@ -821,6 +889,8 @@ If you disable the ValidatingAdmissionWebhook, you must also disable the `ValidatingWebhookConfiguration` object in the `admissionregistration.k8s.io/v1` group/version via the `--runtime-config` flag. +**Type**: Validating. + ## Is there a recommended set of admission controllers to use? Yes. The recommended admission controllers are enabled by default