diff --git a/docs/tutorials/resource-migration.md b/docs/tutorials/resource-migration.md index 2a7a5cbd..0071949a 100644 --- a/docs/tutorials/resource-migration.md +++ b/docs/tutorials/resource-migration.md @@ -1,5 +1,5 @@ --- -title: Resource Migration +title: Resource Migration and Rollback --- ## Objectives @@ -9,8 +9,8 @@ you want to migrate the existing resource to Karmada and then achieve multi-clus 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. +- Migrate application from Kubernetes to Karmada. +- Rollback application migration. ## Prerequisites @@ -32,31 +32,13 @@ export KUBECONFIG=~/.kube/karmada.config:~/.kube/members.config > > After the above command executed, you will see Karmada control plane installed with multi member 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 member cluster, we deploy some simple Deployments and Services to `member1` cluster. +To simulate resources already exist in member cluster, we deploy simple Deployment to `member1` cluster. -#### Step 3: Write the code +#### Step 2: Write the code -Create new file `/tmp/deployments-and-services.yaml` and copy text below to it: +Create new file `/tmp/deployments.yaml` and copy text below to it: ```yaml apiVersion: apps/v1 @@ -78,54 +60,47 @@ spec: 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 +### Step 3: Run the command ```shell -$ kubectl --context member1 apply -f /tmp/deployments-and-services.yaml +$ kubectl --context member1 apply -f /tmp/deployments.yaml deployment.apps/nginx-deploy created -service/nginx-svc created -deployment.apps/hello-deploy created -service/hello-svc created + +$ karmadactl --karmada-context karmada-apiserver get deploy --operation-scope=all +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx-deploy member1 2/2 2 2 15m N ``` -Thus, we can use `member1` as the cluster with existing resources, while `member2` as a bare cluster. +You will see the current `nginx-deploy` deployment in the member1 cluster, +with `ADOPTION=N` indicating it is not currently managed by Karmada. ## Tutorials -### Migrate all the resources to Karmada +### Migrate application to Karmada + +To make the tutorial simpler and easier to understand, +here we assume the application example contains only a single simple deployment. #### Step 1: Run the command ```shell -$ kubectl --context karmada-apiserver apply -f /tmp/deployments-and-services.yaml +$ kubectl --context karmada-apiserver apply -f /tmp/deployments.yaml deployment.apps/nginx-deploy created -service/nginx-svc created -deployment.apps/hello-deploy created -service/hello-svc created + +$ karmadactl --karmada-context karmada-apiserver get deploy --operation-scope=all +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx-deploy Karmada 0/2 0 0 7s - +nginx-deploy member1 2/2 2 2 16m N ``` -> **Note：** -> -> Same Deployments and Services should be deployed to Karmada control plane as [ResourceTemplate](https://karmada.io/docs/core-concepts/concepts#resource-template). +You will see that the Deployment has been deployed to the Karmada control plane as a [ResourceTemplate](https://karmada.io/docs/core-concepts/concepts#resource-template), +but there is currently no matching PropagationPolicy to propagate it. #### Step 2: Write the code -Create new file `/tmp/pp-for-migrating-deployments-and-services.yaml` and copy text below to it: +Create new file `/tmp/pp-for-migrating-deployments.yaml` and copy text below to it: ```yaml apiVersion: policy.karmada.io/v1alpha1 @@ -138,98 +113,83 @@ spec: clusterAffinity: clusterNames: - member1 - priority: 0 resourceSelectors: - apiVersion: apps/v1 kind: Deployment - - apiVersion: v1 - kind: Service - schedulerName: default-scheduler + name: nginx-deploy ``` > **Note:** > -> You should pay attention to two fields： +> 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). -#### Step 3: Run the command +#### Step 3: Run the Command -Apply this PropagationPolicy to Karmada control plane. +Apply the above PropagationPolicy to the Karmada control plane: ```shell -$ kubectl --context karmada-apiserver apply -f /tmp/pp-for-migrating-deployments-and-services.yaml +$ kubectl --context karmada-apiserver apply -f /tmp/pp-for-migrating-deployments.yaml propagationpolicy.policy.karmada.io/migrate-pp created ``` #### Step 4: Verification ```shell -$ kubectl --context karmada-apiserver get deploy -NAME READY UP-TO-DATE AVAILABLE AGE -nginx-deploy 2/2 2 2 38s -$ kubectl --context karmada-apiserver get rb -NAME SCHEDULED FULLYAPPLIED AGE -nginx-deploy-deployment True True 13s -nginx-svc-service True True 13s +$ karmadactl --karmada-context karmada-apiserver get deploy --operation-scope=all +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx-deploy Karmada 2/2 2 2 34s - +nginx-deploy member1 2/2 2 2 16m Y + +$ karmadactl --karmada-context karmada-apiserver get pods --operation-scope=all +NAME CLUSTER READY STATUS RESTARTS AGE +nginx-deploy-54b9c68f67-4qjrz member1 1/1 Running 0 16m +nginx-deploy-54b9c68f67-f4qpm member1 1/1 Running 0 16m ``` -You shall see the Deployments in Karmada are all ready and the `aggregatedStatus` of `ResourceBinding` is applied, -which means the existing resources in `member1` cluster has been taken over by Karmada. +You will see that all Deployments are ready, +which means `nginx-deploy` in the member1 cluster is successfully taken over by Karmada: -So far, you have finished the migration, isn't it so easy? +* `AGE=16m` indicates the resource is taken over rather than recreated, with corresponding pods no need to be restarted. +* `ADOPTION=Y` indicates that the resource is now managed by Karmada. -### Apply higher priority PropagationPolicy +You have now completed the migration. -#### Step 5: Write the code +### Rollback Migration -Create new file `/tmp/pp-for-nginx-app.yaml` and copy text below to it: +#### Step 5: Set preserveResourcesOnDeletion for PropagationPolicy -```yaml -apiVersion: policy.karmada.io/v1alpha1 -kind: PropagationPolicy -metadata: - name: nginx-pp -spec: - conflictResolution: Overwrite - placement: - clusterAffinity: - clusterNames: - - member1 - - member2 ## propagate to more clusters other than member1 - priority: 10 ## priority greater than above PropagationPolicy (10 > 0) - preemption: Always ## preemption should equal to Always - resourceSelectors: - - apiVersion: apps/v1 - kind: Deployment - name: nginx-deploy - - apiVersion: v1 - kind: Service - name: nginx-svc - schedulerName: default-scheduler +Run the following command to modify `PropagationPolicy/migrate-pp`, setting `spec.preserveResourcesOnDeletion=true`: + +```shell +$ kubectl --context karmada-apiserver patch pp migrate-pp --type='json' -p '[{"op": "replace", "path": "/spec/preserveResourcesOnDeletion", "value": true}]' +propagationpolicy.policy.karmada.io/nginx-pp patched ``` -#### Step 6: Run the command +#### Step 6: Delete the Resource Template from the Control Plane -Apply this higher priority PropagationPolicy to Karmada control plane. +Run the following command: ```shell -$ kubectl --context karmada-apiserver apply -f /tmp/pp-for-nginx-app.yaml -propagationpolicy.policy.karmada.io/nginx-pp created +$ kubectl --context karmada-apiserver delete -f /tmp/deployments.yaml +deployment.apps "nginx-deploy" deleted ``` #### Step 7: Verification +Run the following 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 80:30000/TCP 54s app=nginx +$ karmadactl --karmada-context karmada-apiserver get deploy --operation-scope=all +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx-deploy member1 2/2 2 2 17m N ... ``` -As you see, you shall find `nginx` application related resource are all propagated to `member2` cluster, -which means the higher priority `PropagationPolicy` does work. \ No newline at end of file +You will see that the resource template in the control plane has been deleted, +and the resources in the member clusters remain intact, +with `ADOPTION=N` indicating that the resource is not managed by Karmada. + +You have now completed the migration rollback. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/resource-migration.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/resource-migration.md index acc023f4..95bcdefe 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/resource-migration.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/resource-migration.md @@ -1,5 +1,5 @@ --- -title: 平滑迁移 +title: 平滑迁移及回滚 --- ## 目标 @@ -8,8 +8,8 @@ title: 平滑迁移 在此背景下，本节将引导您完成： -- 以资源为粒度将所有已部署资源从原集群迁移到 Karmada。 -- 应用更高优先级的 `PropagationPolicy`，以满足以应用为粒度的更多分发需求。 +- 将应用从单集群迁移到 Karmada。 +- 回滚应用的迁移。 ## 前提条件 @@ -31,31 +31,13 @@ export KUBECONFIG=~/.kube/karmada.config:~/.kube/members.config > > 执行上述命令后，您将看到Karmada控制面和多个成员集群已安装完成。 -### 在 karmada-controller-manager 开启 PropagationPolicyPreemption 特性开关 - -#### 步骤二: 运行命令 - -```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 - -``` - -> **说明：** -> -> `PropagationPolicy Priority and Preemption` 特性是在 v1.7 版本中引入的，它由特性开关 `PropagationPolicyPreemption` 控制，默认是关闭的。 -> -> 您只需执行上面的一条命令即可启用此特性开关。或者，如果您想使用更谨慎的方法，您可以这样做： -> -> 1. 执行 `kubectl --context karmada-host edit deploy karmada-controller-manager -n karmada-system`。 -> 2. 检查 `spec.template.spec.containers[0].command` 字段是否有 `--feature-gates=PropagationPolicyPreemption=true` 这一行。 -> 3. 如果没有，您需要添加 `--feature-gates=PropagationPolicyPreemption=true` 到上述字段中。 - ### 在成员集群中预置资源 -为了模拟成员集群中已经存在现有资源，我们将一些简单的 Deployment 和 Service 部署到 `member1` 集群。 +为了模拟成员集群中已经存在现有资源，我们将简单的 Deployment 部署到 `member1` 集群。 -#### 步骤三: 编写代码 +#### 步骤二: 编写代码 -创建新文件 `/tmp/deployments-and-services.yaml` 并写入以下文本： +创建新文件 `/tmp/deployments.yaml` 并写入以下文本： ```yaml apiVersion: apps/v1 @@ -77,54 +59,45 @@ spec: 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 ``` -#### 步骤四: 运行命令 +#### 步骤三: 运行命令 ```shell -$ kubectl --context member1 apply -f /tmp/deployments-and-services.yaml +$ kubectl --context member1 apply -f /tmp/deployments.yaml deployment.apps/nginx-deploy created -service/nginx-svc created -deployment.apps/hello-deploy created -service/hello-svc created + +$ karmadactl --karmada-context karmada-apiserver get deploy --operation-scope=all +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx-deploy member1 2/2 2 2 15m N ``` -因此，我们可以使用 `member1` 作为已部署现有资源的集群。 +您将看到当前 `nginx-deploy` 部署在 member1 集群，`ADOPTION=N` 表示它此时不是由 Karmada 管理 ## 指导 -### 将所有资源迁移到 Karmada +### 将应用迁移到 Karmada + +为了使教程更简单易懂，假设应用仅由上述一个简单的 Deployment 构成。 #### 步骤一: 运行命令 ```shell -$ kubectl --context karmada-apiserver apply -f /tmp/deployments-and-services.yaml +$ kubectl --context karmada-apiserver apply -f /tmp/deployments.yaml deployment.apps/nginx-deploy created -service/nginx-svc created -deployment.apps/hello-deploy created -service/hello-svc created + +$ karmadactl --karmada-context karmada-apiserver get deploy --operation-scope=all +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx-deploy Karmada 0/2 0 0 7s - +nginx-deploy member1 2/2 2 2 16m N ``` -> **说明：** -> -> 相同的 Deployments 和 Services 应被部署到 Karmada 控制面，作为 [ResourceTemplate](https://karmada.io/docs/core-concepts/concepts#resource-template)。 +您将看到该 Deployment 被部署到 Karmada 控制面，作为 [ResourceTemplate](https://karmada.io/docs/core-concepts/concepts#resource-template)， +此时尚无匹配的 PropagationPolicy 对其分发。 #### 步骤二: 编写代码 -创建新文件 `/tmp/pp-for-migrating-deployments-and-services.yaml` 并写入以下文本： +创建新文件 `/tmp/pp-for-migrating-deployments.yaml` 并写入以下文本： ```yaml apiVersion: policy.karmada.io/v1alpha1 @@ -137,13 +110,10 @@ spec: clusterAffinity: clusterNames: - member1 - priority: 0 resourceSelectors: - apiVersion: apps/v1 kind: Deployment - - apiVersion: v1 - kind: Service - schedulerName: default-scheduler + name: nginx-deploy ``` > **说明：** @@ -158,75 +128,61 @@ spec: 应用上述 `PropagationPolicy` 到 Karmada 控制面： ```shell -$ kubectl --context karmada-apiserver apply -f /tmp/pp-for-migrating-deployments-and-services.yaml +$ kubectl --context karmada-apiserver apply -f /tmp/pp-for-migrating-deployments.yaml propagationpolicy.policy.karmada.io/migrate-pp created ``` #### 步骤四: 验证 ```shell -$ kubectl --context karmada-apiserver get deploy -NAME READY UP-TO-DATE AVAILABLE AGE -nginx-deploy 2/2 2 2 38s -$ kubectl --context karmada-apiserver get rb -NAME SCHEDULED FULLYAPPLIED AGE -nginx-deploy-deployment True True 13s -nginx-svc-service True True 13s +$ karmadactl --karmada-context karmada-apiserver get deploy --operation-scope=all +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx-deploy Karmada 2/2 2 2 34s - +nginx-deploy member1 2/2 2 2 16m Y + +$ karmadactl --karmada-context karmada-apiserver get pods --operation-scope=all +NAME CLUSTER READY STATUS RESTARTS AGE +nginx-deploy-54b9c68f67-4qjrz member1 1/1 Running 0 16m +nginx-deploy-54b9c68f67-f4qpm member1 1/1 Running 0 16m ``` -您将看到 Karmada 中的 Deployment 已全部就绪，并且 `ResourceBinding` 的 `FULLYAPPLIED` 为 True，这表示 `member1` 集群中的现有资源已被 Karmada 接管。 +您将看到所有 Deployment 已就绪，并且 member1 集群的 `nginx-deploy` 成功被 Karmada 接管： -至此，您已经完成了迁移，是不是很简单？ +* `AGE=16m` 说明该资源是被接管而不是重新创建，相应的 pods 不会发生重启。 +* `ADOPTION=Y` 表示该资源现在由 Karmada 管理。 -### 应用更高优先级的 PropagationPolicy +至此，您已经完成了迁移。 -#### 步骤五: 编写代码 +### 迁移回滚 -创建新文件 `/tmp/pp-for-nginx-app.yaml` 并写入以下文本： +#### 步骤五: 对 PropagationPolicy 设置 preserveResourcesOnDeletion -```yaml -apiVersion: policy.karmada.io/v1alpha1 -kind: PropagationPolicy -metadata: - name: nginx-pp -spec: - conflictResolution: Overwrite - placement: - clusterAffinity: - clusterNames: - - member1 - - member2 ## propagate to more clusters other than member1 - priority: 10 ## priority greater than above PropagationPolicy (10 > 0) - preemption: Always ## preemption should equal to Always - resourceSelectors: - - apiVersion: apps/v1 - kind: Deployment - name: nginx-deploy - - apiVersion: v1 - kind: Service - name: nginx-svc - schedulerName: default-scheduler +执行下述命令修改 `PropagationPolicy/migrate-pp`，设置 `spec.preserveResourcesOnDeletion=true` + +```shell +$ kubectl --context karmada-apiserver patch pp migrate-pp --type='json' -p '[{"op": "replace", "path": "/spec/preserveResourcesOnDeletion", "value": true}]' +propagationpolicy.policy.karmada.io/nginx-pp patched ``` -#### 步骤六: 运行命令 +#### 步骤六：从控制面删除资源模板 -应用上述 `PropagationPolicy` 到 Karmada 控制面： +执行下述命令： ```shell -$ kubectl --context karmada-apiserver apply -f /tmp/pp-for-nginx-app.yaml -propagationpolicy.policy.karmada.io/nginx-pp created +$ kubectl --context karmada-apiserver delete -f /tmp/deployments.yaml +deployment.apps "nginx-deploy" deleted ``` -#### 步骤七: 验证 +#### 步骤七：验证 + +执行下述命令： ```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 80:30000/TCP 54s app=nginx -... +$ karmadactl --karmada-context karmada-apiserver get deploy --operation-scope=all +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx-deploy member1 2/2 2 2 17m N ``` -您将看到 `nginx` 应用相关的资源被分发到 `member2` 集群，这表示更高优先级的 `PropagationPolicy` 生效了。 \ No newline at end of file +您将看到，控制面的资源模板已删除，并且成员集群中的资源依然可以保留，`ADOPTION=N` 表示该资源当前不是由 Karmada 管理。 + +至此，您已经完成了迁移回滚。