Skip to content

Commit 94f6eb5

Browse files
authored
Merge pull request #467 from mengqiy/webhook_generator_book
[book] webhook manifest generator
2 parents 3ca15af + 8160481 commit 94f6eb5

File tree

3 files changed

+152
-0
lines changed

3 files changed

+152
-0
lines changed

docs/book/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@
4141
* Webhooks
4242
* [What is a Webhook](beyond_basics/what_is_a_webhook.md)
4343
* [Webhook Example](beyond_basics/sample_webhook.md)
44+
* [Webhook Configuration Installation](beyond_basics/webhook_installer_generator.md)
4445
* Client-Go
4546
* [Generated Informers](beyond_basics/using_client_go_informers.md)
4647
* Deployment Workflow

docs/book/beyond_basics/sample_webhook.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,7 @@ A Server registers Webhook Configuration with the apiserver and creates an HTTP
124124
The server is behind a Kubernetes Service and provides a certificate to the apiserver when serving requests.
125125

126126
The Server depends on a Kubernetes Secret containing this certificate to be mounted under `CertDir`.
127+
The Secret needs to present but not have to be prepopulated before the manager pod starts.
127128

128129
If the Secret is empty, during bootstrapping the Server will generate a certificate and write it into the Secret.
129130

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Webhook Configuration Installation
2+
3+
Installing webhook configurations requires higher privileges which manager's service account might not have.
4+
In that case, a separate process with higher privileges would like to install the webhook configurations.
5+
6+
There are 2 options to install webhook configurations into a cluster:
7+
8+
- Configure the Webhook Server to automatically install the webhook configurations when it starts.
9+
- Use the webhook manifests generator to generate webhook configurations.
10+
Then install the webhook configurations and deploy the webhook servers.
11+
12+
## Webhook Installer
13+
14+
Webhook installer is a feature provided by the [controller-runtime](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/webhook) library.
15+
For a [Webhook Server](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/webhook#Server),
16+
you can choose to enable the webhook installer.
17+
Depending on your [ServerOptions](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/webhook#ServerOptions),
18+
the installer may install [mutatingWebhookConfigurations](https://github.com/kubernetes/api/blob/9fcf73cc980bd64f38a4f721a7371b0ebb72e1ff/admissionregistration/v1beta1/types.go#L113-L124),
19+
[validatingWebhookConfigurations](https://github.com/kubernetes/api/blob/9fcf73cc980bd64f38a4f721a7371b0ebb72e1ff/admissionregistration/v1beta1/types.go#L83-L94)
20+
and service; it may also update the secret if needed.
21+
22+
To make the webhook installer work correctly, please ensure the manager's service account has
23+
the right permissions. For example. it may need permissions:
24+
- create and update MutatingWebhookConfigurations and ValidatingWebhookConfigurations
25+
- create and update the Service in the same namespace of the manager
26+
- update the Secret in the same namespace of the manager
27+
28+
The service fronts the webhook server.
29+
So please ensure the service's selectors select your webhook server pods.
30+
31+
The secret contains
32+
- the serving certificate and its corresponding private key
33+
- the signing CA certificate and its corresponding private key
34+
35+
Webhook installer can be very helpful for
36+
- faster iteration during development
37+
- easier deployment in production if policy allows
38+
39+
Webhook installer is on by default. Set
40+
[`DisableWebhookConfigInstaller`](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/server.go#L57-L60)
41+
to true to turn it off.
42+
43+
## Webhook Manifests Generator
44+
45+
From cluster administrators perspective, they may want to have the webhook configurations
46+
installation to be a separate process from running the webhook server,
47+
since permissions to create and update webhook configurations are considered as high privileges.
48+
49+
Similar to other generators in [controller-tools](https://github.com/kubernetes-sigs/controller-tools),
50+
webhook manifest generator is annotation-driven.
51+
52+
How the webhook manifest generator works
53+
1) It parses the annotations to configure
54+
[Webhook](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/webhook/admission#Webhook).
55+
1) It parses the annotations to configure
56+
[ServerOptions](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/webhook#ServerOptions).
57+
1) It uses the library in controller-runtime, which is the same machinery as
58+
the installer, to generate the webhook configuration manifests.
59+
60+
#### Comment Group
61+
62+
A comment group represents a sequence of comments with no empty lines between.
63+
Comment group is a concept that is important for writing and parsing annotations correctly.
64+
65+
For example, the following comments are in one comment group
66+
67+
```
68+
// +kubebuilder:webhook:groups=apps
69+
// +kubebuilder:webhook:resources=deployments
70+
```
71+
72+
The following comments are in 2 comments groups
73+
74+
```
75+
// +kubebuilder:webhook:groups=apps
76+
77+
// +kubebuilder:webhook:resources=deployments
78+
```
79+
80+
#### Annotations
81+
82+
Each comment line that starts with `+kubebuilder:webhook:` will be processed to extract annotations.
83+
84+
The annotations can be grouped in 2 categories based on what struct they configure.
85+
86+
The _first_ category is for each individual webhook.
87+
They are used to set the fields in [`Webhook`](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/admission/webhook.go#L55-L80) struct.
88+
The annotations for the same webhook are allowed to span across multiple lines as long as they are prefixed with
89+
`+kubebuilder:webhook:` and in the __same__ comment group.
90+
It is suggested to put this category of annotations in the same file as its corresponding webhook.
91+
92+
For example, the following is for one single webhook
93+
94+
```
95+
// +kubebuilder:webhook:groups=apps,versions=v1,resources=deployments,verbs=create,update
96+
// +kubebuilder:webhook:name=mutating-create-update-deployment.testproject.org
97+
// +kubebuilder:webhook:path=/mutating-create-update-deployment
98+
// +kubebuilder:webhook:type=mutating,failure-policy=fail
99+
```
100+
101+
`groups`, `versions` and `resources` have the same semantic as the ones used for generating RBAC manifests.
102+
They can reference a core type or a CRD type.
103+
104+
`verbs` are used to set [`Operations`](https://github.com/kubernetes/api/blob/9fcf73cc980bd64f38a4f721a7371b0ebb72e1ff/admissionregistration/v1beta1/types.go#L234-L243).
105+
It supports `create`, `update`, `delete`, `connect` and `*` case-insensitively.
106+
107+
`name` is the name of the webhook and
108+
is used to set [`Name`](https://github.com/kubernetes/api/blob/9fcf73cc980bd64f38a4f721a7371b0ebb72e1ff/admissionregistration/v1beta1/types.go#L146).
109+
`path` is the endpoint that this webhook serves and
110+
is used to set [`Path`](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/admission/webhook.go#L61-L62).
111+
Both `name` and `path` do NOT allow `,` and `;`.
112+
113+
`type` indicates the webhook type which can be either `mutating` or `validating`.
114+
115+
`failure-policy` is used to set [`FailurePolicy`](https://github.com/kubernetes/api/blob/9fcf73cc980bd64f38a4f721a7371b0ebb72e1ff/admissionregistration/v1beta1/types.go#L54-L61).
116+
It supports `fail` and `ignore` case-insensitively.
117+
118+
The _second_ category is for the webhook server.
119+
All of them are used to configuration [`ServerOptions`](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/server.go#L39-L98) struct.
120+
Each annotation should only be used once.
121+
They don't have to be in the same comment group.
122+
It is suggested to put this category of annotations in the same file as the webhook server.
123+
124+
The following is an example using webhook server annotations.
125+
126+
```
127+
// +kubebuilder:webhook:port=7890,cert-dir=/path/to/cert
128+
// +kubebuilder:webhook:service=test-system:webhook-service,selector=app:webhook-server
129+
// +kubebuilder:webhook:secret=test-system:webhook-secret
130+
// +kubebuilder:webhook:mutating-webhook-config-name=test-mutating-webhook-cfg
131+
// +kubebuilder:webhook:validating-webhook-config-name=test-validating-webhook-cfg
132+
```
133+
134+
`port` is the port that the webhook server serves. It is used to set [`Port`](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/server.go#L43).
135+
136+
`service` should be formatted as `<namespace>:<name>`. It is used to set
137+
[the name and namespace of the service](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/server.go#L102-L105).
138+
139+
`selector` should be formatted as `key1:value1;key2:value2` and it has 2 usages:
140+
- use as [selectors in the service](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/server.go#L106-L108)
141+
- use as additional labels that will be added to field `.spec.template.metadata.labels` of
142+
the StatefulSet through [`kustomize`](https://github.com/kubernetes-sigs/kustomize).
143+
144+
`host` is used to set [`Host`](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/server.go#L87-L91).
145+
146+
`secret` should be formatted as `<namespace>:<name>`. It is used to set [`Secret`](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/server.go#L73-L77)
147+
148+
`mutating-webhook-config-name` is used to set [`MutatingWebhookConfigName`](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/server.go#L68-L69).
149+
150+
`validating-webhook-config-name` is used to set [`ValidatingWebhookConfigName`](https://github.com/kubernetes-sigs/controller-runtime/blob/a8ea2056444a5d74d7408e4b8798cbe63b14066b/pkg/webhook/server.go#L70-L71).

0 commit comments

Comments
 (0)