Viewing legacy documentation for Kubebuilder, check out the latest documentation instead.
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 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
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.
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
The following comments are in 2 comments groups
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
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
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
type indicates the webhook type which can be either
failure-policy is used to set
The second category is for the webhook server.
All of them are used to configuration
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.
port is the port that the webhook server serves. It is used to set
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.labelsof the StatefulSet through
host is used to set
secret should be formatted as
<namespace>:<name>. It is used to set
mutating-webhook-config-name is used to set
validating-webhook-config-name is used to set