kubewebhook

module
Version: v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 21, 2020 License: Apache-2.0

README

kubewebhook

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.

Features

  • Ready for mutating and validating webhook kinds (compatible with CRDs).
  • 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.
  • Type specific (static) webhooks and multitype (dynamic) webhooks.

Status

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

Example

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()

    // Mutator.
    mt := mutatingwh.MutatorFunc(func(_ context.Context, obj metav1.Object) (bool, error) {
        pod, ok := obj.(*corev1.Pod)
        if !ok {
            return false, nil
        }

        if pod.Annotations == nil {
            pod.Annotations = make(map[string]string)
        }
        pod.Annotations["mutated"] = "true"
        pod.Annotations["mutator"] = "pod-annotate"

        return false, nil
    })

    mcfg := mutatingwh.WebhookConfig{
        Name: "podAnnotate",
        Obj:  &corev1.Pod{},
    }
    wh, err := mutatingwh.NewWebhook(mcfg, mt, nil, nil, logger)
    if err != nil {
        fmt.Fprintf(os.Stderr, "error creating webhook: %s", err)
        os.Exit(1)
    }

    // 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)
        os.Exit(1)
    }
}

You can get more examples in here

Production ready example

This repository is a production ready webhook app: https://github.com/slok/k8s-webhook-example

It shows, different webhook use cases, app structure, testing domain logic, kubewebhook use case, how to deploy...

Static and dynamic webhooks

We have 2 kinds of webhooks:

  • Static: Common one, is a single resource type webhook.
  • Dynamic: Used when the same webhook act on multiple types, unknown types and/or is used for generic stuff (e.g labels).
    • To use this kind of webhook, don't set the type on the configuration or set to nil.
    • If a request for an unknown type is not known by the webhook libraries, it will fallback to runtime.Unstructured object type.
    • Very useful to manipulate multiple resources on the same webhook (e.g Deployments, Statfulsets).
    • CRDs are unknown types so they will fallback to runtime.Unstructured`.
    • If using CRDs, better use Static webhooks.
    • Very useful to maniputale any metadata based validation or mutations (e.g Labels, annotations...)

Compatibility matrix

Depending on your Kubernetes cluster version, you should select the Kubewebhook version.

This Matrix ensures that Kubernetes libs are used with the described versions and the integration tests have been tested against this Kubernetes cluster versions, this doesn't mean that other Kubewebhook versions different to the matched ones to Kubernetes versions don't work (e.g k8s v1.15 with Kubewebhook v0.3). You can try it and check if they work for you.

k8s version Kubewebhook version Supported admission reviews Support dynamic webhooks
1.19 v0.11 v1beta1
1.18 v0.10 v1beta1
1.18 v0.9 v1beta1
1.17 v0.8 v1beta1
1.16 v0.7 v1beta1
1.15 v0.6 v1beta1
1.14 v0.5 v1beta1
1.13 v0.4 v1beta1
1.12 v0.3 v1beta1
1.11 v0.2 v1beta1
1.10 v0.2 v1beta1

Documentation

Integration tests

Tools required

  • mkcert (optional if you want to create new certificates).
  • kind (option1, 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 ngrok tcp tunnels so, they should be valid for our exposed webhooks using ngrok.

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 ngrok 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.

Kind is what is used to bootstrap the integration tests.

To run the integration tests do:

make integration-test

This it will bootstrap a cluster with kind by default. A ssh tunnel in a random address, 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.

Developing integration tests

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

Directories

Path Synopsis
examples
Package mocks will have all the mocks of the library, we'll try to use mocking using blackbox testing and integration tests whenever is possible.
Package mocks will have all the mocks of the library, we'll try to use mocking using blackbox testing and integration tests whenever is possible.
observability/metrics
Code generated by mockery v1.0.0
Code generated by mockery v1.0.0
webhook
Code generated by mockery v1.0.0
Code generated by mockery v1.0.0
webhook/mutating
Code generated by mockery v1.0.0
Code generated by mockery v1.0.0
webhook/validating
Code generated by mockery v1.0.0
Code generated by mockery v1.0.0
pkg
log
test
integration/crd/apis/building/v1
Package v1 is the v1 version of the API.
Package v1 is the v1 version of the API.
integration/crd/client/clientset/versioned
This package has the automatically generated clientset.
This package has the automatically generated clientset.
integration/crd/client/clientset/versioned/fake
This package has the automatically generated fake clientset.
This package has the automatically generated fake clientset.
integration/crd/client/clientset/versioned/scheme
This package contains the scheme of the automatically generated clientset.
This package contains the scheme of the automatically generated clientset.
integration/crd/client/clientset/versioned/typed/building/v1
This package has the automatically generated typed clients.
This package has the automatically generated typed clients.
integration/crd/client/clientset/versioned/typed/building/v1/fake
Package fake has the automatically generated clients.
Package fake has the automatically generated clients.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL