doc: migrate existing resource from a cluster to Karmada.

Signed-off-by: chaosi-zju <chaosi@zju.edu.cn>

docs/administrator/migration/migrate-in-batch.md

@@ -0,0 +1,97 @@
+---
+title: Migrate In Batch
+---
+
+## Scenario
+
+Assuming the user has a single kubernetes cluster which already has many native resource installed.
+
+The user want to install Karmada for multi-cluster management, and hope to migrate the resource that already exist from original cluster to Karmada.
+It is required that the pods already exist not be affected during the process of migration, which means the relevant container not be restarted.
+
+So, how to migrate the existing resource?
+
+![](../../resources/administrator/migrate-in-batch-1.jpg)
+
+## Recommended migration strategy
+
+If you only want to migrate individual resources, you can just refer to [promote-legacy-workload](./promote-legacy-workload) to do it one by one.
+
+If you want to migrate a batch of resources, you are advised to take over all resources based on resource granularity through few `PropagationPolicy` at first,
+then if you have more propagate demands based on application granularity, you can apply higher priority `PropagationPolicy` to preempt them.
+
+Thus, how to take over all resources based on resource granularity? You can do as follows.
+
+![](../../resources/administrator/migrate-in-batch-2.jpg)
+
+### Step one
+
+Since the existing resources will be token over by Karmada, there is no longer need to apply the related YAML config to member cluster.
+That means, you can stop the corresponding operation or pipeline.
+
+### Step two
+
+Apply all the YAML config of resources to Karmada control plane, as the [ResourceTemplate](https://karmada.io/docs/core-concepts/concepts#resource-template) of Karmada.
+
+### Step three
+
+Edit a [PropagationPolicy](https://karmada.io/docs/core-concepts/concepts#propagation-policy), and apply it to Karmada control plane. You should pay attention to two fields：
+
+* `spec.conflictResolution: Overwrite`：**the value must be [Overwrite](https://github.com/karmada-io/karmada/blob/master/docs/proposals/migration/design-of-seamless-cluster-migration-scheme.md#proposal).**
+* `spec.resourceSelectors`：defining which resources are selected to migrate
+
+here we provide two examples：
+
+#### Eg1. migrate all deployments
+
+If you want to migrate all deployments from `member1` cluster to Karmada, you shall apply:
+
+```yaml
+apiVersion: policy.karmada.io/v1alpha1
+kind: PropagationPolicy
+metadata:
+  name: deployments-pp
+spec:
+  conflictResolution: Overwrite
+  placement:
+    clusterAffinity:
+      clusterNames:
+      - member1
+  priority: 0
+  resourceSelectors:
+  - apiVersion: apps/v1
+    kind: Deployment
+  schedulerName: default-scheduler
+```
+
+#### Eg2. migrate all services
+
+If you want to migrate all services from `member1` cluster to Karmada, you shall apply:
+
+```yaml
+apiVersion: policy.karmada.io/v1alpha1
+kind: PropagationPolicy
+metadata:
+  name: services-pp
+spec:
+  conflictResolution: Overwrite
+  placement:
+    clusterAffinity:
+      clusterNames:
+      - member1
+  priority: 0
+  resourceSelectors:
+  - apiVersion: v1
+    kind: Service
+  schedulerName: default-scheduler
+```
+
+### Step four
+
+The rest migration operations will be finished by Karmada automatically.
+
+## PropagationPolicy Preemption and Demo
+
+Besides, if you have more propagate demands based on application granularity, you can apply higher priority `PropagationPolicy` 
+to preempt those you applied in the migration mentioned above. Detail demo you can refer to the tutorial [Resource Migration](../../tutorials/resource-migration.md)
+

docs/tutorials/resource-migration.md

@@ -0,0 +1,235 @@
+---
+title: Resource Migration
+---
+
+## Objectives
+
+Assuming you have a single kubernetes cluster which already has many native resource installed, furthermore, 
+you want to migrate the existing resource to Karmada and then achieve multi-cluster management. 
+
+So, this section will guide you to cover:
+
+- Migrate all the existing resource from original cluster to Karmada based on resource granularity.
+- Apply higher priority `PropagationPolicy` to meet more propagate demands based on application granularity.
+
+## Prerequisites
+
+### Karmada with multi cluster has been installed
+
+**Step 1: Run the command**
+
+```shell
+$ git clone https://github.com/karmada-io/karmada
+$ cd karmada
+$ hack/local-up-karmada.sh
+$ export KUBECONFIG=~/.kube/karmada.config:~/.kube/members.config
+```
+
+**Note:**
+
+Before guide started, we should install at least three kubernetes clusters, one is for Karmada control plane, the other two for business clusters.
+For convenience, we use [hack/local-up-karmada.sh](https://karmada.io/docs/installation/#install-karmada-for-development-environment) script to quickly prepare the above clusters.
+
+After the above command executed, you will see Karmada control plane installed with multi members clusters.
+
+### Enable PropagationPolicyPreemption in karmada-controller-manager
+
+**Step 2: Run the command**
+
+```shell
+$ kubectl --context karmada-host get deploy karmada-controller-manager -n karmada-system -o yaml | sed '/- --failover-eviction-timeout=30s/{n;s/- --v=4/- --feature-gates=PropagationPolicyPreemption=true\n        &/g}' | kubectl --context karmada-host replace -f -
+```
+
+**Note:**
+
+The feature `PropagationPolicy Priority and Preemption` was introduced in v1.7, and it is controlled by the feature gate `PropagationPolicyPreemption` which is disabled by default.
+
+You can just execute the above one command to enable this feature gate. Or, if you want to use a more cautious approach, you can do like this:
+
+1. execute `kubectl --context karmada-host edit deploy karmada-controller-manager -n karmada-system` 
+2. check if feature gate `--feature-gates=PropagationPolicyPreemption=true` is existed in `spec.template.spec.containers[0].command` field.
+3. If not, you shall add `--feature-gates=PropagationPolicyPreemption=true` into that field.
+
+### Preset resource in a member cluster
+
+To simulate resources already exist in the member cluster, we deploy some simple Deployments and Services to `member1` cluster.
+
+**Step 3: Write the code**
+
+Create new file `/tmp/deployments-and-services.yaml` and copy text below to it:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx-deploy
+spec:
+  selector:
+    matchLabels:
+      app: nginx
+  replicas: 2
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:latest
+        ports:
+        - containerPort: 80
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: nginx-svc
+spec:
+  selector:
+    app: nginx
+  type: NodePort
+  ports:
+  - port: 80
+    nodePort: 30000
+    targetPort: 80
+```
+
+**Step 4: Run the command**
+
+```shell
+$ kubectl --context member1 apply -f /tmp/deployments-and-services.yaml
+deployment.apps/nginx-deploy created
+service/nginx-svc created
+deployment.apps/hello-deploy created
+service/hello-svc created
+```
+
+Thus, we can use `member1` as the cluster with existing resources, while `member2` as a bare cluster.
+
+## Tutorials
+
+### Migrate all the resources to Karmada
+
+1）Apply the local file `/tmp/deployments-and-services.yaml` written just now to Karmada control plane too.
+
+**Step 5: Run the command**
+
+```shell
+➜ ✗ kubectl --context karmada-apiserver apply -f /tmp/deployments-and-services.yaml
+deployment.apps/nginx-deploy created
+service/nginx-svc created
+deployment.apps/hello-deploy created
+service/hello-svc created
+```
+
+2）Write a `PropagationPolicy` to the local file `/tmp/pp-for-migrating-deployments-and-services.yaml`.
+
+**Step 6: Write the code**
+
+Create new file `/tmp/pp-for-migrating-deployments-and-services.yaml` and copy text below to it:
+
+```yaml
+apiVersion: policy.karmada.io/v1alpha1
+kind: PropagationPolicy
+metadata:
+  name: migrate-pp
+spec:
+  conflictResolution: Overwrite
+  placement:
+    clusterAffinity:
+      clusterNames:
+      - member1
+  priority: 0
+  resourceSelectors:
+  - apiVersion: apps/v1
+    kind: Deployment
+  - apiVersion: v1
+    kind: Service
+  schedulerName: default-scheduler
+```
+
+**Note:**
+
+You should pay attention to two fields： 
+
+* `spec.conflictResolution: Overwrite`：the value must be [Overwrite](https://github.com/karmada-io/karmada/blob/master/docs/proposals/migration/design-of-seamless-cluster-migration-scheme.md#proposal).
+* `spec.resourceSelectors`：selecting resources to migrate, you can define your custom [ResourceSelector](https://karmada.io/docs/userguide/scheduling/override-policy/#resource-selector).
+
+3）Apply `/tmp/pp-for-migrating-deployments-and-services.yaml` to Karmada control plane. 
+
+**Step 7: Run the command**
+
+```shell
+$ kubectl --context karmada-apiserver apply -f /tmp/pp-for-migrating-deployments-and-services.yaml
+propagationpolicy.policy.karmada.io/migrate-pp created
+```
+
+Now, you have finished the migration, isn't it so easy? 
+
+4）Verification
+
+**Step 8: Run the command**
+
+```shell
+$ kubectl --context karmada-apiserver get deploy
+$ kubectl --context karmada-apiserver get rb
+```
+
+You can see the Deployments in Karmada are all ready and the `aggregatedStatus` of `ResourceBinding` is applied.
+
+### Apply higher priority PropagationPolicy
+
+1）Write a high priority `PropagationPolicy` to the local file `/tmp/pp-for-nginx-app.yaml`.
+
+**Step 9: Write the code**
+
+Create new file `/tmp/pp-for-nginx-app.yaml` and copy text below to it:
+
+```yaml
+apiVersion: policy.karmada.io/v1alpha1
+kind: PropagationPolicy
+metadata:
+  name: nginx-pp
+spec:
+  conflictResolution: Overwrite
+  placement:
+    clusterAffinity:
+      clusterNames:
+      - member1
+      - member2                          ## focus on this line
+  priority: 10
+  preemption: Always                     ## focus on this line
+  resourceSelectors:
+  - apiVersion: apps/v1
+    kind: Deployment
+    name: nginx-deploy
+  - apiVersion: v1
+    kind: Service
+    name: nginx-svc
+  schedulerName: default-scheduler
+```
+
+2）Apply `/tmp/pp-for-nginx-app.yaml` to Karmada control plane. 
+
+**Step 10: Run the command**
+
+```shell
+$ kubectl --context karmada-apiserver apply -f /tmp/pp-for-nginx-app.yaml
+propagationpolicy.policy.karmada.io/nginx-pp created
+```
+
+3）Verification
+
+**Step 11: Run the command**
+
+```shell
+$ kubectl --context member2 get deploy -o wide 
+NAME           READY   UP-TO-DATE   AVAILABLE   AGE     CONTAINERS   IMAGES         SELECTOR
+nginx-deploy   2/2     2            2           5m24s   nginx        nginx:latest   app=nginx
+$ kubectl --context member2 get svc -o wide   
+NAME         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE   SELECTOR
+nginx-svc    NodePort    10.13.161.255   <none>        80:30000/TCP   54s   app=nginx
+...
+```
+
+As you see, you would find `nginx` application related resource are all propagated to `member2` cluster, 
+which means the higher priority `PropagationPolicy` does work.

sidebars.js

@@ -34,6 +34,7 @@ module.exports = {
                 "tutorials/autoscaling-with-custom-metrics",
                 "tutorials/autoscaling-federatedhpa-with-cronfederatedhpa",
                 "tutorials/autoscaling-workload-with-cronfederatedhpa",
+                "tutorials/resource-migration",
             ],
         },
         {
@@ -161,6 +162,7 @@ module.exports = {
                     items: [
                         "administrator/migration/promote-legacy-workload",
                         "administrator/migration/migration-from-kubefed",
+                        "administrator/migration/migrate-in-batch",
                     ],
                 },
                 {