fhpa-usage tutorial construction

Signed-off-by: Krishiv-Mahajan <mahajankrishiv10@gmail.com>

Author: Krishiv-Mahajan

karmada-FHPA-example/finish.md

@@ -0,0 +1,3 @@
+# Summary
+
+In this scenario, we installed metrics-server on member clusters and enabled the karmada-metrics-adapter on the control plane to provide CPU metrics for autoscaling, created a FederatedHPA resource to monitor CPU utilization across all member clusters and automatically adjust the number of replicas based on workload demand. To test the scaling behavior, we generated CPU load using the `williamyeh/hey` load-generator pod and observed the FederatedHPA trigger a scale-up event. After stopping the load generation, we also observed the FederatedHPA scale the workload back down automatically once CPU usage returned to normal.

karmada-FHPA-example/foreground.sh

@@ -0,0 +1,268 @@
+#!/usr/bin/env bash
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+# variable define
+kind_version=v0.17.0
+host_cluster_ip=172.30.1.2 #host node where Karmada is located
+member_cluster_ip=172.30.2.2
+local_ip=127.0.0.1
+KUBECONFIG_PATH=${KUBECONFIG_PATH:-"${HOME}/.kube"}
+
+function installKind() {
+    cat << EOF > installKind.sh
+    set -e
+    wget https://github.com/kubernetes-sigs/kind/releases/download/${kind_version}/kind-linux-amd64
+    chmod +x kind-linux-amd64
+    sudo mv kind-linux-amd64 /usr/local/bin/kind
+EOF
+}
+
+function createCluster() {
+    cat << EOF > createCluster.sh
+    set -e
+    kind delete cluster --name=member1 || true
+    kind create cluster --name=member1 --config=cluster1.yaml
+    # Patch kindnet to use less CPU
+    kubectl --kubeconfig \$HOME/.kube/config patch daemonset kindnet -n kube-system --type='json' -p='[{"op": "add", "path": "/spec/template/spec/containers/0/resources", "value": {"requests": {"cpu": "50m"}, "limits": {"cpu": "200m"}}}]'
+    # Patch coredns
+    kubectl --kubeconfig \$HOME/.kube/config patch deployment coredns -n kube-system --type='json' -p='[{"op": "replace", "path": "/spec/template/spec/containers/0/resources/requests/cpu", "value": "30m"}, {"op": "replace", "path": "/spec/template/spec/containers/0/resources/limits/cpu", "value": "100m"}]'
+    mv \$HOME/.kube/config ~/config-member1
+
+    kind delete cluster --name=member2 || true
+    kind create cluster --name=member2 --config=cluster2.yaml
+    kubectl --kubeconfig \$HOME/.kube/config patch daemonset kindnet -n kube-system --type='json' -p='[{"op": "add", "path": "/spec/template/spec/containers/0/resources", "value": {"requests": {"cpu": "50m"}, "limits": {"cpu": "200m"}}}]'
+    kubectl --kubeconfig \$HOME/.kube/config patch deployment coredns -n kube-system --type='json' -p='[{"op": "replace", "path": "/spec/template/spec/containers/0/resources/requests/cpu", "value": "30m"}, {"op": "replace", "path": "/spec/template/spec/containers/0/resources/limits/cpu", "value": "100m"}]'
+    mv \$HOME/.kube/config config-member2
+
+    # modify ip
+    sed -i "s/${local_ip}/${member_cluster_ip}/g"  config-member1
+    # set StrictHostKeyChecking to no to avoid prompting, the same below
+    scp -o StrictHostKeyChecking=no config-member1 root@${host_cluster_ip}:$HOME/.kube/config-member1
+    sed -i "s/${local_ip}/${member_cluster_ip}/g"  config-member2
+    scp -o StrictHostKeyChecking=no config-member2 root@${host_cluster_ip}:$HOME/.kube/config-member2
+EOF
+}
+
+function cluster1Config() {
+    cat << EOF > cluster1.yaml
+    kind: Cluster
+    apiVersion: kind.x-k8s.io/v1alpha4
+    networking:
+      apiServerAddress: "${member_cluster_ip}"
+      apiServerPort: 6443
+      serviceSubnet: "10.250.0.0/16"
+      podSubnet: "10.251.0.0/16"
+    nodes:
+    - role: control-plane
+EOF
+}
+
+function cluster2Config() {
+    cat << EOF > cluster2.yaml 
+    kind: Cluster
+    apiVersion: kind.x-k8s.io/v1alpha4
+    networking:
+      apiServerAddress: "${member_cluster_ip}"
+      apiServerPort: 6444
+      serviceSubnet: "10.250.0.0/16"
+      podSubnet: "10.251.0.0/16"
+    nodes:
+    - role: control-plane
+EOF
+}
+
+function installMetrics() {
+    cat << 'EOF' > installMetricsServer.sh
+# Install metrics-server on member clusters
+_tmp=$(mktemp -d)
+
+cleanup() {
+  rm -rf "${_tmp}"
+}
+trap cleanup EXIT
+
+METRICS_SERVER_URL="https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml"
+if command -v curl &>/dev/null && curl -fsSL "${METRICS_SERVER_URL}" -o "${_tmp}/components.yaml"; then
+  :
+elif command -v wget &>/dev/null && wget -qO "${_tmp}/components.yaml" "${METRICS_SERVER_URL}"; then
+  :
+else
+  echo "ERROR: failed to download metrics-server components.yaml. Please ensure curl or wget is installed and network access is available."
+  exit 1
+fi
+
+sed -i'' -e 's/args:/args:\n        - --kubelet-insecure-tls=true/' "${_tmp}/components.yaml"
+
+kubectl --kubeconfig=$HOME/.kube/config-member1 apply -f "${_tmp}/components.yaml"
+kubectl --kubeconfig=$HOME/.kube/config-member2 apply -f "${_tmp}/components.yaml"
+EOF
+    chmod +x installMetricsServer.sh
+
+    cat << 'EOF' > installMetricsAdapter.sh
+# Install karmada-metrics-adapter on the Karmada control plane
+# This bridges metrics from member clusters to the FederatedHPA controller
+karmadactl addons enable karmada-metrics-adapter --kubeconfig=$HOME/.kube/config
+EOF
+    chmod +x installMetricsAdapter.sh
+
+
+}
+
+function nginxDeployment() {
+    cat << EOF > nginxDeployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+  labels:
+    app: nginx
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - image: nginx
+        name: nginx
+        resources:
+          requests:
+            cpu: 10m
+            memory: 32Mi
+          limits:
+            cpu: 100m
+            memory: 64Mi
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: nginx-service
+spec:
+  ports:
+  - port: 80
+    targetPort: 80
+  selector:
+    app: nginx
+EOF
+}
+
+function propagationPolicy() {
+    cat << EOF > propagationPolicy.yaml
+apiVersion: policy.karmada.io/v1alpha1
+kind: PropagationPolicy
+metadata:
+  name: nginx-propagation
+spec:
+  resourceSelectors:
+    - apiVersion: apps/v1
+      kind: Deployment
+      name: nginx
+    - apiVersion: v1
+      kind: Service
+      name: nginx-service
+  placement:
+    clusterAffinity:
+      clusterNames:
+        - kind-member1
+        - kind-member2
+    replicaScheduling:
+      replicaDivisionPreference: Weighted
+      replicaSchedulingType: Divided
+      weightPreference:
+        staticWeightList:
+          - targetCluster:
+              clusterNames:
+                - kind-member1
+            weight: 1
+          - targetCluster:
+              clusterNames:
+                - kind-member2
+            weight: 1
+EOF
+}
+
+function federatedHPA() {
+    cat << EOF > federatedHPA.yaml
+apiVersion: autoscaling.karmada.io/v1alpha1
+kind: FederatedHPA
+metadata:
+  name: nginx-fhpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: nginx
+  minReplicas: 1
+  maxReplicas: 4
+  behavior:
+    scaleDown:
+      stabilizationWindowSeconds: 10
+    scaleUp:
+      stabilizationWindowSeconds: 0
+  metrics:
+  - type: Resource
+    resource:
+      name: cpu
+      target:
+        type: Utilization
+        averageUtilization: 10
+EOF
+}
+
+function multiClusterService() {
+    cat << EOF > multiClusterService.yaml
+apiVersion: networking.karmada.io/v1alpha1
+kind: MultiClusterService
+metadata:
+  name: nginx-service
+spec:
+  types:
+    - CrossCluster
+  consumerClusters:
+    - name: kind-member1
+    - name: kind-member2
+  providerClusters:
+    - name: kind-member1
+    - name: kind-member2
+EOF
+}
+
+function copyConfigFilesToNode() {
+    scp -o StrictHostKeyChecking=no \
+        installKind.sh \
+        createCluster.sh \
+        cluster1.yaml \
+        cluster2.yaml \
+        root@${member_cluster_ip}:~
+}
+
+kubectl delete node node01 || true
+kubectl taint node controlplane node-role.kubernetes.io/control-plane:NoSchedule-
+
+# prepare helper scripts and cluster config files
+installKind
+createCluster
+cluster1Config
+cluster2Config
+copyConfigFilesToNode
+
+installMetrics
+
+# generate nginx and FHPA config files
+mkdir -p ~/fhpa
+cd ~/fhpa
+nginxDeployment
+propagationPolicy
+federatedHPA
+multiClusterService
+cd ~
+
+# clean screen 
+clear

karmada-FHPA-example/image/success.png

@@ -0,0 +1,78 @@
+{
+  "title": "FederatedHPA: Autoscaling Across Clusters",
+  "description": "Learn how to use Karmada FederatedHPA to automatically scale workloads across multiple clusters based on CPU metrics",
+  "details": {
+    "intro": {
+      "text": "intro.md",
+      "foreground": "foreground.sh"
+    },
+    "steps": [
+      {
+        "title": "Environment overview",
+        "text": "step1/text.md",
+        "verify": "step1/verify.sh"
+      },
+      {
+        "title": "Install karmadactl",
+        "text": "step2/text.md",
+        "verify": "step2/verify.sh"
+      },
+      {
+        "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": "Install metrics-server on member clusters",
+        "text": "step6/text.md",
+        "verify": "step6/verify.sh"
+      },
+      {
+        "title": "Install karmada-metrics-adapter",
+        "text": "step7/text.md",
+        "verify": "step7/verify.sh"
+      },
+      {
+        "title": "Deploy nginx workload",
+        "text": "step8/text.md",
+        "verify": "step8/verify.sh"
+      },
+      {
+        "title": "Create PropagationPolicy",
+        "text": "step9/text.md",
+        "verify": "step9/verify.sh"
+      },
+      {
+        "title": "Configure Multi-Cluster Routing",
+        "text": "step10/text.md",
+        "verify": "step10/verify.sh"
+      },
+      {
+        "title": "Deploy FederatedHPA",
+        "text": "step11/text.md",
+        "verify": "step11/verify.sh"
+      },
+      {
+        "title": "Trigger load and observe autoscaling",
+        "text": "step12/text.md",
+        "verify": "step12/verify.sh"
+      }
+    ],
+    "finish": {
+      "text": "finish.md"
+    }
+  },
+  "backend": {
+    "imageid": "kubernetes-kubeadm-2nodes"
+  }
+}

karmada-FHPA-example/index.json

@@ -0,0 +1,11 @@
+# What is Karmada?
+
+Karmada (Kubernetes Armada) is a Kubernetes management system that enables you to run your cloud-native applications across multiple Kubernetes clusters and clouds, with no changes to your applications. By speaking Kubernetes-native APIs and providing advanced scheduling capabilities, Karmada enables truly open, multi-cloud Kubernetes.
+
+Karmada aims to provide turnkey automation for multi-cluster application management in multi-cloud and hybrid cloud scenarios, with key features such as centralized multi-cloud management, high availability, failure recovery, and traffic scheduling.
+
+# What is FederatedHPA?
+
+When load increases, FederatedHPA scales up the replicas of the workload if the number of Pods is below the configured maximum. When load decreases, it scales them back down to the configured minimum.
+
+In this scenario, we will create a FederatedHPA targeting CPU utilization, and trigger a CPU load to observe autoscaling across clusters.

karmada-FHPA-example/intro.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`.

karmada-FHPA-example/step1/text.md

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+set -e
+
+# Verify node01 is reachable
+ssh -o StrictHostKeyChecking=no root@172.30.2.2 "echo node01 ready"