OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Admission plugins

About admission plugins

Admission plugins intercept requests to the master API to validate resource requests. After a request is authenticated and authorized, the admission plugins ensure that any associated policies are followed. For example, they are commonly used to enforce security policy, resource limitations or configuration requirements.

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

OpenShift Dedicated has a default set of admission plugins enabled for each resource type. These are required for proper functioning of the cluster. Admission plugins ignore resources that they are not responsible for.

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

Calling webhook servers through a mutating admission plugin 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 plugins in OpenShift Dedicated , 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 plugins

Default validating and admission plugins are enabled in OpenShift Dedicated . These default plugins contribute to fundamental control plane functionality, such as ingress policy, cluster resource limit override and quota policy.

Do not run workloads in or share access to default projects. Default projects are reserved for running core cluster components.

The following default projects are considered highly privileged: default, kube-public, kube-system, openshift, openshift-infra, openshift-node, and other system-created projects that have the openshift.io/run-level label set to 0 or 1. Functionality that relies on admission plugins, such as pod security admission, security context constraints, cluster resource quotas, and image reference resolution, does not work in highly privileged projects.

The following lists contain the default admission plugins:

Validating admission plugins

  • 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 plugins

  • NamespaceLifecycle

  • LimitRanger

  • ServiceAccount

  • NodeRestriction

  • TaintNodesByCondition

  • PodNodeSelector

  • Priority

  • DefaultTolerationSeconds

  • PodTolerationRestriction

  • 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 plugins

In addition to OpenShift Dedicated default admission plugins, dynamic admission can be implemented through webhook admission plugins 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 plugins in OpenShift Dedicated:

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

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

When an API request comes in, mutating or validating admission plugins 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.

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 plugins

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

Some common webhook admission plugin use cases include:

  • Namespace reservation.

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

  • Pod priority class validation.

The maximum default webhook timeout value in OpenShift Dedicated is 13 seconds, and it cannot be changed.

Types of webhook admission plugins

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

Mutating admission plugin

The mutating admission plugin 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 plugin 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 plugin configuration
apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration (1)
metadata:
  name: <webhook_name> (2)
webhooks:
- name: <webhook_name> (3)
  clientConfig: (4)
    service:
      namespace: default (5)
      name: kubernetes (6)
      path: <webhook_url> (7)
    caBundle: <ca_signing_certificate> (8)
  rules: (9)
  - operations: (10)
    - <operation>
    apiGroups:
    - ""
    apiVersions:
    - "*"
    resources:
    - <resource>
  failurePolicy: <policy> (11)
  sideEffects: None
1 Specifies a mutating admission plugin configuration.
2 The name for the MutatingWebhookConfiguration object. Replace <webhook_name> with the appropriate value.
3 The name of the webhook to call. Replace <webhook_name> with the appropriate value.
4 Information about how to connect to, trust, and send data to the webhook server.
5 The namespace where the front-end service is created.
6 The name of the front-end service.
7 The webhook URL used for admission requests. Replace <webhook_url> with the appropriate value.
8 A PEM-encoded CA certificate that signs the server certificate that is used by the webhook server. Replace <ca_signing_certificate> with the appropriate certificate in base64 format.
9 Rules that define when the API server should use this webhook admission plugin.
10 One or more operations that trigger the API server to call this webhook admission plugin. Possible values are create, update, delete or connect. Replace <operation> and <resource> with the appropriate values.
11 Specifies how the policy should proceed if the webhook server is unavailable. Replace <policy> with either Ignore (to unconditionally accept the request in the event of a failure) or Fail (to deny the failed request). Using Ignore can result in unpredictable behavior for all clients.

In OpenShift Dedicated , objects created by users or control loops through a mutating admission plugin might return unexpected results, especially if values set in an initial request are overwritten, which is not recommended.

Validating admission plugin

A validating admission plugin is invoked during the validation phase of the admission process. This phase allows the enforcement of invariants on particular API resources to ensure that the resource does not change again. The Pod Node Selector is also an example of a webhook which is called by the validating admission plugin, to ensure that all nodeSelector fields are constrained by the node selector restrictions on the namespace.

Sample validating admission plugin configuration
apiVersion: admissionregistration.k8s.io/v1beta1
kind: ValidatingWebhookConfiguration (1)
metadata:
  name: <webhook_name> (2)
webhooks:
- name: <webhook_name> (3)
  clientConfig: (4)
    service:
      namespace: default  (5)
      name: kubernetes (6)
      path: <webhook_url> (7)
    caBundle: <ca_signing_certificate> (8)
  rules: (9)
  - operations: (10)
    - <operation>
    apiGroups:
    - ""
    apiVersions:
    - "*"
    resources:
    - <resource>
  failurePolicy: <policy> (11)
  sideEffects: Unknown
1 Specifies a validating admission plugin configuration.
2 The name for the ValidatingWebhookConfiguration object. Replace <webhook_name> with the appropriate value.
3 The name of the webhook to call. Replace <webhook_name> with the appropriate value.
4 Information about how to connect to, trust, and send data to the webhook server.
5 The namespace where the front-end service is created.
6 The name of the front-end service.
7 The webhook URL used for admission requests. Replace <webhook_url> with the appropriate value.
8 A PEM-encoded CA certificate that signs the server certificate that is used by the webhook server. Replace <ca_signing_certificate> with the appropriate certificate in base64 format.
9 Rules that define when the API server should use this webhook admission plugin.
10 One or more operations that trigger the API server to call this webhook admission plugin. Possible values are create, update, delete or connect. Replace <operation> and <resource> with the appropriate values.
11 Specifies how the policy should proceed if the webhook server is unavailable. Replace <policy> with either Ignore (to unconditionally accept the request in the event of a failure) or Fail (to deny the failed request). Using Ignore can result in unpredictable behavior for all clients.

Additional resources