Skip to content
Go framework to create Kubernetes mutating and validating webhooks
Go Makefile Shell Dockerfile
Branch: master
Clone or download
slok Update prometheus client library (#40)
Update prometheus client library
Latest commit 39d3338 Jun 29, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add codewoners to auto asign pull requests and issues Dec 6, 2018
docker Update to Kuberntes 1.12.9 May 28, 2019
docs Change docs domain to Mar 8, 2019
examples Add tracer mutators and validators to multiwebhook example Aug 2, 2018
hack/scripts Add integration tests Jun 3, 2019
logo Add logos Jul 7, 2018
mocks Add metrics recorder interface Jul 17, 2018
test Add integration tests Jun 3, 2019
.gitignore Replace dep with gomod Sep 25, 2018
.travis.yml Add integration tests Jun 3, 2019 Rename changelog Jun 2, 2019
LICENSE Add license Jun 30, 2018
Makefile Add integration tests Jun 3, 2019 Add integration tests Jun 3, 2019
go.mod Update prometheus client library Jun 29, 2019
go.sum Update prometheus client library Jun 29, 2019


kubewebhook Build Status Go Report Card GoDoc

Kubewebhook is a small Go framework to create external admission webhooks for Kubernetes.

With Kubewebhook you can make validating and mutating webhooks very fast and focusing mainly on the domain logic of the webhook itself.


  • Ready for mutating and validating webhook kinds.
  • Easy and testable API.
  • Simple, extensible and flexible.
  • Multiple webhooks on the same server.
  • Webhook metrics (RED) for Prometheus with Grafana dashboard included.
  • Webhook tracing with Opentracing.


Kubewebhook has been used in production for several months, and the results have been good.


Here is a simple example of mutating webhook that will add mutated=true and mutator=pod-annotate annotations.

func main() {
    logger := &log.Std{Debug: true}

    cfg := initFlags()

    // Create our mutator
    mt := mutatingwh.MutatorFunc(func(_ context.Context, obj metav1.Object) (bool, error) {
        pod, ok := obj.(*corev1.Pod)
        if !ok {
            // If not a pod just continue the mutation chain(if there is one) and don't do nothing.
            return false, nil

        // Mutate our object with the required annotations.
        if pod.Annotations == nil {
            pod.Annotations = make(map[string]string)
        pod.Annotations["mutated"] = "true"
        pod.Annotations["mutator"] = "pod-annotate"

        return false, nil

    wh, err := mutatingwh.NewStaticWebhook(mt, &corev1.Pod{}, logger)
    if err != nil {
        fmt.Fprintf(os.Stderr, "error creating webhook: %s", err)

    // Get the handler for our webhook.
    whHandler := whhttp.HandlerFor(wh)
    logger.Infof("Listening on :8080")
    err = http.ListenAndServeTLS(":8080", cfg.certFile, cfg.keyFile, whHandler)
    if err != nil {
        fmt.Fprintf(os.Stderr, "error serving webhook: %s", err)

You can get more examples in here

Compatibility matrix

Integration tests will run on different Kubernetes versions, so if these are passing is likely that HEAD supports those Kubernetes versions, these will be marked on the matrix as ✓?. Check the latest builds here

Kubernetes 1.10 Kubernetes 1.11 Kubernetes 1.12 Kubernetes 1.13 Kubernetes 1.14
kubewebhook 0.1 ? ? ?
kubewebhook 0.2 ? ? ?
kubewebhook 0.3 ? ? ? ?
kubewebhook HEAD ? ? ✓? ✓? ✓?


Integration tests

Tools required

  • mkcert (optional if you want to create new certificates).
  • kind (option1, to run the cluster).
  • k3s (option2, to run the cluster)
  • ssh (to expose our webhook to the internet).

(Optional) Certificates

Certificates are ready to be used on [/test/integration/certs]. This certificates are valid for * so, they should be valid for our exposed webhooks using serveo.

If you want to create new certificates execute this:

make create-integration-test-certs

Running the tests

The integration tests are on [/tests/integration], there are the certificates valid for where the tunnel will be exposing the webhooks.

Go integration tests require this env vars:

  • TEST_WEBHOOK_URL: The url where the apiserver should make the webhook requests.
  • TEST_LISTEN_PORT: The port where our webhook will be listening the requests.

There are 2 ways of bootstrapping the integration tests, one using kind and another using k3s.

To run the integration tests do:

make integration-test

This it will bootstrap a cluster with kind by default and a k3s cluster if K3S=true env var is set. A ssh tunnel in a random subdomain using the 1987 port, and finally use the precreated certificates (see previous step), after this will execute the tests, and do it's best effort to tear down the clusters (on k3s could be problems, so have a check on k3s processes).

Developing integration tests

To develop integration test is handy to run a k3s cluster and a serveo tunnel, then check out [/tests/integration/helper/config] and use this development settings on the integration tests.

You can’t perform that action at this time.