Admission Webhooks Introduction

Kubernetes offers us a lot of options when it comes to customization; setting default values while creating Custom Resource Definitions, enforcing security policies by adding a custom sidecar and preventing users from deleting custom resource objects.

The Kubernetes controller includes predefined Admission Plugins by default. You may customize almost any Kubernetes object by combining ValidatingAdmissionWebhook and MutatingAdmissionWebhook.

Finally, we can limit the scope of the admission webhook using namespace label selectors. In this case, we can skip enforcement of validation steps on core namespaces.

Admission Webhook Flow

Includes 2 phases:

  • Mutating: the sequential calling of each matching Admission Webhook object
  • Validation: the parallel calling of each matching Admission Webhook object

Admission Review

An Admission Review object is sent by Kubernetes ApiServer to an Admission Webhook defined in a JSON file, which contains 2 segments:

  • Admission Request - an object generated by ApiServer that should not be modified during request processing
  • Admission Response - an object not provided by ApiServer which should be created by Webhook

The most important thing in creating the Response is to copy Request UUID into Response UUID. With all other fields we can proceed with defaults. Finally, the Response object should be injected into Review and returned as a JSON object by request.

If errors occur during request handling, an Admission Response with proper state should be returned. It helps in the debugging process and generates helpful messages for users. Otherwise, in the case of an error 500 the failurePolicy invokes a response.

Mutating Admission Webhook

Here we can set default values of the undefined fields, enforce any object change such as additional containers, selectors or imagePullSecrets.

More details about Mutating response preparation will be covered by the next article in this series.

An example configuration of a Mutating Webhook:

apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration
metadata:
  name: mutating-admission-webhook
webhooks:
- name: mutating.example.com
  failurePolicy: Fail
  rules:
  - apiGroups:
    - ""
    apiVersions:
    - v1
    operations:
    - CREATE
    - UPDATE
    resources:
    - pods
  clientConfig:
    service:
      path: /mutating
      namespace: kube-system
      name: mutating-admission-webhook-service
    caBundle: "Base64 encoded CA"
  namespaceSelector:
    matchLabels:
      enabled.mutating.example.com: "true"

Validation Admission Webhook

Now we can verify the object which is useful as a way to enforce security on the cluster. An example would be to prevent the use of storage-classes or to prevent to use of untrusted images.

An example configuration of a Validating Webhook:

apiVersion: admissionregistration.k8s.io/v1beta1
kind: ValidatingWebhookConfiguration
metadata:
  name: validation-admission-webhook
webhooks:
- name: validation.example.com
  failurePolicy: Fail
  rules:
  - apiGroups:
    - ""
    apiVersions:
    - v1
    operations:
    - CREATE
    - UPDATE
    resources:
    - pods
  clientConfig:
    service:
      path: /validation
      namespace: kube-system
      name: validation-admission-webhook-service
    caBundle: "Base64 encoded CA"
  namespaceSelector:
    matchLabels:
      enabled.validation.example.com: "true"

Summary

You just learned about Kubernetes Admission Webhooks. In the next article, we will cover implementation details.