From f900debc6305f6078997301bf61421a8b347ba0b Mon Sep 17 00:00:00 2001 From: Marek Skrobacki Date: Fri, 28 Jul 2023 18:01:15 +0100 Subject: [PATCH] admission controllers: put type information at top of section Signed-off-by: Marek Skrobacki --- .../admission-controllers.md | 140 +++++++++--------- 1 file changed, 70 insertions(+), 70 deletions(-) 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 73cf07b13c..7279339f59 100644 --- a/content/en/docs/reference/access-authn-authz/admission-controllers.md +++ b/content/en/docs/reference/access-authn-authz/admission-controllers.md @@ -118,21 +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. -**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. +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 @@ -141,10 +143,10 @@ 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} +**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. @@ -152,10 +154,10 @@ 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} +**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. @@ -163,18 +165,18 @@ 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} +**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`. -**Type**: Validating. - ### 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 @@ -189,10 +191,10 @@ 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} +**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 @@ -206,10 +208,10 @@ 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} +**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 @@ -217,10 +219,10 @@ 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 +**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 @@ -234,12 +236,12 @@ of it. This admission controller is disabled by default. -**Type**: Validating. - ### EventRateLimit {#eventratelimit} {{< 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: @@ -284,10 +286,10 @@ for more details. This admission controller is disabled by default. -**Type**: Validating. - ### 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 @@ -297,16 +299,14 @@ add these tolerations. This admission controller is disabled by default. -**Type**: Mutating. - ### ImagePolicyWebhook {#imagepolicywebhook} +**Type**: Validating. + 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. @@ -465,15 +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. -**Type**: Validating. - ### 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 @@ -485,10 +487,10 @@ 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} +**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. @@ -502,8 +504,6 @@ 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 @@ -519,23 +519,25 @@ 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. 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} +**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. -**Type**: Validating. - ### 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`, @@ -545,10 +547,10 @@ 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} +**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:`. 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. @@ -579,22 +581,22 @@ 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} +**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` 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" >}} +**Type**: Validating. + This admission controller implements additional validations for checking incoming `PersistentVolumeClaim` resize requests. @@ -620,12 +622,12 @@ 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" >}} +**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 @@ -637,19 +639,17 @@ 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" >}} +**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. 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. @@ -711,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/) @@ -721,12 +723,12 @@ 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" >}} +**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. @@ -755,18 +757,18 @@ metadata: This admission controller is disabled by default. -**Type**: Mutating and Validating. - ### 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. -**Type**: Mutating and Validating. - ### 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 @@ -775,10 +777,10 @@ 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} +**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 @@ -790,10 +792,10 @@ defined in the corresponding RuntimeClass. See also [Pod Overhead](/docs/concepts/scheduling-eviction/pod-overhead/) for more information. -**Type**: Mutating and Validating. - ### SecurityContextDeny {#securitycontextdeny} +**Type**: Validating. + {{< feature-state for_k8s_version="v1.27" state="deprecated" >}} {{< caution >}} @@ -833,20 +835,20 @@ 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} +**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. You should enable this admission controller if you intend to make any use of Kubernetes `ServiceAccount` objects. -**Type**: Mutating and Validating. - ### 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 @@ -855,27 +857,27 @@ 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} +**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. -**Type**: Mutating. - ### 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. -**Type**: Validating. - ### 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 @@ -889,8 +891,6 @@ 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