Merge pull request #6109 from RainbowMango/pr_explain_interpreter_webhook

Explain the interpreter webhook comunication channel

Author: karmada-bot

api/openapi-spec/swagger.json

@@ -17791,7 +17791,7 @@
       ],
       "properties": {
         "clientConfig": {
-          "description": "ClientConfig defines how to communicate with the hook.",
+          "description": "ClientConfig defines how to communicate with the hook. It supports two mutually exclusive configuration modes:\n\n1. URL - Directly specify the webhook URL with format `scheme://host:port/path`.\n   Example: https://webhook.example.com:8443/my-interpreter\n\n2. Service - Reference a Kubernetes Service that exposes the webhook.\n   When using Service reference, Karmada resolves the endpoint through following steps:\n   a) First attempts to locate the Service in karmada-apiserver\n   b) If found, constructs URL based on Service type:\n      - ClusterIP/LoadBalancer/NodePort: Uses ClusterIP with port from Service spec\n        (Note: Services with ClusterIP \"None\" are rejected), Example:\n        `https://\u003ccluster ip\u003e:\u003cport\u003e`\n      - ExternalName: Uses external DNS name format: `https://\u003cexternal name\u003e:\u003cport\u003e`\n   c) If NOT found in karmada-apiserver, falls back to standard Kubernetes\n      service DNS name format: `https://\u003cservice\u003e.\u003cnamespace\u003e.svc:\u003cport\u003e`\n\nNote: When both URL and Service are specified, the Service reference takes precedence\n      and the URL configuration will be ignored.",
           "default": {},
           "$ref": "#/definitions/io.k8s.api.admissionregistration.v1.WebhookClientConfig"
         },

charts/karmada/_crds/bases/config/config.karmada.io_resourceinterpreterwebhookconfigurations.yaml

@@ -48,7 +48,26 @@ spec:
                 as the resources and operations it applies to.
               properties:
                 clientConfig:
-                  description: ClientConfig defines how to communicate with the hook.
+                  description: |-
+                    ClientConfig defines how to communicate with the hook.
+                    It supports two mutually exclusive configuration modes:
+
+                    1. URL - Directly specify the webhook URL with format `scheme://host:port/path`.
+                       Example: https://webhook.example.com:8443/my-interpreter
+
+                    2. Service - Reference a Kubernetes Service that exposes the webhook.
+                       When using Service reference, Karmada resolves the endpoint through following steps:
+                       a) First attempts to locate the Service in karmada-apiserver
+                       b) If found, constructs URL based on Service type:
+                          - ClusterIP/LoadBalancer/NodePort: Uses ClusterIP with port from Service spec
+                            (Note: Services with ClusterIP "None" are rejected), Example:
+                            `https://<cluster ip>:<port>`
+                          - ExternalName: Uses external DNS name format: `https://<external name>:<port>`
+                       c) If NOT found in karmada-apiserver, falls back to standard Kubernetes
+                          service DNS name format: `https://<service>.<namespace>.svc:<port>`
+
+                    Note: When both URL and Service are specified, the Service reference takes precedence
+                          and the URL configuration will be ignored.
                   properties:
                     caBundle:
                       description: |-

pkg/apis/config/v1alpha1/resourceinterpreterwebhook_types.go

@@ -56,6 +56,24 @@ type ResourceInterpreterWebhook struct {
 	Name string `json:"name"`
 
 	// ClientConfig defines how to communicate with the hook.
+	// It supports two mutually exclusive configuration modes:
+	//
+	// 1. URL - Directly specify the webhook URL with format `scheme://host:port/path`.
+	//    Example: https://webhook.example.com:8443/my-interpreter
+	//
+	// 2. Service - Reference a Kubernetes Service that exposes the webhook.
+	//    When using Service reference, Karmada resolves the endpoint through following steps:
+	//    a) First attempts to locate the Service in karmada-apiserver
+	//    b) If found, constructs URL based on Service type:
+	//       - ClusterIP/LoadBalancer/NodePort: Uses ClusterIP with port from Service spec
+	//         (Note: Services with ClusterIP "None" are rejected), Example:
+	//         `https://<cluster ip>:<port>`
+	//       - ExternalName: Uses external DNS name format: `https://<external name>:<port>`
+	//    c) If NOT found in karmada-apiserver, falls back to standard Kubernetes
+	//       service DNS name format: `https://<service>.<namespace>.svc:<port>`
+	//
+	// Note: When both URL and Service are specified, the Service reference takes precedence
+	//       and the URL configuration will be ignored.
 	// +required
 	ClientConfig admissionregistrationv1.WebhookClientConfig `json:"clientConfig"`