doc: add mcs doc

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

docs/tutorials/access-service-across-clusters.md

@@ -0,0 +1,165 @@
+---
+title: Access service acrosss clusters within native service name
+---
+
+In Karmada, the MultiClusterService can enable users to access services across clusters with the native service name, like `foo.svc`, with the aim of providing a seamless experience for users to access services across clusters.
+
+This document provides an example of how to enable MultiClusterService for accessing service across clusters with native service name.
+
+## Prerequisites
+
+### Karmada has been installed
+
+We can install Karmada by referring to [Quick Start](https://github.com/karmada-io/karmada#quick-start), or directly run `hack/local-up-karmada.sh` script which is also used to run our E2E cases.
+
+## Deploy deployment in `member1` cluster
+
+We need to deploy deployment in `member1` cluster:
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+  labels:
+    app: nginx
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - image: nginx
+        name: nginx
+        resources:
+          requests:
+            cpu: 25m
+            memory: 64Mi
+          limits:
+            cpu: 25m
+            memory: 64Mi
+---
+apiVersion: policy.karmada.io/v1alpha1
+kind: PropagationPolicy
+metadata:
+  name: nginx-propagation
+spec:
+  resourceSelectors:
+    - apiVersion: apps/v1
+      kind: Deployment
+      name: nginx
+  placement:
+    clusterAffinity:
+      clusterNames:
+        - member1
+```
+
+After deploying, you can check the created pods:
+```sh
+$ karmadactl get po
+NAME                     CLUSTER   READY   STATUS              RESTARTS   AGE
+nginx-5c54b4855f-6sq9s   member1   0/1     Running             0          28s
+nginx-5c54b4855f-vp948   member1   0/1     Running             0          28s
+```
+
+## Deploy curl pod in `member2` cluster
+
+Let's deploy a curl pod in `member2` cluster:
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: curl
+  labels:
+    app: curl
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: curl
+  template:
+    metadata:
+      labels:
+        app: curl
+    spec:
+      containers:
+      - image: curlimages/curl:latest
+        command: ["sleep", "infinity"]
+        name: curl
+        resources:
+          requests:
+            cpu: 25m
+            memory: 64Mi
+          limits:
+            cpu: 25m
+            memory: 64Mi
+---
+apiVersion: policy.karmada.io/v1alpha1
+kind: PropagationPolicy
+metadata:
+  name: curl-propagation
+spec:
+  resourceSelectors:
+    - apiVersion: apps/v1
+      kind: Deployment
+      name: curl
+  placement:
+    clusterAffinity:
+      clusterNames:
+        - member2
+```
+
+
+After deploying, you can check the created pods:
+```sh
+$ karmadactl get po -C member2
+NAME                    CLUSTER   READY   STATUS    RESTARTS   AGE
+curl-6894f46595-c75rc   member2   1/1     Running   0          15s
+```
+
+Later, we will run the curl command in this pod.
+
+### Deploy MultiClusterService and Service in Karmada
+
+Now, let's deploy Service and MultiClusterService in Karmada:
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: nginx
+spec:
+  ports:
+  - port: 80
+    targetPort: 8080
+  selector:
+    app: nginx
+---
+apiVersion: networking.karmada.io/v1alpha1
+kind: MultiClusterService
+metadata:
+   name: nginx
+spec:
+  types:
+    - CrossCluster
+  consumerClusters:
+    - name: member2
+  providerClusters:
+    - name: member1
+```
+
+### Access the backend pods from member2 cluster
+
+To access the backend pods in the member1 cluster from the member2 cluster, execute the following command:
+```sh
+$ karmadactl exec -C member2 curl-6894f46595-c75rc -it -- sh
+~ $ curl http://nginx.default
+Hello, world!
+Version: 1.0.0
+Hostname: nginx-0
+```
+
+Using MultiClusterService, the pods are situated solely in the member1 cluster. However, they can be accessed from the member2 cluster using the native service name.

docs/userguide/service/multi-cluster-service-with-native-svc-access.mdx

@@ -0,0 +1,41 @@
+---
+title: Multi-cluster service with native service name access
+---
+
+import MCSOverview from '../../resources/userguide/service/multiclusterservice/mcs-overview.png';
+import MCSWayOfWork from '../../resources/userguide/service/multiclusterservice/mcs-way-of-work.png';
+
+In Karmada, the MultiClusterService can enable users to access services across clusters with the native service name, like `foo.svc`, with the aim of providing a seamless experience for users to access services across clusters.
+
+<p align="center">
+    <img src={MCSOverview} width="80%"/>
+</p>
+
+Once the network is connected between clusters, with MultiClusterSerivce, the accessing will be directed to the active backend pods distributed across these clusters.
+
+The MultiCluster Service is implemented as a Karmada API resource and multiple controllers, the resource determines the behavior of the controller. The multiple controllers, runnning within the Karmada control plane, sync the services' backend EndpointSlice resource between clusters, to add the multiple clusters' pods' IP to the services' backend.
+
+## How does a MultiCluster Service work?
+
+To implement access service across multiple clusters with native service name, Karmada introduces multiple controllers to sync the services' backend EndpointSlice resource between clusters, they work as follows:
+
+<p align="center">
+    <img src={MCSWayOfWork} width="80%"/>
+</p>
+
+1. Karmada will collect EndpointSlice resources from all target clusters, and sync them to the Karmada control plane.
+2. Karmada will sync the collected EndpointSlice resources to all target clusters, with attaching the EndpointSlice to the service.
+3. When users access through `foo.svc`, the underlying network will route the request to the backend pods in the multiple clusters.
+
+## API Object
+
+The MultiClusterService is an API in the Karmada networking API group. The current version is v1alpha1.
+
+You can check the FederatedHPA API specification [here](https://github.com/karmada-io/karmada/blob/65376b28d5037c27ff7ec0e56542c2a345d1a120/pkg/apis/networking/v1alpha1/service_types.go#L50).
+
+## What's next
+
+If you configure MultiClusterService, you may also want to consider how to connectt the network between clusters, such as [Submariner](../network/working-with-submariner.md).
+
+For more information on MultiClusterService:
+* Read [Access serice across clusters within native service name](../../tutorials/access-service-across-clusters) to know how to use MultiClusterService.

sidebars.js

@@ -35,6 +35,7 @@ module.exports = {
                 "tutorials/autoscaling-federatedhpa-with-cronfederatedhpa",
                 "tutorials/autoscaling-workload-with-cronfederatedhpa",
                 "tutorials/resource-migration",
+                "tutorials/access-service-across-clusters",
             ],
         },
         {
@@ -99,6 +100,7 @@ module.exports = {
                     items: [
                         "userguide/service/multi-cluster-service",
                         "userguide/service/multi-cluster-ingress",
+                        "userguide/service/multi-cluster-service-with-native-svc-access",
                         "userguide/service/working-with-eriecanal",
                         "userguide/service/working-with-istio-on-flat-network",
                         "userguide/service/working-with-istio-on-non-flat-network",