add the introduction of configuring clientConfig to the resource intrepreter webhook

Signed-off-by: changzhen <[email protected]>

Author: XiShanYongYe-Chang

Diff for: examples/customresourceinterpreter/README.md

@@ -1,20 +1,45 @@
-# Examples
+# Resource Interpreter Webhook
 
-## Resource Interpreter
+This document uses an example of a resource interpreter webhook to show users its usage. In the example, we process a CustomResourceDefinition(CRD) resource named `Workload`. Users can implement their own resource interpreter webhook component based on their own business, taking `karmada-interpreter-webhook-example` as an example.
 
-This example installs a CustomResourceDefinition(CRD), `Workload` in the `karmada-apiserver`, and deploys a deployment `karmada-interpreter-webhook-example` in the Karmada host.
+## Document introduction
 
-### Install
+```
+examples/customresourceinterpreter/
+│
+├── apis/                                        # API Definition
+│   ├── workload/                                # `Workload` API Definition
+│   │   ├── v1alpha1                             # `Workload` v1alpha1 version API Definition
+│   │   |   ├── doc.go                           # API Package Introduction
+│   │   |   ├── workload_types.go                # example `Workload` API Definition
+│   │   |   ├── zz_generated.deepcopy.go         # generated by `deepcopy-gen`
+|   |   |   └── zz_generated.register.go         # generated by `register-gen`
+│   └── └── workload.example.io_workloads.yaml   # `Workload` CustomResourceDefinition, generated by `controller-gen crd`
+│
+├── webhook/                                     # demo for `karmada-interpreter-webhook-example` component
+│
+├── karmada-interpreter-webhook-example.yaml     # component deployment configuration file
+├── README.md                                    # README file
+├── webhook-configuration.yaml                   # ResourceInterpreterWebhookConfiguration configuration file
+├── workload.yaml                                # `Workload` resource example
+└── workload-propagationpolicy.yaml              # `PropagationPolicy` resource example to propagate `Workload` resource
+```
 
-### Prerequisites
+## Install
 
-For Karmada deploy using `hack/local-up-karmada.sh`, there are `karmada-host`, `karmada-apiserver` and three member clusters named `member1`, `member2` and `member3`.
+For a Karmada instance, the cluster where the Karmada component is deployed is called `karmada-host` cluster.
+
+This document uses the Karmada instance installed in `hack/local-up-karmada.sh` mode as an example, there are `karmada-host`, `karmada-apiserver` and three member clusters named `member1`, `member2` and `member3`.
 
 > Note: If you use other installation methods, please adapt your installation method proactively.
 
-In the current example, we will deploy `karmada-interpreter-webhook-example` in the Karmada control plane. Since it involves a cluster with Pull mode, the initiator of resource interpreter requests is in `karmada-agent`. Therefore, we create a Service of type `LoadBalancer` for `karmada-interpreter-webhook-example`.
+### Prerequisites
+
+Considering that there is a `Pull` type cluster in the cluster, it is necessary to set up a LoadBalancer type Service for `karmada-interpreter-webhook-example` so that all clusters can access the resource interpreter webhook service. In this document, we deploy `MetalLB` to expose the webhook service.
 
-So we need to deploy MetalLB as a Load Balancer to expose the webhook. Please run the following script to deploy MetalLB.
+If all your clusters are `Push` type clusters, you can access the webhook service in the `karmada-host` cluster through `Service` without configuring additional `MetalLB`.
+
+Please run the following script to deploy `MetalLB`.
 
 ```bash
 kubectl --context="karmada-host" get configmap kube-proxy -n kube-system -o yaml | \
@@ -49,15 +74,17 @@ metadata:
 EOF
 ```
 
-#### Step1: Install `Workload` CRD in `karmada-apiserver` and member clusters
+### Deploy karmada-interpreter-webhook-example
+
+#### Step1: Install `Workload` CRD
 
-Install CRD in `karmada-apiserver` by running the following command:
+Install `Workload` CRD in `karmada-apiserver` by running the following command:
 
 ```bash
 kubectl --kubeconfig $HOME/.kube/karmada.config --context karmada-apiserver apply -f examples/customresourceinterpreter/apis/workload.example.io_workloads.yaml
 ```
 
-Create a `ClusterPropagationPolicy` resource object to propagate `Workload` CRD to member clusters:
+And then, create a `ClusterPropagationPolicy` resource object to propagate `Workload` CRD to all member clusters:
 
 <details>
 
@@ -86,9 +113,63 @@ spec:
 kubectl --kubeconfig $HOME/.kube/karmada.config --context karmada-apiserver apply -f workload-crd-cpp.yaml
 ```
 
-#### Step2: Deploy webhook configuration in karmada-apiserver
+#### Step2: Deploy webhook configuration in `karmada-apiserver`
+
+We can tell Karmada how to access the resource interpreter webhook service by configuring `ResourceInterpreterWebhookConfiguration`. The configuration template is as follows:
+
+```yaml
+apiVersion: config.karmada.io/v1alpha1
+kind: ResourceInterpreterWebhookConfiguration
+metadata:
+  name: examples
+webhooks:
+  - name: workloads.example.com
+    rules:
+      - operations: [ "InterpretReplica","ReviseReplica","Retain","AggregateStatus", "InterpretHealth", "InterpretStatus", "InterpretDependency" ]
+        apiGroups: [ "workload.example.io" ]
+        apiVersions: [ "v1alpha1" ]
+        kinds: [ "Workload" ]
+    clientConfig:
+      url: https://{{karmada-interpreter-webhook-example-svc-address}}:443/interpreter-workload
+      caBundle: {{caBundle}}
+    interpreterContextVersions: [ "v1alpha1" ]
+    timeoutSeconds: 3
+```
+
+If you only need to access the resource interpreter webhook service in the `Karmada-host` cluster, you can directly configure `clientConfig` with the Service domain name in the cluster:
+
+```yaml
+clientConfig:
+  url: https://karmada-interpreter-webhook-example.karmada-system.svc:443/interpreter-workload
+  caBundle: {{caBundle}}
+```
+
+Alternatively, you can also define service in clientConfig, which requires you to deploy a Service of type ExternalName in `Karmada-apiserver`:
+
+```yaml
+clientConfig:
+  caBundle: {{caBundle}}
+  service:
+    namespace: karmada-system
+    name: karmada-interpreter-webhook-example
+    port: 443
+    path: /interpreter-workload
+```
+
+Deploy the Service in `karmada-apiserver`.
 
-Execute below script:
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: karmada-interpreter-webhook-example
+  namespace: karmada-system
+spec:
+  type: ExternalName
+  externalName: karmada-interpreter-webhook-example.karmada-system.svc.cluster.local
+```
+
+In the example of this article, you can directly run the following script to deploy ResourceInterpreterWebhookConfiguration:
 
 <details>
 
@@ -114,17 +195,18 @@ rm -rf "${temp_path}"
 
 ```bash
 chmod +x webhook-configuration.sh
-
 ./webhook-configuration.sh
 ```
 
-#### Step3: Deploy karmada-interpreter-webhook-example in karmada-host
+#### Step3: Deploy `karmada-interpreter-webhook-example` in karmada-host
+
+Run the following command:
 
 ```bash
 kubectl --kubeconfig $HOME/.kube/karmada.config --context karmada-host apply -f examples/customresourceinterpreter/karmada-interpreter-webhook-example.yaml
 ```
 
-> Note: karmada-interpreter-webhook-example is just a demo for testing and reference. If you plan to use the interpreter webhook, please implement specific components based on your business needs.
+> Note: `karmada-interpreter-webhook-example` is just a demo for testing and reference. If you plan to use the interpreter webhook, please implement specific components based on your business needs.
 
 In the current example, the interpreter webhook is deployed under the namespace `karmada-system`. If you are trying to deploy the interpreter webhook in a namespace other than the default karmada-system namespace, and use the domain address of Service in the URL. Such as (take the `test` namespace as an example):
 
@@ -157,6 +239,8 @@ We recommend that you deploy the interpreter webhook component and Karmada contr
 
 The relevant problem description has been recorded in [#4478](https://github.com/karmada-io/karmada/issues/4478), please refer to it.
 
+At this point, you have successfully installed the `karmada-interpreter-webhook-example` service and can start using it.
+
 ### Usage
 
 Create a `Workload` resource and propagate it to the member clusters: