Webhook Configuration Installation

Installing webhook configurations requires higher privileges which manager's service account might not have. In that case, a separate process with higher privileges would like to install the webhook configurations.

There are 2 options to install webhook configurations into a cluster:

• Configure the Webhook Server to automatically install the webhook configurations when it starts.
• Use the webhook manifests generator to generate webhook configurations. Then install the webhook configurations and deploy the webhook servers.

Webhook Installer

Webhook installer is a feature provided by the controller-runtime library. For a Webhook Server, you can choose to enable the webhook installer. Depending on your ServerOptions, the installer may install mutatingWebhookConfigurations, validatingWebhookConfigurations and service; it may also update the secret if needed.

To make the webhook installer work correctly, please ensure the manager's service account has the right permissions. For example. it may need permissions:

• create and update MutatingWebhookConfigurations and ValidatingWebhookConfigurations
• create and update the Service in the same namespace of the manager
• update the Secret in the same namespace of the manager

The service fronts the webhook server. So please ensure the service's selectors select your webhook server pods.

The secret contains

• the serving certificate and its corresponding private key
• the signing CA certificate and its corresponding private key

Webhook installer can be very helpful for

• faster iteration during development
• easier deployment in production if policy allows

Webhook installer is on by default. Set DisableWebhookConfigInstaller to true to turn it off.

Webhook Manifests Generator

From cluster administrators perspective, they may want to have the webhook configurations installation to be a separate process from running the webhook server, since permissions to create and update webhook configurations are considered as high privileges.

Similar to other generators in controller-tools, webhook manifest generator is annotation-driven.

How the webhook manifest generator works 1) It parses the annotations to configure Webhook. 1) It parses the annotations to configure ServerOptions. 1) It uses the library in controller-runtime, which is the same machinery as the installer, to generate the webhook configuration manifests.

Comment Group

A comment group represents a sequence of comments with no empty lines between. Comment group is a concept that is important for writing and parsing annotations correctly.

For example, the following comments are in one comment group

// +kubebuilder:webhook:groups=apps
// +kubebuilder:webhook:resources=deployments

The following comments are in 2 comments groups

// +kubebuilder:webhook:groups=apps

// +kubebuilder:webhook:resources=deployments

Annotations

Each comment line that starts with +kubebuilder:webhook: will be processed to extract annotations.

The annotations can be grouped in 2 categories based on what struct they configure.

The first category is for each individual webhook. They are used to set the fields in Webhook struct. The annotations for the same webhook are allowed to span across multiple lines as long as they are prefixed with +kubebuilder:webhook: and in the same comment group. It is suggested to put this category of annotations in the same file as its corresponding webhook.

For example, the following is for one single webhook

// +kubebuilder:webhook:groups=apps,versions=v1,resources=deployments,verbs=create,update
// +kubebuilder:webhook:name=mutating-create-update-deployment.testproject.org
// +kubebuilder:webhook:path=/mutating-create-update-deployment
// +kubebuilder:webhook:type=mutating,failure-policy=fail

groups, versions and resources have the same semantic as the ones used for generating RBAC manifests. They can reference a core type or a CRD type.

verbs are used to set Operations. It supports create, update, delete, connect and * case-insensitively.

name is the name of the webhook and is used to set Name. path is the endpoint that this webhook serves and is used to set Path. Both name and path do NOT allow , and ;.

type indicates the webhook type which can be either mutating or validating.

failure-policy is used to set FailurePolicy. It supports fail and ignore case-insensitively.

The second category is for the webhook server. All of them are used to configuration ServerOptions struct. Each annotation should only be used once. They don't have to be in the same comment group. It is suggested to put this category of annotations in the same file as the webhook server.

The following is an example using webhook server annotations.

// +kubebuilder:webhook:port=7890,cert-dir=/path/to/cert
// +kubebuilder:webhook:service=test-system:webhook-service,selector=app:webhook-server
// +kubebuilder:webhook:secret=test-system:webhook-secret
// +kubebuilder:webhook:mutating-webhook-config-name=test-mutating-webhook-cfg
// +kubebuilder:webhook:validating-webhook-config-name=test-validating-webhook-cfg

port is the port that the webhook server serves. It is used to set Port.

service should be formatted as <namespace>:<name>. It is used to set the name and namespace of the service.

selector should be formatted as key1:value1;key2:value2 and it has 2 usages:

• use as selectors in the service
• use as additional labels that will be added to field .spec.template.metadata.labels of the StatefulSet through kustomize.

host is used to set Host.

secret should be formatted as <namespace>:<name>. It is used to set Secret

mutating-webhook-config-name is used to set MutatingWebhookConfigName.

validating-webhook-config-name is used to set ValidatingWebhookConfigName.