Kubernetes Webhooks in Haskell and Dhall

2020-02-09T00:00:00+00:00

I spent the past few weeks fighting with Kubernetes Admission Controllers</a> (also known as Mutating/Validating Webhooks).

Admission controllers are a quite powerful tool, that allow intercepting requests to the Kubernetes API Server before an object is persisted, and perform custom validations or mutations on it.

There are two main components to an admission controller:

A webhook exposed over HTTPS which accepts an AdmissionReviewRequest</code> and returns an AdmissionReviewResponse</code></li>

A configuration entry of type MutatingWebhookConfiguration</code> or ValidatingWebhookConfiguration</code></li> </ol>In this post, I will present the kubernetes-webhook-haskell</a> library, which is used to create the webhook, and a dhall</code> template that helps with the configuration and tls certificates. Many tutorials I found online show how to do this with a bash script, here we take a more declarative approach using cert-manager</a>. How to write a Kubernetes Webhook in Haskell#</a> </h2> This is a step by step explanation on how to write a webhook in Haskell. If you are familiar with Haskell, and servant, you can skip this section and look at the example</a> instead. First of all, set up a project using your favorite build tool, adding kubernetes-webhook-haskell</code> as a dependency. Second, you need to create an endpoint where you will be receiving the requests. In servant</code>, this looks like: type API = -- /mutate "mutate" :> ReqBody '[JSON] AdmissionReviewRequest :> Post '[JSON] AdmissionReviewResponse </code></pre> Third, you need to set up the server so that it runs on https (kubernetes only allows https for webhooks), with warp-tls</code> you can do something like: main :: IO () main = do let tlsOpts = tlsSettings "/certs/tls.crt" "/certs/tls.key" warpOpts = setPort 8080 defaultSettings runTLS tlsOpts warpOpts app </code></pre> If you will be using the template provided in the section below, we will load the certificates there. Fourth, you can write the webhook logic. Depending on whether you are writing a validating or a mutating webhook, the library exposes two different functions: mutatingWebhook</code> and validatingWebhook</code>. The logic is similar for both, you parse a request, write a handler for it returning either an error (of type Status</code>) or a Allowed</code>/Patch</code> (see http://jsonpatch.com/ for information on how to write the patch). For example, if you want to write a mutating webhook that adds a toleration to your pods, you should define the Toleration type: data Toleration = Toleration { effect :: Maybe TolerationEffect, key :: Maybe Text, operator :: Maybe TolerationOperator, tolerationSeconds :: Maybe Integer, value :: Maybe Text } deriving (Generic, A.ToJSON) data TolerationEffect = NoSchedule | PreferNoSchedule | NoExecute deriving (Generic, A.ToJSON) data TolerationOperator = Exists | Equal deriving (Generic, A.ToJSON) </code></pre> and then your patch can look like: patch :: W.Patch patch = W.Patch [ W.PatchOperation { op = W.Add, path = "/spec/tolerations/-", from = Nothing, value = Just $ A.toJSON toleration } ] where toleration = Toleration { effect = Just NoSchedule, key = Just "foo", operator = Just Equal, tolerationSeconds = Nothing, value = Nothing } </code></pre> Then your patch in the mutatingWebhook</code>: mutate :: AdmissionReviewRequest -> AdmissionReviewResponse mutate = mutatingWebhook req (\_ -> Right patch) </code></pre> And that's it! Compile and create a docker image, and jump to the next section. How to deploy the Kubernetes Webhook using Dhall#</a> </h2> Regardless of the fact that you created the webhook with the library above or not, this part explains how to deploy a webhook to Kubernetes by using an opinionated Dhall template. Dhall is a configuration language aimed at writing maintainable configuration files. It's a great language to write infrastructure configuration in, with features such as: (safe) imports</li> functions</li> types</li> </li> </ul> See dhall-lang.org</a> for more information about the language. As a pre-requisite for this part, you need to: Install cert-manager</a> in your cluster. This has been tested with cert-manager v0.13.0</code> with the ca-injector enabled.</li> Install dhall-to-yaml</a> on your laptop or in your continuous deployment / gitops. This has been tested with dhall-to-yaml v1.6.1</code>.</li> </ul> Then, add a custom label to the namespaces you want to apply the webhook to: kubectl label namespace my-namespace my-webhook=enabled </code></pre> Deploying a webhook now is as easy as replacing the values in this example with yours: -- webhook.dhall let k8s = https://raw.githubusercontent.com/dhall-lang/dhall-kubernetes/6a47bd50c4d3984a13570ea62382a3ad4a9919a4/1.14/package.dhall let Webhook = https://raw.githubusercontent.com/EarnestResearch/dhall-packages/v0.11.1/kubernetes/webhook/package.dhall let config = Webhook::{ , imageName = "docker/whalesay" -- replace with your webhook docker image , name = "my-mutating-webhook" -- replace with a meaningful name , namespace = "default" -- replace with the namespace where you want to deploy it , path = "/mutate" -- replace with the path where the webhook is exposed , port = 8080 --replace with the port where the webhook is exposed , rules = -- replace with the rules you care about [ k8s.RuleWithOperations::{ , operations = [ "CREATE", "UPDATE" ] , apiGroups = [ "" ] , apiVersions = [ "v1" ] , resources = [ "pods" ] } ] , namespaceSelector = Some k8s.LabelSelector::{ , matchLabels = toMap { my-webhook = "enabled" } -- replace with the label you used for the namespace } } in Webhook.renderMutatingWebhook config -- or Webhook.renderValidatingWebhook </code></pre> Once the file is ready, run echo ./webhook.dhall | dhall-to-yaml --omit-empty | kubectl apply -n default -f - </code></pre> The webhook will be installed and ready to use, with all the certificates loaded.

Alessandro Marrella - kubernetes

Kubernetes Webhooks in Haskell and Dhall