About admission plug-ins

Admission plug-ins are used to help regulate how OpenShift Container Platform 4.10 functions. Admission plug-ins intercept requests to the master API to validate resource requests and ensure policies are adhered to, after the request is authenticated and authorized. For example, they are commonly used to enforce security policy, resource limitations or configuration requirements.

Admission plug-ins run in sequence as an admission chain. If any admission plug-in in the sequence rejects a request, the whole chain is aborted and an error is returned.

OpenShift Container Platform has a default set of admission plug-ins enabled for each resource type. These are required for proper functioning of the cluster. Admission plug-ins ignore resources that they are not responsible for.

In addition to the defaults, the admission chain can be extended dynamically through webhook admission plug-ins that call out to custom webhook servers. There are two types of webhook admission plug-ins: a mutating admission plug-in and a validating admission plug-in. The mutating admission plug-in runs first and can both modify resources and validate requests. The validating admission plug-in validates requests and runs after the mutating admission plug-in so that modifications triggered by the mutating admission plug-in can also be validated.

Calling webhook servers through a mutating admission plug-in can produce side effects on resources related to the target object. In such situations, you must take steps to validate that the end result is as expected.

Dynamic admission should be used cautiously because it impacts cluster control plane operations. When calling webhook servers through webhook admission plug-ins in OpenShift Container Platform 4.10, ensure that you have read the documentation fully and tested for side effects of mutations. Include steps to restore resources back to their original state prior to mutation, in the event that a request does not pass through the entire admission chain.

Default admission plug-ins

Default validating and admission plug-ins are enabled in OpenShift Container Platform 4.10. These default plug-ins contribute to fundamental control plane functionality, such as ingress policy, cluster resource limit override and quota policy. The following lists contain the default admission plug-ins:

Validating admission plug-ins
  • LimitRanger

  • ServiceAccount

  • PodNodeSelector

  • Priority

  • PodTolerationRestriction

  • OwnerReferencesPermissionEnforcement

  • PersistentVolumeClaimResize

  • RuntimeClass

  • CertificateApproval

  • CertificateSigning

  • CertificateSubjectRestriction

  • autoscaling.openshift.io/ManagementCPUsOverride

  • authorization.openshift.io/RestrictSubjectBindings

  • scheduling.openshift.io/OriginPodNodeEnvironment

  • network.openshift.io/ExternalIPRanger

  • network.openshift.io/RestrictedEndpointsAdmission

  • image.openshift.io/ImagePolicy

  • security.openshift.io/SecurityContextConstraint

  • security.openshift.io/SCCExecRestrictions

  • route.openshift.io/IngressAdmission

  • config.openshift.io/ValidateAPIServer

  • config.openshift.io/ValidateAuthentication

  • config.openshift.io/ValidateFeatureGate

  • config.openshift.io/ValidateConsole

  • operator.openshift.io/ValidateDNS

  • config.openshift.io/ValidateImage

  • config.openshift.io/ValidateOAuth

  • config.openshift.io/ValidateProject

  • config.openshift.io/DenyDeleteClusterConfiguration

  • config.openshift.io/ValidateScheduler

  • quota.openshift.io/ValidateClusterResourceQuota

  • security.openshift.io/ValidateSecurityContextConstraints

  • authorization.openshift.io/ValidateRoleBindingRestriction

  • config.openshift.io/ValidateNetwork

  • operator.openshift.io/ValidateKubeControllerManager

  • ValidatingAdmissionWebhook

  • ResourceQuota

  • quota.openshift.io/ClusterResourceQuota

Mutating admission plug-ins
  • NamespaceLifecycle

  • LimitRanger

  • ServiceAccount

  • NodeRestriction

  • TaintNodesByCondition

  • PodNodeSelector

  • Priority

  • DefaultTolerationSeconds

  • PodTolerationRestriction

  • PersistentVolumeLabel

  • DefaultStorageClass

  • StorageObjectInUseProtection

  • RuntimeClass

  • DefaultIngressClass

  • autoscaling.openshift.io/ManagementCPUsOverride

  • scheduling.openshift.io/OriginPodNodeEnvironment

  • image.openshift.io/ImagePolicy

  • security.openshift.io/SecurityContextConstraint

  • security.openshift.io/DefaultSecurityContextConstraints

  • MutatingAdmissionWebhook

Webhook admission plug-ins

In addition to OpenShift Container Platform default admission plug-ins, dynamic admission can be implemented through webhook admission plug-ins that call webhook servers, to extend the functionality of the admission chain. Webhook servers are called over HTTP at defined endpoints.

There are two types of webhook admission plug-ins in OpenShift Container Platform:

  • During the admission process, the mutating admission plug-in can perform tasks, such as injecting affinity labels.

  • At the end of the admission process, the validating admission plug-in can be used to make sure an object is configured properly, for example ensuring affinity labels are as expected. If the validation passes, OpenShift Container Platform schedules the object as configured.

When an API request comes in, mutating or validating admission plug-ins use the list of external webhooks in the configuration and call them in parallel:

  • If all of the webhooks approve the request, the admission chain continues.

  • If any of the webhooks deny the request, the admission request is denied and the reason for doing so is based on the first denial.

  • If more than one webhook denies the admission request, only the first denial reason is returned to the user.

  • If an error is encountered when calling a webhook, the request is either denied or the webhook is ignored depending on the error policy set. If the error policy is set to Ignore, the request is unconditionally accepted in the event of a failure. If the policy is set to Fail, failed requests are denied. Using Ignore can result in unpredictable behavior for all clients.

Communication between the webhook admission plug-in and the webhook server must use TLS. Generate a CA certificate and use the certificate to sign the server certificate that is used by your webhook admission server. The PEM-encoded CA certificate is supplied to the webhook admission plug-in using a mechanism, such as service serving certificate secrets.

The following diagram illustrates the sequential admission chain process within which multiple webhook servers are called.

API admission stage
Figure 1. API admission chain with mutating and validating admission plug-ins

An example webhook admission plug-in use case is where all pods must have a common set of labels. In this example, the mutating admission plug-in can inject labels and the validating admission plug-in can check that labels are as expected. OpenShift Container Platform would subsequently schedule pods that include required labels and reject those that do not.

Some common webhook admission plug-in use cases include:

  • Namespace reservation.

  • Limiting custom network resources managed by the SR-IOV network device plug-in.

  • Defining tolerations that enable taints to qualify which pods should be scheduled on a node.

  • Pod priority class validation.

Types of webhook admission plug-ins

Cluster administrators can call out to webhook servers through the mutating admission plug-in or the validating admission plug-in in the API server admission chain.

Mutating admission plug-in

The mutating admission plug-in is invoked during the mutation phase of the admission process, which allows modification of resource content before it is persisted. One example webhook that can be called through the mutating admission plug-in is the Pod Node Selector feature, which uses an annotation on a namespace to find a label selector and add it to the pod specification.

Sample mutating admission plug-in configuration
apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration (1)
  name: <webhook_name> (2)
- name: <webhook_name> (3)
  clientConfig: (4)
      namespace: default (5)
      name: kubernetes (6)
      path: <webhook_url> (7)
    caBundle: <ca_signing_certificate> (8)
  rules: (9)
  - operations: (10)
    - <operation>
    - ""