Admission Webhooks

An in-depth walkthough of admission webhooks.

Create a validating or mutating Admission Webhook

Admission webhooks are HTTP callbacks that receive admission requests and do something with them. It is registered with Kubernetes, and will be called by Kubernetes to validate or mutate a resource before being stored. There are two types of admission webhooks.

1. Validating admission webhook

Validating webhooks can be used to perform validations that go beyond the capabilities of OpenAPI schema validation, such as ensuring a field is immutable after creation or higher level permissions checks based on the user that is making the request to the API server. It can reject the request, but it cannot modify the object that they are receiving in the request.

2. Mutating admission webhook

Mutating webhooks are most frequently used for defaulting, by adding default values for unset fields in the resource on creation. They can modify objects by creating a patch that will be sent back in the admission response.

For more background on Admission webhooks, refer to the Kubebuilder documentation or the official Kubernetes documentation. You can also refer to the Kubebuilder webhook walkthrough, which is similar in content to this guide.

Create Validation Webhook

As an example, let’s walk through the scaffolding of a validation webhook for the sample memcached operator.

  1. $ operator-sdk create webhook --group cache --version v1alpha1 --kind Memcached --defaulting --programmatic-validation

After, create webhook command, the following message will appear on the terminal. It scaffolds out api/<version>/<kind>_webhook.go file. In this example, it would be api/v1alpha1/memcached_webhook.go.

  1. Writing kustomize manifests for you to edit...
  2. Writing scaffold for you to edit...
  3. api/v1alpha1/memcached_webhook.go

The --defaulting flag will scaffold the resources required for a mutating webhook, and the --programmatic-validation flag will scaffold the resources required for a validating webhook. In this case we have scaffolded both.

After running the create webhook command the file structure would be:

  1. ├── Dockerfile
  2. ├── Makefile
  3. ├── PROJECT
  4. ├── api
  5. │   └── v1alpha1
  6. │       ├── memcached_webhook.go
  7. │       ├── webhook_suite_test.go
  8. ├── config
  9. │   ├── certmanager
  10. │   │   ├── certificate.yaml
  11. │   │   ├── kustomization.yaml
  12. │   │   └── kustomizeconfig.yaml
  13. │   ├── default
  14. │   │   ├── manager_webhook_patch.yaml
  15. │   │   └── webhookcainjection_patch.yaml
  16. │   └── webhook
  17. │       ├── kustomization.yaml
  18. │       ├── kustomizeconfig.yaml
  19. │       └── service.yaml
  20. ├── go.mod
  21. ├── go.sum
  22. └── main.go

The scaffolded file api/v1alpha1/memcached_webhook.go has method signatures which need to be implemented for the validation webhook.

Following this, there are a few steps which need to be done in your operator project to enable webhooks. This will involve:

  1. Implementing the required methods for Validating or Mutating webhook in <kind>_webhook.go. An example of such implementation is provided here.

  2. Uncommenting sections in config/default/kustomization.yaml to enable webhook and cert-manager configuration through kustomize. Cert-manager (or any third party solution) can be used to provision certificates for webhook server. This is explained in detail here.

Generate webhook manifests and enable webhook deployment

Once your webhooks are implemented, all that’s left is to create the WebhookConfiguration manifests required to register your webhooks with Kubernetes:

  1. $ make manifests

Run your operator and webhooks

There are two ways to test your operator project with webhooks.

Run locally

Technically, the webhooks can be run locally, but for it to work you need to generate certificates for the webhook server and store them at /tmp/k8s-webhook-server/serving-certs/tls.{crt,key}. For more details about running webhook locally, refer here.

Run as a Deployment inside the cluster

Adding webhooks does not alter deploying your operator. For instructions on deploying your operator into a cluster, refer to the tutorial.

Last modified August 31, 2021: Update webhook.md (#5174) (1979f73f)