Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

📖 add note ClusterClass compatibility info to validating webhooks section #6875

Merged
merged 1 commit into from
Jul 13, 2022
Merged

📖 add note ClusterClass compatibility info to validating webhooks section #6875

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
24 changes: 23 additions & 1 deletion docs/book/src/developer/providers/webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,28 @@ Cluster API provides support for three kinds of webhooks: validating webhooks, d
## Validating webhooks
Validating webhooks are an implementation of a [Kubernetes validating webhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook). A validating webhook allows developers to test whether values supplied by users are valid. e.g. [the Cluster webhook] ensures the Infrastructure reference supplied at the Cluster's `.spec.infrastructureRef` is in the same namespace as the Cluster itself and rejects the object creation or update if not.

<aside class="note">

<h1> ClusterClass and managed topology support in validating webhooks </h1>

Validating webhooks implemented for a `InfrastructureMachineTemplate` or `BootstrapConfigTemplate` resource
are required to not block due to immutability checks when the controller for managed
topology and ClusterClass does [Server Side Apply] dry-run requests.
[Server Side Apply] implementation in ClusterClass and managed topologies requires to dry-run changes on templates.
If infrastructure or bootstrap providers have implemented immutability checks in their InfrastructureMachineTemplate
or BootstrapConfigTemplate webhooks, it is required to implement the following changes in order to prevent dry-run
to return errors. The implementation requires sigs.k8s.io/controller-runtime in version >= v0.12.3.
In order to do so it is required to use a controller runtime CustomValidator.
This will allow to skip the immutability check only when the topology controller is dry running while preserving the
validation behavior for all other cases.

chrischdi marked this conversation as resolved.
Show resolved Hide resolved
See [the DockerMachineTemplate webhook] as a reference for a compatible implementation.

[Server Side Apply]: https://kubernetes.io/docs/reference/using-api/server-side-apply/
[the DockerMachineTemplate webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/test/infrastructure/docker/api/v1beta1/dockermachinetemplate_webhook.go

</aside>

## Defaulting webhooks
Defaulting webhooks are an implementation of a [Kubernetes mutating webhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook). A defaulting webhook allows developers to set default values for a type before they are placed in the Kubernetes data store. e.g. [the Cluster webhook] will set the Infrastructure reference namespace to equal the Cluster namespace if `.spec.infrastructureRef.namespace` is empty.

Expand Down Expand Up @@ -35,4 +57,4 @@ type Cluster struct {
A detailed guide on the purpose of each of these tags is [here](https://book.kubebuilder.io/reference/markers/webhook.html).

<!-- links -->
[the Cluster webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/release-1.1/internal/webhooks/cluster.go
[the Cluster webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/internal/webhooks/cluster.go