feat: Add preflight checks framework

charts/cluster-api-runtime-extensions-nutanix/templates/webhooks.yaml

@@ -56,3 +56,23 @@ webhooks:
         resources:
           - clusters
     sideEffects: None
+  - admissionReviewVersions:
+      - v1
+    clientConfig:
+      service:
+        name: '{{ include "chart.name" . }}-admission'
+        namespace: '{{ .Release.Namespace }}'
+        path: /preflight-v1beta1-cluster
+    failurePolicy: Fail
+    name: preflight.cluster.caren.nutanix.com
+    rules:
+      - apiGroups:
+          - cluster.x-k8s.io
+        apiVersions:
+          - '*'
+        operations:
+          - CREATE
+        resources:
+          - clusters
+    sideEffects: None
+    timeoutSeconds: 30

cmd/main.go

@@ -41,6 +41,7 @@ import (
 	"github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/pkg/handlers/nutanix"
 	"github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/pkg/handlers/options"
 	"github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/pkg/webhook/cluster"
+	"github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/pkg/webhook/preflight"
 )
 
 func main() {
@@ -219,6 +220,13 @@ func main() {
 		Handler: cluster.NewValidator(mgr.GetClient(), admission.NewDecoder(mgr.GetScheme())),
 	})
 
+	mgr.GetWebhookServer().Register("/preflight-v1beta1-cluster", &webhook.Admission{
+		Handler: preflight.New(mgr.GetClient(), admission.NewDecoder(mgr.GetScheme()),
+			[]preflight.Checker{
+				// Add your preflight checkers here.
+			}...,
+		),
+	})
 	if err := mgr.Start(signalCtx); err != nil {
 		setupLog.Error(err, "unable to start controller manager")
 		os.Exit(1)

hack/update-webhook-configurations.yq

@@ -8,7 +8,7 @@ with(.metadata;
   .name = "{{ include \"chart.name\" . }}-" + .name,
   .annotations["cert-manager.io/inject-ca-from"] = "{{ .Release.Namespace}}/{{ template \"chart.name\" . }}-admission-tls"
 ),
-with(.webhooks[0].clientConfig.service;
+with(.webhooks[].clientConfig.service;
   .name = "{{ include \"chart.name\" . }}-admission",
   .namespace = "{{ .Release.Namespace }}"
 )

pkg/webhook/preflight/doc.go

@@ -0,0 +1,5 @@
+// Copyright 2025 Nutanix. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+package preflight
+
+// +kubebuilder:webhook:path=/preflight-v1beta1-cluster,mutating=false,failurePolicy=fail,groups="cluster.x-k8s.io",resources=clusters,verbs=create,versions=*,name=preflight.cluster.caren.nutanix.com,admissionReviewVersions=v1,sideEffects=None,timeoutSeconds=30

pkg/webhook/preflight/preflight.go

@@ -0,0 +1,153 @@
+// Copyright 2025 Nutanix. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+package preflight
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"sync"
+
+	admissionv1 "k8s.io/api/admission/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	clusterv1 "sigs.k8s.io/cluster-api/api/v1beta1"
+	ctrlclient "sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
+)
+
+type Cause struct {
+	Message string
+	Field   string
+}
+
+type CheckResult struct {
+	Name string
+
+	Allowed bool
+	Error   bool
+
+	Causes   []Cause
+	Warnings []string
+}
+
+type Check = func(ctx context.Context) CheckResult
+
+type Checker interface {
+	// Init decides which of its checks should run for the cluster. It then initializes the checks
+	// with common dependencies, such as an infrastructure client. Finally, it returns the initialized checks,
+	// ready to be run.
+	//
+	// Init can store the client and cluster, but not the context, because each check will accept its own context.
+	Init(ctx context.Context, client ctrlclient.Client, cluster *clusterv1.Cluster) []Check
+}
+
+type WebhookHandler struct {
+	client   ctrlclient.Client
+	decoder  admission.Decoder
+	checkers []Checker
+}
+
+func New(client ctrlclient.Client, decoder admission.Decoder, checkers ...Checker) *WebhookHandler {
+	h := &WebhookHandler{
+		client:   client,
+		decoder:  decoder,
+		checkers: checkers,
+	}
+	return h
+}
+
+func (h *WebhookHandler) Handle(ctx context.Context, req admission.Request) admission.Response {
+	if req.Operation == admissionv1.Delete {
+		return admission.Allowed("")
+	}
+
+	cluster := &clusterv1.Cluster{}
+	err := h.decoder.Decode(req, cluster)
+	if err != nil {
+		return admission.Errored(http.StatusBadRequest, err)
+	}
+
+	// Checks run only for ClusterClass-based clusters.
+	if cluster.Spec.Topology == nil {
+		return admission.Allowed("")
+	}
+
+	resp := admission.Response{
+		AdmissionResponse: admissionv1.AdmissionResponse{
+			Allowed: true,
+			Result: &metav1.Status{
+				Details: &metav1.StatusDetails{},
+			},
+		},
+	}
+
+	// Collect all checks in parallel.
+	checkerWG := &sync.WaitGroup{}
+	resultCh := make(chan CheckResult)
+	for _, checker := range h.checkers {
+		checkerWG.Add(1)
+
+		go func(ctx context.Context, checker Checker, resultCh chan CheckResult) {
+			// Initialize the checker.
+			checks := checker.Init(ctx, h.client, cluster)
+
+			// Run its checks in parallel.
+			checksWG := &sync.WaitGroup{}
+			for _, check := range checks {
+				checksWG.Add(1)
+				go func(ctx context.Context, check Check, resultCh chan CheckResult) {
+					result := check(ctx)
+					resultCh <- result
+					checksWG.Done()
+				}(ctx, check, resultCh)
+			}
+			checksWG.Wait()
+
+			checkerWG.Done()
+		}(ctx, checker, resultCh)
+	}
+
+	// Close the channel when all checkers are done.
+	go func(wg *sync.WaitGroup, resultCh chan CheckResult) {
+		wg.Wait()
+		close(resultCh)
+	}(checkerWG, resultCh)
+
+	// Collect all check results from the channel.
+	internalError := false
+	for result := range resultCh {
+		if result.Error {
+			internalError = true
+		}
+
+		if !result.Allowed {
+			resp.Allowed = false
+		}
+
+		for _, cause := range result.Causes {
+			resp.Result.Details.Causes = append(resp.Result.Details.Causes, metav1.StatusCause{
+				Type:    metav1.CauseType(fmt.Sprintf("FailedPreflight%s", result.Name)),
+				Message: cause.Message,
+				Field:   cause.Field,
+			})
+		}
+
+		resp.Warnings = append(resp.Warnings, result.Warnings...)
+	}
+
+	if len(resp.Result.Details.Causes) == 0 {
+		return resp
+	}
+
+	// Because we have some causes, we construct the response message and code.
+	resp.Result.Message = "preflight checks failed"
+	resp.Result.Code = http.StatusForbidden
+	resp.Result.Reason = metav1.StatusReasonForbidden
+	if internalError {
+		// Internal errors take precedence over check failures.
+		resp.Result.Code = http.StatusInternalServerError
+		resp.Result.Reason = metav1.StatusReasonInternalError
+	}
+
+	return resp
+}