Phase 5: Dynamic Webhook Middleware Kubernetes Controller

cmd/thv-operator/api/v1alpha1/mcpserver_types.go

@@ -71,12 +71,18 @@ const (
 const (
 	// ConditionTypeExternalAuthConfigValidated indicates whether the ExternalAuthConfig is valid
 	ConditionTypeExternalAuthConfigValidated = "ExternalAuthConfigValidated"
+
+	// ConditionTypeWebhookConfigValidated indicates whether the WebhookConfig is valid
+	ConditionTypeWebhookConfigValidated = "WebhookConfigValidated"
 )
 
 const (
 	// ConditionReasonExternalAuthConfigMultiUpstream indicates the ExternalAuthConfig has multiple upstreams,
 	// which is not supported for MCPServer (use VirtualMCPServer for multi-upstream).
 	ConditionReasonExternalAuthConfigMultiUpstream = "MultiUpstreamNotSupported"
+
+	// ConditionReasonWebhookConfigInvalid indicates the referenced webhook config is invalid or missing
+	ConditionReasonWebhookConfigInvalid = "WebhookConfigInvalid"
 )
 
 // ConditionStdioReplicaCapped indicates spec.replicas was capped at 1 for stdio transport.
@@ -222,6 +228,11 @@ type MCPServerSpec struct {
 	// +optional
 	ExternalAuthConfigRef *ExternalAuthConfigRef `json:"externalAuthConfigRef,omitempty"`
 
+	// WebhookConfigRef references a MCPWebhookConfig resource for webhook middleware configuration.
+	// The referenced MCPWebhookConfig must exist in the same namespace as this MCPServer.
+	// +optional
+	WebhookConfigRef *WebhookConfigRef `json:"webhookConfigRef,omitempty"`
+
 	// Telemetry defines observability configuration for the MCP server
 	// +optional
 	Telemetry *TelemetryConfig `json:"telemetry,omitempty"`
@@ -734,6 +745,14 @@ type ExternalAuthConfigRef struct {
 	Name string `json:"name"`
 }
 
+// WebhookConfigRef defines a reference to a MCPWebhookConfig resource.
+// The referenced MCPWebhookConfig must be in the same namespace as the MCPServer.
+type WebhookConfigRef struct {
+	// Name is the name of the MCPWebhookConfig resource
+	// +kubebuilder:validation:Required
+	Name string `json:"name"`
+}
+
 // ToolConfigRef defines a reference to a MCPToolConfig resource.
 // The referenced MCPToolConfig must be in the same namespace as the MCPServer.
 type ToolConfigRef struct {
@@ -860,6 +879,10 @@ type MCPServerStatus struct {
 	// +optional
 	ExternalAuthConfigHash string `json:"externalAuthConfigHash,omitempty"`
 
+	// WebhookConfigHash is the hash of the referenced MCPWebhookConfig spec
+	// +optional
+	WebhookConfigHash string `json:"webhookConfigHash,omitempty"`
+
 	// URL is the URL where the MCP server can be accessed
 	// +optional
 	URL string `json:"url,omitempty"`

cmd/thv-operator/api/v1alpha1/mcpwebhookconfig_types.go

@@ -0,0 +1,133 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	"github.com/stacklok/toolhive/pkg/webhook"
+)
+
+// WebhookTLSConfig contains TLS configuration for secure webhook connections
+type WebhookTLSConfig struct {
+	// CASecretRef references a Secret containing the CA certificate bundle used to verify the webhook server's certificate.
+	// Contains a bundle of PEM-encoded X.509 certificates.
+	// +optional
+	CASecretRef *SecretKeyRef `json:"caSecretRef,omitempty"`
+
+	// ClientCertSecretRef references a Secret containing the client certificate for mTLS authentication.
+	// The secret must contain both a client certificate (PEM-encoded) and a client private key (PEM-encoded).
+	// If only the path or a reference to it is available at runtime, both must be handled together.
+	// Typically the Secret should have 'tls.crt' and 'tls.key'. Wait, actually to follow the same pattern, a single SecretKeyRef might just point to a TLS secret where we load the cert and key. But we're going with a reference that will build local certs. To keep it simple, we could either reference two keys or a TLS secret. Let's look closely at the issue description... The issue says "ClientCertSecretRef references a secret containing client cert for mTLS" which points to SecretKeyRef, but typically mTLS has a key and a cert. I will stick to what's defined in the issue description, but augment it slightly: we'll use TLS secret type if possible.
+	// Actually, the issue specifically asks for ClientCertSecretRef *SecretKeyRef `json:"clientCertSecretRef,omitempty"`. Let's stick strictly to it, but also add ClientKeySecretRef if needed, since mTLS always requires both. In pkg/webhook/types.go TLSConfig has `ClientCertPath` and `ClientKeyPath`. I will define ClientCertSecretRef and ClientKeySecretRef to map to them. Wait, the RFC says ClientCertSecretRef to point to a kubernetes.io/tls type secret. Let's use `ClientCertSecretRef *corev1.LocalObjectReference` meaning it refers to a TLS Secret containing `tls.crt` and `tls.key`. Let's revisit the issue. "ClientCertSecretRef *SecretKeyRef". Wait, SecretKeyRef means a specific key in a secret. If a user needs both, using SecretKeyRef for cert is weird because what about the key? Wait, maybe it's `SecretReference`? Let's use `SecretKeyRef` for `CASecretRef` and for `ClientCertSecretRef`, I'll use it but comment that it should be a key if combined or maybe that's not right. Let's check `mcpexternalauthconfig_types.go` or other types. I'll just stick strictly to the exact types described in the issue.
+	// +optional
+	ClientCertSecretRef *SecretKeyRef `json:"clientCertSecretRef,omitempty"`
+
+	// ClientKeySecretRef is the private key for the client cert. I am adding this to make mTLS work correctly, as we need both a public cert and private key to configure client certificates in Go.
+	// +optional
+	ClientKeySecretRef *SecretKeyRef `json:"clientKeySecretRef,omitempty"`
+
+	// InsecureSkipVerify disables server certificate verification.
+	// WARNING: This should only be used for development/testing and not in production environments.
+	// +optional
+	InsecureSkipVerify bool `json:"insecureSkipVerify,omitempty"`
+}
+
+// WebhookSpec defines the configuration for a single webhook middleware
+type WebhookSpec struct {
+	// Name is a unique identifier for this webhook
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=63
+	Name string `json:"name"`
+
+	// URL is the endpoint to call for this webhook. Must be an HTTP/HTTPS URL.
+	// +kubebuilder:validation:Format=uri
+	URL string `json:"url"`
+
+	// Timeout configures the maximum time to wait for the webhook to respond.
+	// Defaults to 10s if not specified. Maximum is 30s.
+	// +kubebuilder:validation:Type=string
+	// +kubebuilder:validation:Format=duration
+	// +optional
+	Timeout *metav1.Duration `json:"timeout,omitempty"`
+
+	// FailurePolicy defines how to handle errors when communicating with the webhook.
+	// Supported values: "fail", "ignore". Defaults to "fail".
+	// +kubebuilder:validation:Enum=fail;ignore
+	// +kubebuilder:default=fail
+	// +optional
+	FailurePolicy webhook.FailurePolicy `json:"failurePolicy,omitempty"`
+
+	// TLSConfig contains optional TLS configuration for the webhook connection.
+	// +optional
+	TLSConfig *WebhookTLSConfig `json:"tlsConfig,omitempty"`
+
+	// HMACSecretRef references a Kubernetes Secret containing the HMAC signing key
+	// used to sign the webhook payload. If set, the X-Toolhive-Signature header will be injected.
+	// +optional
+	HMACSecretRef *SecretKeyRef `json:"hmacSecretRef,omitempty"`
+}
+
+// MCPWebhookConfigSpec defines the desired state of MCPWebhookConfig
+// +kubebuilder:validation:XValidation:rule="size(self.validating) + size(self.mutating) > 0",message="at least one validating or mutating webhook must be defined"
+type MCPWebhookConfigSpec struct {
+	// Validating webhooks are called to approve or deny MCP requests.
+	// +optional
+	Validating []WebhookSpec `json:"validating,omitempty"`
+
+	// Mutating webhooks are called to transform MCP requests before processing.
+	// +optional
+	Mutating []WebhookSpec `json:"mutating,omitempty"`
+}
+
+// MCPWebhookConfigStatus defines the observed state of MCPWebhookConfig
+type MCPWebhookConfigStatus struct {
+	// ConfigHash is a hash of the spec, used for detecting changes
+	// +optional
+	ConfigHash string `json:"configHash,omitempty"`
+
+	// ReferencingServers lists the names of MCPServers currently using this configuration
+	// +optional
+	ReferencingServers []string `json:"referencingServers,omitempty"`
+
+	// ObservedGeneration is the last observed generation corresponding to the current status
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+	// Conditions represent the latest available observations
+	// +optional
+	// +patchMergeKey=type
+	// +patchStrategy=merge
+	// +listType=map
+	// +listMapKey=type
+	Conditions []metav1.Condition `json:"conditions,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:resource:shortName=mwc
+// +kubebuilder:printcolumn:name="Referencing Servers",type="integer",JSONPath=".status.referencingServers.length()",description="Number of MCPServers referencing this config"
+// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
+
+// MCPWebhookConfig is the Schema for the mcpwebhookconfigs API
+type MCPWebhookConfig struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   MCPWebhookConfigSpec   `json:"spec,omitempty"`
+	Status MCPWebhookConfigStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// MCPWebhookConfigList contains a list of MCPWebhookConfig
+type MCPWebhookConfigList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []MCPWebhookConfig `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&MCPWebhookConfig{}, &MCPWebhookConfigList{})
+}

cmd/thv-operator/api/v1alpha1/mcpwebhookconfig_types_test.go

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package v1alpha1
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	"github.com/stacklok/toolhive/pkg/webhook"
+)
+
+func TestMCPWebhookConfig_Creation(t *testing.T) {
+	t.Parallel()
+
+	timeout := metav1.Duration{Duration: 5 * time.Second}
+
+	config := &MCPWebhookConfig{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      "test-webhook-config",
+			Namespace: "default",
+		},
+		Spec: MCPWebhookConfigSpec{
+			Validating: []WebhookSpec{
+				{
+					Name:          "test-validator",
+					URL:           "https://example.com/validate",
+					Timeout:       &timeout,
+					FailurePolicy: webhook.FailurePolicyFail,
+					TLSConfig: &WebhookTLSConfig{
+						InsecureSkipVerify: true,
+					},
+				},
+			},
+			Mutating: []WebhookSpec{
+				{
+					Name:          "test-mutator",
+					URL:           "https://example.com/mutate",
+					Timeout:       &timeout,
+					FailurePolicy: webhook.FailurePolicyIgnore,
+					HMACSecretRef: &SecretKeyRef{
+						Name: "hmac-secret",
+						Key:  "key",
+					},
+				},
+			},
+		},
+	}
+
+	assert.NotNil(t, config)
+	assert.Equal(t, "test-webhook-config", config.Name)
+	assert.Len(t, config.Spec.Validating, 1)
+	assert.Len(t, config.Spec.Mutating, 1)
+
+	assert.Equal(t, "test-validator", config.Spec.Validating[0].Name)
+	assert.Equal(t, webhook.FailurePolicyFail, config.Spec.Validating[0].FailurePolicy)
+	assert.True(t, config.Spec.Validating[0].TLSConfig.InsecureSkipVerify)
+
+	assert.Equal(t, "test-mutator", config.Spec.Mutating[0].Name)
+	assert.Equal(t, webhook.FailurePolicyIgnore, config.Spec.Mutating[0].FailurePolicy)
+	assert.Equal(t, "hmac-secret", config.Spec.Mutating[0].HMACSecretRef.Name)
+}