Merge pull request #26 from Krishiv-Mahajan/failover-tutorial

karmada-bot · web-flow · commit 206330c203af · 2026-05-21T20:30:54.000+08:00
Update failover example scenario with detailed steps and dividing the setup into small interactive steps
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ You can enjoy tutorial experience about Karmada with following platforms.
 * Try [Installing Karmada on Kubernetes through the Karmada CLI](https://killercoda.com/karmada/scenario/karmada-CLI-installation-example).
 * Try [Propagate workload through karmada duplicated mode](https://killercoda.com/karmada/scenario/karmada-HA-Duplicated-Scheduling).
 * Try [Propagate workload through karmada divided mode](https://killercoda.com/karmada/scenario/karmada-HA-workload-staticweight).
-* Try [Simulate multitype cluster failover through Karmada](https://killercoda.com/karmada/scenario/karmada-Failover-example).
+* Try [Simulate multitype cluster failover through Karmada](https://killercoda.com/karmada/scenario/karmada-Cluster-Failover-example).
 
 
 ## Contribution
diff --git a/karmada-Cluster-Failover-example/finish.md b/karmada-Cluster-Failover-example/finish.md
diff --git a/karmada-Cluster-Failover-example/foreground.sh b/karmada-Cluster-Failover-example/foreground.sh
@@ -136,23 +136,5 @@ cd nginx
 nginxDeployment
 propagationPolicy
 
-# create cluster in node01 machine
-ssh -o StrictHostKeyChecking=no root@${member_cluster_ip} "bash ~/installKind.sh" &
-sleep 10
-ssh -o StrictHostKeyChecking=no root@${member_cluster_ip} "bash ~/createCluster.sh" &
-sleep 90
-
-# install karmadactl
-curl -s https://raw.githubusercontent.com/karmada-io/karmada/master/hack/install-cli.sh | sudo bash
-
-# init karmada, and enable Failover feature gate and eviction feature
-karmadactl init --karmada-controller-manager-extra-args="--feature-gates=Failover=true,--enable-no-execute-taint-eviction=true"
-
-# join member clusters
-MEMBER_CLUSTER_NAME=kind-member1
-karmadactl --kubeconfig /etc/karmada/karmada-apiserver.config  join ${MEMBER_CLUSTER_NAME} --cluster-kubeconfig=$HOME/.kube/config-member1 --cluster-context=kind-member1
-MEMBER_CLUSTER_NAME=kind-member2
-karmadactl --kubeconfig /etc/karmada/karmada-apiserver.config  join ${MEMBER_CLUSTER_NAME} --cluster-kubeconfig=$HOME/.kube/config-member2 --cluster-context=kind-member2
-
 # clean screen 
 clear
diff --git a/karmada-Cluster-Failover-example/image/success.png b/karmada-Cluster-Failover-example/image/success.png
diff --git a/karmada-Cluster-Failover-example/index.json b/karmada-Cluster-Failover-example/index.json
@@ -8,23 +8,44 @@
       },
       "steps": [
         {
-          "title": "Check member cluster has been joined",
+          "title": "Environment overview",
           "text": "step1/text.md",
           "verify": "step1/verify.sh"
         },
         {
-          "title": "Check workloads has been deployed",
+          "title": "Install karmadactl",
           "text": "step2/text.md",
           "verify": "step2/verify.sh"
         },
         {
-          "title": "Simulate cluster failure",
+          "title": "Initialize Karmada control plane",
           "text": "step3/text.md",
           "verify": "step3/verify.sh"
         },
+        {
+          "title": "Prepare member clusters",
+          "text": "step4/text.md",
+          "verify": "step4/verify.sh"
+        },
+        {
+          "title": "Join member clusters to the host cluster",
+          "text": "step5/text.md",
+          "verify": "step5/verify.sh"
+        },
+        {
+          "title": "Create deployment",
+          "text": "step6/text.md",
+          "verify": "step6/verify.sh"
+        },
+        {
+          "title": "Simulate cluster failure",
+          "text": "step7/text.md",
+          "verify": "step7/verify.sh"
+        },
         {
           "title": "Check the status and quantity distribution of pods and deployments",
-          "text": "step4/text.md"
+          "text": "step8/text.md",
+          "verify": "step8/verify.sh"
         }
       ],
       "finish": {
diff --git a/karmada-Cluster-Failover-example/intro.md b/karmada-Cluster-Failover-example/intro.md
diff --git a/karmada-Cluster-Failover-example/step1/text.md b/karmada-Cluster-Failover-example/step1/text.md
@@ -0,0 +1,13 @@
+### Environment overview
+
+The environment consists of two hosts:
+
+1. `controlplane`: The host Kubernetes cluster where Karmada runs. The kubeconfig files for the host cluster are located in the `$HOME/.kube` directory.
+2. `node01`: Used to create member clusters.
+
+| HostName | Host IP |
+| --- | --- |
+| controlplane | 172.30.1.2 |
+| node01 | 172.30.2.2 |
+
+Note: The current terminal is on the host `controlplane`.
diff --git a/karmada-Cluster-Failover-example/step1/verify.sh b/karmada-Cluster-Failover-example/step1/verify.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+set -e
+
+test -f "$HOME/.kube/config"
diff --git a/karmada-Cluster-Failover-example/step2/text.md b/karmada-Cluster-Failover-example/step2/text.md
@@ -0,0 +1,13 @@
+### Install karmadactl
+
+**Install `karmadactl`:**
+
+RUN `curl -s https://raw.githubusercontent.com/karmada-io/karmada/master/hack/install-cli.sh | sudo bash`{{exec}}
+
+This downloads and installs the `karmadactl` CLI tool from the official Karmada repository.
+
+**Verify installation:**
+
+RUN `karmadactl version`{{exec}}
+
+This confirms that `karmadactl` is installed correctly and shows the installed version.
diff --git a/karmada-Cluster-Failover-example/step2/verify.sh b/karmada-Cluster-Failover-example/step2/verify.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+set -e
+
+karmadactl version
diff --git a/karmada-Cluster-Failover-example/step3/text.md b/karmada-Cluster-Failover-example/step3/text.md
@@ -0,0 +1,21 @@
+### Initialize Karmada control plane
+
+**Initialize Karmada control plane:**
+
+You need to enable both the `Failover` feature gate and the `eviction` feature to use cluster failover.
+
+When deploying Karmada with `karmadactl init`, append this parameter:
+
+`--karmada-controller-manager-extra-args="--feature-gates=Failover=true,--enable-no-execute-taint-eviction=true"`
+
+You may also manually modify the `karmada-controller-manager` configuration post-installation.
+
+RUN `karmadactl init --karmada-controller-manager-extra-args="--feature-gates=Failover=true,--enable-no-execute-taint-eviction=true"`{{exec}}
+
+This sets up the Karmada control plane on the host cluster, including API server and controllers.
+
+**Verify initialization:**
+
+RUN `kubectl --kubeconfig /etc/karmada/karmada-apiserver.config config get-contexts karmada-apiserver`{{exec}}
+
+This ensures that the Karmada API server context is available and configured correctly.
diff --git a/karmada-Cluster-Failover-example/step3/verify.sh b/karmada-Cluster-Failover-example/step3/verify.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+set -e
+
+kubectl --kubeconfig /etc/karmada/karmada-apiserver.config config get-contexts karmada-apiserver
diff --git a/karmada-Cluster-Failover-example/step4/text.md b/karmada-Cluster-Failover-example/step4/text.md
@@ -0,0 +1,21 @@
+### Prepare member clusters
+
+**Install Kind on the member node:**
+
+RUN `ssh -o StrictHostKeyChecking=no root@172.30.2.2 "bash ~/installKind.sh"`{{exec}}
+
+This command connects to node01 via SSH and installs Kind (Kubernetes in Docker), which is used to create local Kubernetes clusters.
+
+**Create two clusters (`member1` and `member2`):**
+
+RUN `ssh -o StrictHostKeyChecking=no root@172.30.2.2 "bash ~/createCluster.sh"`{{exec}}
+
+This creates two Kubernetes clusters (`member1` and `member2`) and copies their kubeconfig files back to the host node.
+
+> **Note:** This step may take **1–2 minutes** — wait for the prompt to return before proceeding.
+
+**Verify clusters were created:**
+
+RUN `ssh -o StrictHostKeyChecking=no root@172.30.2.2 "kind get clusters"`{{exec}}
+
+Both `member1` and `member2` should appear in the output.
diff --git a/karmada-Cluster-Failover-example/step4/verify.sh b/karmada-Cluster-Failover-example/step4/verify.sh
@@ -0,0 +1,6 @@
+#!/bin/bash
+set -e
+
+clusters=$(ssh -o StrictHostKeyChecking=no root@172.30.2.2 "kind get clusters")
+echo "$clusters" | grep -x member1
+echo "$clusters" | grep -x member2
diff --git a/karmada-Cluster-Failover-example/step5/text.md b/karmada-Cluster-Failover-example/step5/text.md
@@ -0,0 +1,30 @@
+### Join member clusters to the host cluster
+
+1. Join `kind-member1` and `kind-member2` to the host cluster.
+
+   RUN `MEMBER_CLUSTER_NAME=kind-member1`{{exec}}
+
+   This sets the variable `MEMBER_CLUSTER_NAME` to `kind-member1` for use in the join command.
+
+   RUN `karmadactl --kubeconfig /etc/karmada/karmada-apiserver.config join ${MEMBER_CLUSTER_NAME} --cluster-kubeconfig=$HOME/.kube/config-member1 --cluster-context=kind-member1`{{exec}}
+
+   This joins the `kind-member1` cluster to the Karmada control plane using its kubeconfig file and context.
+
+   RUN `MEMBER_CLUSTER_NAME=kind-member2`{{exec}}
+
+   This sets the variable to `kind-member2` for the second cluster join.
+
+   RUN `karmadactl --kubeconfig /etc/karmada/karmada-apiserver.config join ${MEMBER_CLUSTER_NAME} --cluster-kubeconfig=$HOME/.kube/config-member2 --cluster-context=kind-member2`{{exec}}
+
+   This joins the `kind-member2` cluster to the Karmada control plane using its respective kubeconfig file and context.
+
+2. Check Karmada resources.
+
+   RUN `kubectl --kubeconfig /etc/karmada/karmada-apiserver.config get clusters`{{exec}}
+
+   This command lists all the member clusters that have successfully joined the Karmada control plane.
+3. The following image shows the expected output, indicating that the member clusters have been joined successfully.
+
+![Joined clusters](../image/success.png)
+
+**Note:** If a join command fails due to a transient issue, rerun that specific join command.
diff --git a/karmada-Cluster-Failover-example/step5/verify.sh b/karmada-Cluster-Failover-example/step5/verify.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+set -e
+
+kubectl --kubeconfig /etc/karmada/karmada-apiserver.config get clusters kind-member1 && kubectl --kubeconfig /etc/karmada/karmada-apiserver.config get clusters kind-member2
diff --git a/karmada-Cluster-Failover-example/step6/text.md b/karmada-Cluster-Failover-example/step6/text.md
@@ -0,0 +1,80 @@
+### Create deployment
+
+Create a deployment named `nginx`.
+
+RUN `kubectl --kubeconfig /etc/karmada/karmada-apiserver.config apply -f ~/nginx/nginxDeployment.yaml`{{exec}}
+
+<details>
+<summary>nginxDeployment.yaml</summary>
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+  labels:
+    app: nginx
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+        - name: nginx
+          image: nginx
+```
+
+</details>
+
+RUN `kubectl --kubeconfig /etc/karmada/karmada-apiserver.config apply -f ~/nginx/propagationPolicy.yaml`{{exec}}
+
+<details>
+<summary>propagationPolicy.yaml</summary>
+
+```yaml
+apiVersion: policy.karmada.io/v1alpha1
+kind: PropagationPolicy
+metadata:
+  name: nginx-propagation
+spec:
+  resourceSelectors:
+    - apiVersion: apps/v1
+      kind: Deployment
+      name: nginx
+  placement:
+    clusterAffinity:
+      clusterNames:
+        - kind-member1
+        - kind-member2
+    replicaScheduling:
+      replicaDivisionPreference: Weighted
+      replicaSchedulingType: Divided
+      weightPreference:
+        staticWeightList:
+          - targetCluster:
+              clusterNames:
+                - kind-member1
+            weight: 2
+          - targetCluster:
+              clusterNames:
+                - kind-member2
+            weight: 1
+```
+
+</details>
+
+Check deployments and pods and their distribution across member clusters:
+
+RUN `karmadactl --kubeconfig /etc/karmada/karmada-apiserver.config get deployment --operation-scope members`{{exec}}
+
+RUN `karmadactl --kubeconfig /etc/karmada/karmada-apiserver.config get pods --operation-scope members`{{exec}}
+
+- You should see that the deployment is created and pods are running on both member clusters as per the propagation policy.
+- Their distribution should be: kind-member1: 2 pods, kind-member2: 1 pods.
+
+> **Note:** If the expected output doesn't appear, wait for 30 seconds to 1 minute and try again.
diff --git a/karmada-Cluster-Failover-example/step6/verify.sh b/karmada-Cluster-Failover-example/step6/verify.sh
@@ -1,3 +1,5 @@
 #!/bin/bash
 
+set -e
+
 kubectl --kubeconfig /etc/karmada/karmada-apiserver.config get deployment nginx
diff --git a/karmada-Cluster-Failover-example/step7/text.md b/karmada-Cluster-Failover-example/step7/text.md
@@ -0,0 +1,5 @@
+### Simulate cluster failure
+
+RUN `karmadactl --kubeconfig /etc/karmada/karmada-apiserver.config taint cluster kind-member2 failover-test:NoExecute`{{exec}}
+
+This adds a taint to the member cluster `kind-member2` to simulate a failure.
diff --git a/karmada-Cluster-Failover-example/step7/verify.sh b/karmada-Cluster-Failover-example/step7/verify.sh
@@ -1,5 +1,7 @@
 #!/bin/bash
 
+set -e
+
 taint_effect=$(kubectl --kubeconfig /etc/karmada/karmada-apiserver.config get cluster kind-member2 -o jsonpath='{.spec.taints[?(@.key=="failover-test")].effect}')
 if [ "$taint_effect" == "NoExecute" ]; then
 		echo "Taint applied successfully to kind-member2."
diff --git a/karmada-Cluster-Failover-example/step8/text.md b/karmada-Cluster-Failover-example/step8/text.md
diff --git a/karmada-Cluster-Failover-example/step8/verify.sh b/karmada-Cluster-Failover-example/step8/verify.sh
@@ -0,0 +1,25 @@
+#!/bin/bash
+
+set -e
+
+pod_counts=$(karmadactl --kubeconfig /etc/karmada/karmada-apiserver.config get pods --operation-scope members | awk '
+NR > 1 && $1 ~ /^nginx-/ {
+	if ($2 == "kind-member1") {
+		member1++
+	} else if ($2 == "kind-member2") {
+		member2++
+	}
+}
+END {
+	print member1 + 0, member2 + 0
+}')
+
+member1_pod_count=$(echo "$pod_counts" | awk '{print $1}')
+member2_pod_count=$(echo "$pod_counts" | awk '{print $2}')
+
+if [ "$member1_pod_count" -eq 3 ] && [ "$member2_pod_count" -eq 0 ]; then
+		echo "Pods are scheduled to kind-member1 and absent from kind-member2."
+else
+		echo "Unexpected pod distribution: kind-member1=$member1_pod_count, kind-member2=$member2_pod_count."
+		exit 1
+fi
diff --git a/karmada-Failover-example/step1/text.md b/karmada-Failover-example/step1/text.md
diff --git a/karmada-Failover-example/step1/verify.sh b/karmada-Failover-example/step1/verify.sh
diff --git a/karmada-Failover-example/step2/text.md b/karmada-Failover-example/step2/text.md
diff --git a/karmada-Failover-example/step3/text.md b/karmada-Failover-example/step3/text.md

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +#!/bin/bash
++
 +set -e
++
 +test -f "$HOME/.kube/config"