diff --git a/.github/actions/federation-bootstrap/action.yaml b/.github/actions/federation-bootstrap/action.yaml
new file mode 100644
index 0000000..27a2d65
--- /dev/null
+++ b/.github/actions/federation-bootstrap/action.yaml
@@ -0,0 +1,128 @@
+name: federation-bootstrap
+description: >
+  Stand up a Karmada federation topology (hub kind cluster + N member kind
+  clusters, joined and labeled) and expose the kubeconfig bundle. Any Datum
+  service e2e that needs a hub + members gets it from one action. Unlike
+  kind-bootstrap this does NOT set KUBECONFIG in the environment — there is no
+  single sensible default among the hub / karmada / member kubeconfigs; consume
+  the emitted outputs instead.
+
+# ---------- inputs ----------
+inputs:
+  hub_cluster:
+    description: "kind cluster name hosting the Karmada control plane (the hub)"
+    required: false
+    default: federation-hub
+  members:
+    description: >
+      Space-separated `<name>[=<label>]` member entries (newlines tolerated),
+      e.g. "compute-pop-dfw=dfw compute-pop-ord=ord".
+    required: true
+  member_label_key:
+    description: "Label key applied to each member carrying its label value"
+    required: false
+    default: topology.datum.net/city-code
+  karmada_api_nodeport:
+    description: "NodePort + host port for the Karmada apiserver"
+    required: false
+    default: "32443"
+  karmada_version:
+    description: "Karmada Helm chart version (empty ⇒ Taskfile default)"
+    required: false
+    default: ""
+  wait_timeout:
+    description: "Timeout for shorter waits such as member Ready (e.g. 300s, 5m)"
+    required: false
+    default: "300s"
+  karmada_wait_timeout:
+    description: "Timeout for Karmada install/converge waits (e.g. 10m)"
+    required: false
+    default: "10m"
+  ref:
+    description: >
+      test-infra ref to check out. Empty ⇒ github.action_ref, so the inner
+      checkout matches the pin on the `uses:` line.
+    required: false
+    default: ""
+  images:
+    description: "Space-separated images to load into the hub + all members (optional)"
+    required: false
+    default: ""
+
+# ---------- outputs ----------
+outputs:
+  kubeconfig_dir:
+    description: "Directory holding the federation kubeconfig bundle"
+    value: ${{ steps.emit.outputs.kubeconfig_dir }}
+  hub_kubeconfig:
+    description: "Host-side kubeconfig for the hub cluster"
+    value: ${{ steps.emit.outputs.hub_kubeconfig }}
+  karmada_kubeconfig:
+    description: "Karmada apiserver kubeconfig (localhost:NodePort)"
+    value: ${{ steps.emit.outputs.karmada_kubeconfig }}
+  karmada_internal_kubeconfig:
+    description: "Karmada apiserver kubeconfig (docker-bridge IP:NodePort)"
+    value: ${{ steps.emit.outputs.karmada_internal_kubeconfig }}
+
+runs:
+  using: composite
+  steps:
+    - name: Checkout test-infra
+      uses: actions/checkout@v6
+      with:
+        repository: datum-cloud/test-infra
+        path: test-infra
+        ref: ${{ inputs.ref != '' && inputs.ref || github.action_ref }}
+
+    - name: Install Task
+      uses: arduino/setup-task@v2
+      with:
+        version: 3.x
+        repo-token: ${{ github.token }}
+
+    - name: Stand up federation topology
+      shell: bash
+      working-directory: test-infra
+      run: |
+        # Newlines in the members input are tolerated: fold them to spaces.
+        MEMBERS=$(printf '%s' "${{ inputs.members }}" | tr '\n' ' ')
+        # Only pass KARMADA_VERSION when set: Task treats a CLI-provided empty
+        # value as authoritative and skips the Taskfile's `| default`, so passing
+        # an empty string here would zero out the chart + karmadactl versions.
+        VERSION_ARG=()
+        if [ -n "${{ inputs.karmada_version }}" ]; then
+          VERSION_ARG=(KARMADA_VERSION="${{ inputs.karmada_version }}")
+        fi
+        task federation-up \
+          FEDERATION_HUB_CLUSTER="${{ inputs.hub_cluster }}" \
+          FEDERATION_MEMBERS="$MEMBERS" \
+          FEDERATION_MEMBER_LABEL_KEY="${{ inputs.member_label_key }}" \
+          KARMADA_API_NODEPORT="${{ inputs.karmada_api_nodeport }}" \
+          WAIT_TIMEOUT="${{ inputs.wait_timeout }}" \
+          KARMADA_WAIT_TIMEOUT="${{ inputs.karmada_wait_timeout }}" \
+          "${VERSION_ARG[@]}"
+
+    - name: Load images into hub + members
+      if: ${{ inputs.images != '' }}
+      shell: bash
+      working-directory: test-infra
+      run: |
+        MEMBERS=$(printf '%s' "${{ inputs.members }}" | tr '\n' ' ')
+        IMG_LIST=$(printf '%s' "${{ inputs.images }}" | tr '\n' ' ')
+        task federation-load-image \
+          FEDERATION_HUB_CLUSTER="${{ inputs.hub_cluster }}" \
+          FEDERATION_MEMBERS="$MEMBERS" \
+          IMAGES="$IMG_LIST"
+
+    - id: emit
+      name: Export kubeconfig paths
+      shell: bash
+      working-directory: test-infra
+      run: |
+        DIR="$PWD/kubeconfigs/federation"
+        {
+          echo "kubeconfig_dir=$DIR"
+          echo "hub_kubeconfig=$DIR/${{ inputs.hub_cluster }}.yaml"
+          echo "karmada_kubeconfig=$DIR/karmada.yaml"
+          echo "karmada_internal_kubeconfig=$DIR/karmada-internal.yaml"
+        } >> "$GITHUB_OUTPUT"
diff --git a/.github/workflows/federation-test.yml b/.github/workflows/federation-test.yml
new file mode 100644
index 0000000..d8dabae
--- /dev/null
+++ b/.github/workflows/federation-test.yml
@@ -0,0 +1,165 @@
+name: federation-topology-test
+on:
+  pull_request:
+    branches: [ main ]
+    types: [opened, synchronize, reopened]
+  push:
+    branches:
+      - main
+
+jobs:
+  federation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+
+    env:
+      HUB: dogfood-hub
+      # Two members exercises the join loop and both label paths.
+      MEMBERS: dogfood-member-a=dfw dogfood-member-b=ord
+
+    steps:
+      - uses: actions/checkout@v6
+        with: { fetch-depth: 0 }
+
+      - name: Stand up federation topology
+        id: fed
+        uses: ./.github/actions/federation-bootstrap
+        with:
+          hub_cluster: dogfood-hub
+          members: ${{ env.MEMBERS }}
+          # Dogfood the Taskfile at THIS commit, not test-infra's default branch.
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Assert both members are Ready
+        run: |
+          set -euo pipefail
+          KARMADA="${{ steps.fed.outputs.karmada_kubeconfig }}"
+          for m in dogfood-member-a dogfood-member-b; do
+            kubectl --kubeconfig "$KARMADA" wait --for=condition=Ready \
+              "cluster/$m" --timeout=120s
+            echo "✅ $m is Ready"
+          done
+
+      - name: Assert city-code labels
+        run: |
+          set -euo pipefail
+          KARMADA="${{ steps.fed.outputs.karmada_kubeconfig }}"
+          check() {
+            local cluster="$1" want="$2"
+            got=$(kubectl --kubeconfig "$KARMADA" get cluster "$cluster" \
+              -o jsonpath='{.metadata.labels.topology\.datum\.net/city-code}')
+            if [ "$got" != "$want" ]; then
+              echo "❌ $cluster city-code=[$got], expected [$want]"; exit 1
+            fi
+            echo "✅ $cluster labeled city-code=$got"
+          }
+          check dogfood-member-a dfw
+          check dogfood-member-b ord
+
+      - name: PropagationPolicy round-trip (dfw only)
+        run: |
+          set -euo pipefail
+          KARMADA="${{ steps.fed.outputs.karmada_kubeconfig }}"
+          DIR="${{ steps.fed.outputs.kubeconfig_dir }}"
+          MEMBER_A="$DIR/dogfood-member-a.yaml"
+          MEMBER_B="$DIR/dogfood-member-b.yaml"
+
+          # A ConfigMap plus a PropagationPolicy that targets only members labeled
+          # city-code=dfw (member-a). This is the one assertion that proves the
+          # patched member Secret + apiEndpoint actually carry traffic — Karmada
+          # can only place the object if it can reach member-a's API server.
+          kubectl --kubeconfig "$KARMADA" apply -f - <<'EOF'
+          apiVersion: v1
+          kind: ConfigMap
+          metadata:
+            name: dogfood-cm
+            namespace: default
+          data:
+            hello: federation
+          ---
+          apiVersion: policy.karmada.io/v1alpha1
+          kind: PropagationPolicy
+          metadata:
+            name: dogfood-cm
+            namespace: default
+          spec:
+            resourceSelectors:
+              - apiVersion: v1
+                kind: ConfigMap
+                name: dogfood-cm
+            placement:
+              clusterAffinity:
+                labelSelector:
+                  matchLabels:
+                    topology.datum.net/city-code: dfw
+          EOF
+
+          echo "⏳ Waiting for dogfood-cm to land on member-a (dfw)..."
+          for i in $(seq 1 30); do
+            if kubectl --kubeconfig "$MEMBER_A" -n default get configmap dogfood-cm >/dev/null 2>&1; then
+              echo "✅ dogfood-cm present on member-a"; break
+            fi
+            [ "$i" = "30" ] && { echo "❌ dogfood-cm never propagated to member-a"; exit 1; }
+            sleep 5
+          done
+
+          # member-b (ord) must NOT receive it — proves label-scoped placement.
+          if kubectl --kubeconfig "$MEMBER_B" -n default get configmap dogfood-cm >/dev/null 2>&1; then
+            echo "❌ dogfood-cm unexpectedly present on member-b (ord)"; exit 1
+          fi
+          echo "✅ dogfood-cm absent on member-b, as expected"
+
+          # Delete and confirm it is withdrawn from member-a.
+          kubectl --kubeconfig "$KARMADA" delete configmap dogfood-cm -n default
+          kubectl --kubeconfig "$KARMADA" delete propagationpolicy dogfood-cm -n default
+          echo "⏳ Waiting for dogfood-cm to be withdrawn from member-a..."
+          for i in $(seq 1 30); do
+            if ! kubectl --kubeconfig "$MEMBER_A" -n default get configmap dogfood-cm >/dev/null 2>&1; then
+              echo "✅ dogfood-cm withdrawn from member-a"; break
+            fi
+            [ "$i" = "30" ] && { echo "❌ dogfood-cm never withdrawn from member-a"; exit 1; }
+            sleep 5
+          done
+
+      - name: Federation status
+        run: |
+          cd test-infra
+          task federation-status \
+            FEDERATION_HUB_CLUSTER=dogfood-hub \
+            FEDERATION_MEMBERS="${{ env.MEMBERS }}"
+
+      - name: Collect diagnostics on failure
+        if: failure()
+        run: |
+          set +e
+          mkdir -p /tmp/fed-diagnostics
+          for c in dogfood-hub dogfood-member-a dogfood-member-b; do
+            kind export logs --name "$c" "/tmp/fed-diagnostics/$c" 2>&1 || true
+          done
+          KARMADA="${{ steps.fed.outputs.karmada_kubeconfig }}"
+          HUB="${{ steps.fed.outputs.hub_kubeconfig }}"
+          kubectl --kubeconfig "$HUB" -n karmada-system get pods -o wide \
+            > /tmp/fed-diagnostics/karmada-pods.txt 2>&1 || true
+          kubectl --kubeconfig "$HUB" -n karmada-system logs -l app=karmada-controller-manager --tail=500 \
+            > /tmp/fed-diagnostics/karmada-controller-manager.log 2>&1 || true
+          kubectl --kubeconfig "$KARMADA" get clusters -o yaml \
+            > /tmp/fed-diagnostics/karmada-clusters.yaml 2>&1 || true
+
+      - name: Upload diagnostics
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: federation-diagnostics
+          path: /tmp/fed-diagnostics
+          if-no-files-found: ignore
+
+      - name: Tear down
+        if: always()
+        run: |
+          cd test-infra
+          task federation-down \
+            FEDERATION_HUB_CLUSTER=dogfood-hub \
+            FEDERATION_MEMBERS="${{ env.MEMBERS }}"
diff --git a/.gitignore b/.gitignore
index 7bfaace..aecc87f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,7 @@
 *.tgz
 # Well known location for the kubeconfig to use talk to the test-infra cluster.
 kubeconfig
+# Federation kubeconfig bundle (hub/member/karmada configs + federation.env)
+kubeconfigs/
+# Repo-local pinned tools (e.g. karmadactl)
+bin/
diff --git a/README.md b/README.md
index a86f327..4beddd4 100644
--- a/README.md
+++ b/README.md
@@ -208,6 +208,102 @@ task test-infra:kubectl -- get nodes    # Run kubectl commands
 task test-infra:k9s                     # Launch k9s terminal UI
 ```
 
+## Federation topology (Karmada hub + members)
+
+Beyond the single-cluster environment above, this repo can stand up a **Karmada
+federation topology** — a hub cluster running the Karmada control plane plus any
+number of member clusters, joined and labeled — that any Datum service e2e can
+consume. Compute is the first consumer; NSO-style multi-cluster labs are the
+next. The clusters are throwaway, throughput-tuned kind clusters; Karmada is
+installed imperatively via Helm (federation clusters run **no** Flux).
+
+> [!NOTE]
+> The federation tasks use `for:` over `task:` calls, which requires **Task
+> ≥ 3.44**. The single-cluster tasks are unaffected.
+
+### Quick start
+
+```bash
+# Hub + two members, each labeled with a city code.
+task federation-up FEDERATION_MEMBERS="pop-dfw=dfw pop-ord=ord"
+
+task federation-status        # hub + member health, registered clusters
+task federation-down FEDERATION_MEMBERS="pop-dfw=dfw pop-ord=ord"   # tear down
+```
+
+### Member-spec syntax
+
+`FEDERATION_MEMBERS` is a space-separated list of `<kind-cluster-name>[=<label-value>]`
+entries:
+
+- A member's Karmada cluster name **is** its kind cluster name.
+- `=<label-value>` is optional; when present it is applied under
+  `FEDERATION_MEMBER_LABEL_KEY` (default `topology.datum.net/city-code`). Omit it
+  for no label.
+- Names must not contain `=`, and `karmada` is reserved (it collides with a
+  kubeconfig filename).
+
+### Variables
+
+| Var | Default | Meaning |
+|-----|---------|---------|
+| `FEDERATION_HUB_CLUSTER` | `federation-hub` | Kind cluster hosting Karmada |
+| `FEDERATION_MEMBERS` | _(required)_ | `name[=label]` entries, space-separated |
+| `FEDERATION_MEMBER_LABEL_KEY` | `topology.datum.net/city-code` | Label key for each member's value |
+| `KARMADA_VERSION` | `v1.16.0` | Karmada Helm chart version |
+| `KARMADACTL_VERSION` | `{{KARMADA_VERSION}}` | karmadactl CLI version |
+| `KARMADA_API_NODEPORT` | `32443` | NodePort + host port for the Karmada apiserver |
+| `KARMADA_WAIT_TIMEOUT` | `10m` | Karmada install/converge waits |
+| `FEDERATION_KUBECONFIG_DIR` | `<repo>/kubeconfigs/federation` | Where the kubeconfig bundle lands |
+| `FEDERATION_HUB_KIND_CFG` / `FEDERATION_MEMBER_KIND_CFG` | `cluster/federation/kind-{hub,member}.yaml` | Kind config overrides |
+
+### Kubeconfig bundle
+
+All under `FEDERATION_KUBECONFIG_DIR`:
+
+| File | Contents |
+|------|----------|
+| `<hub>.yaml` | Host-side kubeconfig for the hub cluster |
+| `<member>.yaml` | Host-side kubeconfig per member |
+| `<member>-internal.yaml` | Docker-bridge-IP variant (what Karmada stores for the member) |
+| `karmada.yaml` | Karmada apiserver, server `https://127.0.0.1:<nodeport>` |
+| `karmada-internal.yaml` | Karmada apiserver, server `https://<hub-docker-ip>:<nodeport>` (for in-docker-network reachers) |
+| `federation.env` | Shell-sourceable facts (hub docker IP, NodePort, members) |
+
+### Using from another repository
+
+```yaml
+# Your project's Taskfile.yml
+version: '3'
+
+includes:
+  infra:
+    taskfile: https://raw.githubusercontent.com/datum-cloud/test-infra/v0.7.0/Taskfile.yml
+    vars:
+      REPO_REF: v0.7.0                      # match the include ref for the self-clone
+      FEDERATION_HUB_CLUSTER: my-hub
+      FEDERATION_MEMBERS: my-pop-a=dfw my-pop-b=ord
+```
+
+```bash
+export TASK_X_REMOTE_TASKFILES=1
+task --yes infra:federation-up            # --yes accepts the remote-taskfile trust prompt
+```
+
+> [!IMPORTANT]
+> A remote include shares one root variable namespace, so the foundation's root
+> vars **clobber** a consumer's same-named root vars. Do not define your own root
+> vars with names the foundation uses — `LOCALBIN`, `KARMADACTL`, and the
+> `KARMADA_*` / `FEDERATION_*` families (e.g. name a local tools dir `E2E_BIN`,
+> not `LOCALBIN`). Deliberately steering the foundation by passing those names as
+> `include.vars` (like `KARMADA_API_NODEPORT` above) is exactly how it is meant to
+> be driven and is fine.
+
+CI consumers can instead use the
+[`federation-bootstrap`](.github/actions/federation-bootstrap/action.yaml)
+composite action, which stands up the topology and emits the kubeconfig paths as
+step outputs.
+
 ## Troubleshooting
 
 **Versions** – run `task ensure-tools` regularly; it will upgrade outdated binaries.
diff --git a/Taskfile.yml b/Taskfile.yml
index 48b45eb..c363fdf 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -30,6 +30,45 @@ vars:
   # All file paths relative to REPO_DIR
   KIND_CFG: '{{.REPO_DIR}}/cluster/kind-config.yaml'
 
+  #----------------------------------------------------------------------------
+  # Federation topology (Karmada hub + members). Only the federation-* tasks use
+  # these; single-cluster consumers are unaffected. Requires Task >= 3.44 (for:
+  # over task: calls). See README "Federation topology".
+  #----------------------------------------------------------------------------
+  # Kind cluster hosting the Karmada control plane (the federation hub). Literal
+  # name — no prefixing rules are applied anywhere.
+  FEDERATION_HUB_CLUSTER: '{{.FEDERATION_HUB_CLUSTER | default "federation-hub"}}'
+  # Space-separated `<kind-cluster-name>[=<label-value>]` member entries, e.g.
+  # "compute-pop-dfw=dfw compute-pop-ord=ord". A member's Karmada cluster name is
+  # its kind cluster name; the `=label` is optional (omitted ⇒ no label applied).
+  # Names must not contain `=`, and the name `karmada` is reserved (it would
+  # collide with a kubeconfig filename). No default — federation tasks
+  # precondition on it being non-empty.
+  FEDERATION_MEMBERS: '{{.FEDERATION_MEMBERS | default ""}}'
+  # Label key applied to each member, carrying that member's label value
+  # (Datum-wide topology convention, parameterized so other consumers can relabel).
+  FEDERATION_MEMBER_LABEL_KEY: '{{.FEDERATION_MEMBER_LABEL_KEY | default "topology.datum.net/city-code"}}'
+  # Karmada Helm chart version, and the matching karmadactl CLI. One knob drives
+  # both, each separately overridable.
+  KARMADA_VERSION: '{{.KARMADA_VERSION | default "v1.16.0"}}'
+  KARMADACTL_VERSION: '{{.KARMADACTL_VERSION | default .KARMADA_VERSION}}'
+  # NodePort + host port for the Karmada apiserver (quoted; envsubst-rendered into
+  # the hub kind config and passed to helm --set apiServer.nodePort).
+  KARMADA_API_NODEPORT: '{{.KARMADA_API_NODEPORT | default "32443"}}'
+  # Longer timeout for Karmada install/converge waits; WAIT_TIMEOUT (300s) still
+  # covers the shorter waits such as member Ready.
+  KARMADA_WAIT_TIMEOUT: '{{.KARMADA_WAIT_TIMEOUT | default "10m"}}'
+  # All federation kubeconfigs land here (.test-infra/kubeconfigs/federation/ for
+  # external consumers).
+  FEDERATION_KUBECONFIG_DIR: '{{.FEDERATION_KUBECONFIG_DIR | default (printf "%s/kubeconfigs/federation" .REPO_DIR)}}'
+  # Federation kind config templates (overridable, mirroring KIND_CFG).
+  FEDERATION_HUB_KIND_CFG: '{{.FEDERATION_HUB_KIND_CFG | default (printf "%s/cluster/federation/kind-hub.yaml" .REPO_DIR)}}'
+  FEDERATION_MEMBER_KIND_CFG: '{{.FEDERATION_MEMBER_KIND_CFG | default (printf "%s/cluster/federation/kind-member.yaml" .REPO_DIR)}}'
+  # karmadactl is version-pinned per-repo, so it goes to a repo-local bin (not
+  # /usr/local/bin) like other pinned tools.
+  LOCALBIN: '{{.LOCALBIN | default (printf "%s/bin" .REPO_DIR)}}'
+  KARMADACTL: '{{.KARMADACTL | default (printf "%s/karmadactl" .LOCALBIN)}}'
+
 env:
   KIND_VERSION: '{{.KIND_VERSION}}'
   KUBECONFIG: '{{.KUBECONFIG_FILE}}'
@@ -113,6 +152,12 @@ tasks:
       - echo "  kind-load-image         Load images into KIND"
       - echo "  kind-save-image         Save image tarball artifact"
       - echo ""
+      - echo "🌐 Federation topology (Karmada hub + members):"
+      - echo "  federation-up           Stand up hub + members + join (needs FEDERATION_MEMBERS)"
+      - echo "  federation-down         Delete the federation clusters + kubeconfigs"
+      - echo "  federation-status       Show hub + member health"
+      - echo "  federation-load-image   Load images into hub + all members"
+      - echo ""
       - 'echo "For detailed help: task --list"'
       - 'echo "To run a command: task <command-name>"'
 
@@ -143,7 +188,7 @@ tasks:
       - echo "🎉 Test infrastructure deployment complete!"
       - echo ""
       - echo "🌐 Available endpoints:"
-      - 'echo "   • HTTPS Gateway: https://localhost:8443"'
+      - 'echo "   • HTTPS Gateway: https://localhost:30443"'
       - 'echo "   • Grafana:       http://localhost:30000 (after installing observability)"'
       - echo ""
       - echo "📦 Optional add-ons:"
@@ -153,7 +198,7 @@ tasks:
       - echo "   • export KUBECONFIG={{.KUBECONFIG_FILE}}"  # Connect to test-infra cluster
       - echo "   • task cluster-status"                # Check cluster health
       - echo "   • kubectl get pods --all-namespaces"  # List all pods
-      - echo "   • curl -k https://localhost:8443"     # Test gateway
+      - echo "   • curl -k https://localhost:30443"    # Test gateway
       - echo "   • task help"                          # See all commands
 
   cluster-down:
@@ -264,18 +309,40 @@ tasks:
   create-kind:
     desc: "Create KIND cluster"
     silent: true
+    cmds:
+      # Public create-kind keeps its exact single-cluster behavior: create the
+      # cluster with the repo defaults, then install Flux. The cluster-creation
+      # body now lives in the parameterized create-kind-raw so the federation
+      # tasks can reuse it WITHOUT Flux (federation clusters run no Flux).
+      - task: create-kind-raw
+        vars:
+          CLUSTER_NAME: '{{.CLUSTER_NAME}}'
+          KIND_CFG: '{{.KIND_CFG}}'
+          KUBECONFIG_FILE: '{{.KUBECONFIG_FILE}}'
+      # Always install flux to the cluster so additional components can be
+      # installed using it.
+      - task: install-flux
+
+  create-kind-raw:
+    internal: true
+    desc: "Create a KIND cluster from an explicit config + kubeconfig (no Flux)"
+    silent: true
     cmds:
       - echo "➡️  Creating KIND cluster '{{.CLUSTER_NAME}}' ..."
       - |
         # Check if cluster already exists
         if kind get clusters | grep -q "^{{.CLUSTER_NAME}}$"; then
           echo "✅ KIND cluster '{{.CLUSTER_NAME}}' already exists"
-          # Validate cluster is accessible
-          if kubectl cluster-info >/dev/null 2>&1; then
+          # Validate cluster is accessible. Explicit --kubeconfig on every kubectl:
+          # federation clusters do not use the global KUBECONFIG env (that points
+          # at the single-cluster file), so each call targets this cluster's own
+          # kubeconfig. For the public single-cluster path KUBECONFIG_FILE is that
+          # same global file, so the behavior is unchanged.
+          if kubectl --kubeconfig {{.KUBECONFIG_FILE}} cluster-info >/dev/null 2>&1; then
             echo "✅ Cluster is accessible and ready"
           else
             echo "⚠️  Cluster exists but is not accessible - checking..."
-            kubectl cluster-info 2>&1 || echo "❌ Cluster may need to be recreated"
+            kubectl --kubeconfig {{.KUBECONFIG_FILE}} cluster-info 2>&1 || echo "❌ Cluster may need to be recreated"
           fi
         else
           echo "🚀 Creating new KIND cluster..."
@@ -285,19 +352,22 @@ tasks:
             exit 1
           fi
 
-          # Export REPO_DIR for envsubst to substitute audit policy path in KIND config
-          # KIND doesn't natively support env var substitution, so we preprocess with envsubst
+          # KIND doesn't natively support env var substitution, so we preprocess
+          # with envsubst. REPO_DIR resolves the audit-policy path in the
+          # single-cluster config; KARMADA_API_NODEPORT resolves the hub config's
+          # NodePort port mappings (a harmless no-op for configs without them).
           export REPO_DIR="{{.REPO_DIR}}"
+          export KARMADA_API_NODEPORT="{{.KARMADA_API_NODEPORT}}"
 
           # Process KIND config and create cluster (--name and --image override config values)
           if envsubst < {{.KIND_CFG}} | kind create cluster --name {{.CLUSTER_NAME}} --image kindest/node:{{.K8S_VERSION}} --config - --kubeconfig {{.KUBECONFIG_FILE}}; then
             echo "✅ KIND cluster created successfully"
-            echo "📝 Test-infra cluster kubeconfig written to: {{.KUBECONFIG_FILE}}"
+            echo "📝 Cluster kubeconfig written to: {{.KUBECONFIG_FILE}}"
 
             # Wait for cluster to be ready
             echo "⏳ Waiting for cluster to be ready..."
             timeout_count=0
-            while ! kubectl cluster-info >/dev/null 2>&1; do
+            while ! kubectl --kubeconfig {{.KUBECONFIG_FILE}} cluster-info >/dev/null 2>&1; do
               if [ $timeout_count -ge 30 ]; then
                 echo "❌ Timeout waiting for cluster to be ready"
                 exit 1
@@ -313,9 +383,6 @@ tasks:
             exit 1
           fi
         fi
-      # Always install flux to the cluster so additional components can be
-      # installed using it.
-      - task: install-flux
 
   delete-kind:
     desc: "Delete KIND cluster"
@@ -403,7 +470,7 @@ tasks:
       - echo "✅ Envoy Gateway Operator and merged gateway are ready"
       - echo ""
       - echo "🌐 Gateway exposed ports:"
-      - 'echo "   HTTPS Gateway: https://localhost:8443 (self-signed cert - use -k flag)"'
+      - 'echo "   HTTPS Gateway: https://localhost:30443 (self-signed cert - use -k flag)"'
       - echo "   To find the actual NodePort assignments, run:"
       - echo "   kubectl get svc -n envoy-gateway-system -l app.kubernetes.io/name=envoy"
 
@@ -493,3 +560,459 @@ tasks:
         msg: 'ERROR: set TAR=<file> as argument'
     cmds:
       - docker save "{{.IMAGE}}" | gzip > "{{.TAR}}"
+
+  #------------------------------------------------------------------------------
+  # Federation topology (Karmada hub + members)
+  #
+  # Stands up a Karmada hub kind cluster plus N member kind clusters, joins the
+  # members, and writes a kubeconfig bundle any Datum service e2e can consume
+  # (compute is the first consumer; NSO-style labs the next). Karmada is installed
+  # imperatively via Helm here rather than through Flux — federation clusters run
+  # no Flux, matching the kyverno-style direct install. Requires Task >= 3.44.
+  #
+  # Every kubectl/helm/karmadactl call passes an explicit --kubeconfig: the global
+  # KUBECONFIG env points at the single-cluster file and must never be relied on
+  # in these tasks. docker-IP derivation lives only in hack/federation/*.sh — a
+  # docker --format Go-template would collide with Task's own {{ }} templating.
+  #------------------------------------------------------------------------------
+  federation-up:
+    desc: "Stand up the Karmada hub + members and join them (idempotent)"
+    silent: true
+    preconditions:
+      - sh: '[ -n "{{.FEDERATION_MEMBERS}}" ]'
+        msg: |
+          ERROR: set FEDERATION_MEMBERS="<name>[=<label>] ..." (space-separated).
+          Example: FEDERATION_MEMBERS="compute-pop-dfw=dfw compute-pop-ord=ord"
+      # The Karmada apiserver is exposed as a Service of type NodePort, so the
+      # port must be inside Kubernetes' NodePort range — otherwise the helm
+      # install fails deep inside with a cryptic Service validation error.
+      - sh: 'p={{.KARMADA_API_NODEPORT}}; [ "$p" -ge 30000 ] 2>/dev/null && [ "$p" -le 32767 ] 2>/dev/null'
+        msg: 'ERROR: KARMADA_API_NODEPORT ({{.KARMADA_API_NODEPORT}}) must be a Kubernetes NodePort in the range 30000-32767.'
+    cmds:
+      - task: ensure-repo
+      - task: federation-ensure-tools
+      - task: federation-create-clusters
+      - task: federation-install-karmada
+      - task: federation-join-members
+      - task: federation-write-env
+      - echo ""
+      - echo "🎉 Federation topology ready"
+      - echo ""
+      - 'echo "📝 Kubeconfigs ({{.FEDERATION_KUBECONFIG_DIR}}):"'
+      - 'echo "   • hub:            {{.FEDERATION_HUB_CLUSTER}}.yaml"'
+      - 'echo "   • Karmada API:    karmada.yaml (localhost:{{.KARMADA_API_NODEPORT}})"'
+      - 'echo "   • Karmada API:    karmada-internal.yaml (docker-bridge)"'
+      - 'echo "   • members:        <name>.yaml + <name>-internal.yaml"'
+      - 'echo "   • facts:          federation.env"'
+      - echo ""
+      - 'echo "🔍 Inspect: kubectl --kubeconfig {{.FEDERATION_KUBECONFIG_DIR}}/karmada.yaml get clusters"'
+
+  federation-down:
+    desc: "Delete the federation hub + members and remove their kubeconfigs"
+    silent: true
+    cmds:
+      - echo "🗑️  Deleting federation clusters..."
+      - |
+        # Tolerant teardown (like delete-kind): delete the hub and every member,
+        # ignoring clusters that are already gone. Unquoted expansion word-splits
+        # FEDERATION_MEMBERS on spaces (skipping empties) and strips each label.
+        for c in {{.FEDERATION_HUB_CLUSTER}} $(for m in {{.FEDERATION_MEMBERS}}; do echo "${m%%=*}"; done); do
+          [ -z "$c" ] && continue
+          if kind get clusters 2>/dev/null | grep -qx "$c"; then
+            echo "🗑️  Deleting '$c'..."
+            kind delete cluster --name "$c" || echo "⚠️  Error deleting '$c', continuing..."
+          else
+            echo "ℹ️  Cluster '$c' does not exist"
+          fi
+        done
+      - rm -rf {{.FEDERATION_KUBECONFIG_DIR}}
+      - echo "✅ Federation torn down"
+
+  federation-status:
+    desc: "Show federation hub + member health"
+    silent: true
+    cmds:
+      - echo "🔍 Federation Status"
+      - echo ""
+      - |
+        if kind get clusters 2>/dev/null | grep -qx "{{.FEDERATION_HUB_CLUSTER}}"; then
+          echo "✅ Hub cluster '{{.FEDERATION_HUB_CLUSTER}}' exists"
+        else
+          echo "❌ Hub cluster '{{.FEDERATION_HUB_CLUSTER}}' does not exist"
+          exit 0
+        fi
+      - |
+        HUB={{.FEDERATION_KUBECONFIG_DIR}}/{{.FEDERATION_HUB_CLUSTER}}.yaml
+        echo ""
+        echo "📦 Karmada control plane (karmada-system):"
+        if [ -f "$HUB" ]; then
+          kubectl --kubeconfig "$HUB" -n karmada-system get deploy \
+            -o custom-columns=NAME:.metadata.name,AVAILABLE:.status.availableReplicas,DESIRED:.spec.replicas 2>/dev/null \
+            || echo "   ❌ Cannot read karmada-system deployments"
+        else
+          echo "   ❌ Hub kubeconfig not found at $HUB"
+        fi
+      - |
+        KARMADA={{.FEDERATION_KUBECONFIG_DIR}}/karmada.yaml
+        echo ""
+        echo "🌐 Registered clusters:"
+        if [ -f "$KARMADA" ]; then
+          kubectl --kubeconfig "$KARMADA" get clusters 2>/dev/null \
+            || echo "   ❌ Cannot reach the Karmada API server"
+        else
+          echo "   ❌ Karmada kubeconfig not found at $KARMADA"
+        fi
+      - echo ""
+      - 'echo "📝 Kubeconfig dir: {{.FEDERATION_KUBECONFIG_DIR}}"'
+
+  federation-load-image:
+    desc: "Load one or more images into the federation hub + all members"
+    silent: true
+    vars:
+      IMAGES: '{{.IMAGES}}'
+    preconditions:
+      - sh: '[ -n "{{.IMAGES}}" ]'
+        msg: 'ERROR: pass IMAGES="img1 img2 ..." as argument'
+    cmds:
+      - |
+        for c in {{.FEDERATION_HUB_CLUSTER}} $(for m in {{.FEDERATION_MEMBERS}}; do echo "${m%%=*}"; done); do
+          [ -z "$c" ] && continue
+          for img in {{.IMAGES}}; do
+            echo "➡️  Loading $img into kind '$c'"
+            docker pull "$img" || true
+            kind load docker-image "$img" --name "$c"
+          done
+        done
+
+  #------------------------------------------------------------------------------
+  # Federation internals
+  #------------------------------------------------------------------------------
+  federation-ensure-tools:
+    internal: true
+    silent: true
+    cmds:
+      # kind/kubectl/helm come from the shared installer; karmadactl is
+      # version-pinned per-repo so it lives in a repo-local bin.
+      - bash {{.REPO_DIR}}/hack/ensure-tools.sh kind kubectl helm
+      - task: federation-ensure-karmadactl
+
+  federation-ensure-karmadactl:
+    internal: true
+    silent: true
+    status:
+      - test -f {{.KARMADACTL}}
+    cmds:
+      - mkdir -p {{.LOCALBIN}}
+      - |
+        OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+        ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
+        URL="https://github.com/karmada-io/karmada/releases/download/{{.KARMADACTL_VERSION}}/karmadactl-${OS}-${ARCH}.tgz"
+        echo "Downloading karmadactl {{.KARMADACTL_VERSION}} (${OS}/${ARCH})..."
+        curl -sSfL "${URL}" | tar -xz -C {{.LOCALBIN}} karmadactl
+        chmod +x {{.KARMADACTL}}
+        echo "karmadactl installed → {{.KARMADACTL}}"
+
+  federation-create-clusters:
+    internal: true
+    silent: true
+    cmds:
+      - mkdir -p {{.FEDERATION_KUBECONFIG_DIR}}
+      # Hub — needs the extraPortMappings for the Karmada API NodePort.
+      - task: create-kind-raw
+        vars:
+          CLUSTER_NAME: '{{.FEDERATION_HUB_CLUSTER}}'
+          KIND_CFG: '{{.FEDERATION_HUB_KIND_CFG}}'
+          KUBECONFIG_FILE: '{{.FEDERATION_KUBECONFIG_DIR}}/{{.FEDERATION_HUB_CLUSTER}}.yaml'
+      # Re-export the hub kubeconfig so an idempotent re-run (cluster already
+      # present, kubeconfig dir cleaned) still has a usable file.
+      - kind export kubeconfig --name {{.FEDERATION_HUB_CLUSTER}} --kubeconfig {{.FEDERATION_KUBECONFIG_DIR}}/{{.FEDERATION_HUB_CLUSTER}}.yaml
+      # Members — same busy-host tuning, no port mapping.
+      - for: { var: FEDERATION_MEMBERS, split: ' ' }
+        task: federation-create-member
+        vars:
+          MEMBER_SPEC: '{{.ITEM}}'
+
+  federation-create-member:
+    internal: true
+    silent: true
+    vars:
+      MEMBER_NAME: '{{splitList "=" .MEMBER_SPEC | first}}'
+    # Skip empty entries produced by trailing/double spaces in FEDERATION_MEMBERS
+    # (Task's for/split does not drop empty fields).
+    status:
+      - test -z "{{.MEMBER_NAME}}"
+    cmds:
+      - task: create-kind-raw
+        vars:
+          CLUSTER_NAME: '{{.MEMBER_NAME}}'
+          KIND_CFG: '{{.FEDERATION_MEMBER_KIND_CFG}}'
+          KUBECONFIG_FILE: '{{.FEDERATION_KUBECONFIG_DIR}}/{{.MEMBER_NAME}}.yaml'
+      - kind export kubeconfig --name {{.MEMBER_NAME}} --kubeconfig {{.FEDERATION_KUBECONFIG_DIR}}/{{.MEMBER_NAME}}.yaml
+      # Docker-bridge-IP variant stored in Karmada so the controller (inside
+      # Docker) can reach this member's API server across the kind network.
+      - bash {{.REPO_DIR}}/hack/federation/make-internal-kubeconfig.sh {{.FEDERATION_KUBECONFIG_DIR}}/{{.MEMBER_NAME}}.yaml {{.FEDERATION_KUBECONFIG_DIR}}/{{.MEMBER_NAME}}-internal.yaml {{.MEMBER_NAME}}
+
+  federation-install-karmada:
+    internal: true
+    silent: true
+    vars:
+      HUB_KUBECONFIG: '{{.FEDERATION_KUBECONFIG_DIR}}/{{.FEDERATION_HUB_CLUSTER}}.yaml'
+    cmds:
+      # Idempotency keys on the karmada-apiserver Deployment existing rather than
+      # just the namespace: a Helm --wait that times out on a loaded machine
+      # leaves the namespace behind with components still converging, and we want a
+      # re-run to resume that install (wait for it to finish) instead of skipping
+      # past a not-yet-ready control plane. --repo installs the chart without
+      # mutating the developer's global helm repo list; static values live in
+      # components/karmada/values.yaml, the NodePort is set on the command line so
+      # it shares one source of truth with the hub kind config.
+      - |
+        if kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+            -n karmada-system get deploy karmada-apiserver &>/dev/null; then
+          echo "Karmada already present — waiting for its components to become Available..."
+        else
+          echo "Installing Karmada {{.KARMADA_VERSION}} via Helm..."
+          helm install karmada karmada \
+            --repo https://raw.githubusercontent.com/karmada-io/karmada/master/charts \
+            --version {{.KARMADA_VERSION}} \
+            -f {{.REPO_DIR}}/components/karmada/values.yaml \
+            --set apiServer.nodePort={{.KARMADA_API_NODEPORT}} \
+            --kubeconfig={{.HUB_KUBECONFIG}} \
+            --namespace karmada-system \
+            --create-namespace \
+            --wait \
+            --timeout {{.KARMADA_WAIT_TIMEOUT}} \
+            || echo "Helm --wait did not settle in time; will wait on the deployments directly below"
+        fi
+      # Tune BEFORE the Available wait: the probe relaxation + etcd fsync + leader
+      # election patches are what let the components actually become Available on a
+      # loaded host, so they must land before we block on the wait.
+      - task: federation-tune-karmada
+      # Scale any Karmada deployment sitting at zero back up to one. Makes the
+      # target robust to a control plane intentionally scaled down (to keep a busy
+      # host calm between runs) or left at zero by a partial install: otherwise the
+      # Available wait below blocks forever on a deployment with no desired replicas.
+      - |
+        for d in $(kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+            -n karmada-system get deploy -o jsonpath='{.items[*].metadata.name}'); do
+          reps=$(kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+            -n karmada-system get deploy "$d" -o jsonpath='{.spec.replicas}')
+          if [ "$reps" = "0" ]; then
+            echo "Scaling Karmada deploy $d back to 1 (was scaled to 0)..."
+            kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+              -n karmada-system scale deploy "$d" --replicas=1
+          fi
+        done
+      # Wait on the control-plane deployments regardless of how the install above
+      # exited, so a timed-out Helm run still converges before we build the
+      # kubeconfig and register members.
+      - |
+        kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+          -n karmada-system wait --for=condition=Available deploy --all --timeout={{.KARMADA_WAIT_TIMEOUT}}
+        echo "Karmada control plane is Available"
+      - task: federation-build-kubeconfig
+
+  federation-tune-karmada:
+    internal: true
+    silent: true
+    vars:
+      HUB_KUBECONFIG: '{{.FEDERATION_KUBECONFIG_DIR}}/{{.FEDERATION_HUB_CLUSTER}}.yaml'
+    cmds:
+      # Disable leader election on the single-replica Karmada controllers. On a
+      # busy host, etcd write-latency spikes make the controllers' 5s lease
+      # renewals time out; each lost lease exits the process, and the restart
+      # re-lists every resource, adding I/O load that provokes the next spike — a
+      # crashloop feedback loop. With one replica there is nothing to elect, so
+      # turning it off breaks the loop. Harmless in single-replica e2e; not for HA.
+      - |
+        for d in karmada-controller-manager karmada-kube-controller-manager karmada-scheduler; do
+          current=$(kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+            -n karmada-system get deploy "$d" \
+            -o jsonpath='{.spec.template.spec.containers[0].command}' 2>/dev/null)
+          if echo "$current" | grep -q -- "--leader-elect=false"; then
+            echo "Leader election already disabled on $d"
+          else
+            echo "Disabling leader election on $d..."
+            kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+              -n karmada-system patch deploy "$d" --type=json \
+              -p '[{"op":"add","path":"/spec/template/spec/containers/0/command/-","value":"--leader-elect=false"}]'
+          fi
+        done
+      # Disable fsync on the Karmada control plane's own etcd, same throwaway-data
+      # reason as the base clusters (see cluster/federation/kind-*.yaml). Its etcd
+      # is a Helm-managed StatefulSet on hostPath storage — co-located with the
+      # hub's own etcd on one node — so without this its fsync contention keeps hub
+      # writes slow even after the base etcds are tuned. Idempotent: only patch +
+      # restart if the flag is not already set. Data lives on a hostPath, so
+      # deleting the pod does not lose state (a StatefulSet does not always roll on
+      # a bare command change, hence the explicit delete).
+      - |
+        current=$(kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+          -n karmada-system get statefulset etcd \
+          -o jsonpath='{.spec.template.spec.containers[0].command}' 2>/dev/null)
+        if echo "$current" | grep -q -- "--unsafe-no-fsync"; then
+          echo "Karmada etcd fsync already disabled"
+        else
+          echo "Disabling fsync on the Karmada etcd..."
+          kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+            -n karmada-system patch statefulset etcd --type=json \
+            -p '[{"op":"add","path":"/spec/template/spec/containers/0/command/-","value":"--unsafe-no-fsync=true"}]'
+          kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+            -n karmada-system delete pod etcd-0 --ignore-not-found
+        fi
+      # Relax the Karmada API server's health probes. Under sustained load a
+      # transient etcd/DNS blip makes the default 5s/15s probes fail, and the
+      # kubelet SIGKILLs the API server — cascading into a crashloop. Wider
+      # thresholds let it ride out the blip instead of being killed.
+      - |
+        kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+          -n karmada-system patch deploy karmada-apiserver --type=strategic \
+          -p '{"spec":{"template":{"spec":{"containers":[{"name":"karmada-apiserver","livenessProbe":{"timeoutSeconds":30,"failureThreshold":30,"periodSeconds":30,"initialDelaySeconds":60},"readinessProbe":{"timeoutSeconds":30,"failureThreshold":30,"periodSeconds":20}}]}}}}'
+
+  federation-build-kubeconfig:
+    internal: true
+    silent: true
+    vars:
+      HUB_KUBECONFIG: '{{.FEDERATION_KUBECONFIG_DIR}}/{{.FEDERATION_HUB_CLUSTER}}.yaml'
+      KARMADA_KUBECONFIG: '{{.FEDERATION_KUBECONFIG_DIR}}/karmada.yaml'
+    cmds:
+      - |
+        echo "Building Karmada kubeconfig → {{.KARMADA_KUBECONFIG}}"
+        # Extract the raw kubeconfig from the secret the Helm chart creates.
+        kubectl --kubeconfig={{.HUB_KUBECONFIG}} \
+          get secret karmada-kubeconfig -n karmada-system \
+          -o jsonpath='{.data.kubeconfig}' | base64 -d > {{.KARMADA_KUBECONFIG}}
+        # Rewrite the server to the NodePort exposed on localhost. The served cert
+        # is for the internal cluster IP, so drop the CA and skip TLS (local dev
+        # only). The CA must be unset BEFORE enabling insecure — kubectl rejects a
+        # config carrying both. Single-brace jsonpath is safe inline in the Taskfile.
+        ENTRY=$(kubectl --kubeconfig={{.KARMADA_KUBECONFIG}} config view -o jsonpath='{.clusters[0].name}')
+        kubectl --kubeconfig={{.KARMADA_KUBECONFIG}} config unset "clusters.${ENTRY}.certificate-authority-data" >/dev/null
+        kubectl --kubeconfig={{.KARMADA_KUBECONFIG}} config set-cluster "${ENTRY}" \
+          --server=https://127.0.0.1:{{.KARMADA_API_NODEPORT}} \
+          --insecure-skip-tls-verify=true >/dev/null
+        echo "  karmada server → https://127.0.0.1:{{.KARMADA_API_NODEPORT}}"
+      # Docker-bridge variant of the SAME identity for in-network reachers (e.g. a
+      # cell operator in another kind cluster): server = hub docker IP:NodePort.
+      - bash {{.REPO_DIR}}/hack/federation/make-internal-kubeconfig.sh {{.KARMADA_KUBECONFIG}} {{.FEDERATION_KUBECONFIG_DIR}}/karmada-internal.yaml {{.FEDERATION_HUB_CLUSTER}} {{.KARMADA_API_NODEPORT}}
+
+  federation-join-members:
+    internal: true
+    silent: true
+    vars:
+      KARMADA_KUBECONFIG: '{{.FEDERATION_KUBECONFIG_DIR}}/karmada.yaml'
+    cmds:
+      # cluster.karmada.io is served by the karmada-aggregated-apiserver through
+      # API aggregation, and can briefly return ServiceUnavailable after the pod
+      # reports Ready while the aggregation handshake settles. Wait for the API to
+      # actually answer before registering members so join does not race it.
+      - |
+        echo "Waiting for the cluster.karmada.io aggregated API to be served..."
+        deadline=$((SECONDS+180))
+        until kubectl --kubeconfig={{.KARMADA_KUBECONFIG}} get clusters &>/dev/null; do
+          if [ $SECONDS -ge $deadline ]; then
+            echo "ERROR: cluster.karmada.io was not served within 180s"; exit 1
+          fi
+          sleep 3
+        done
+        echo "cluster.karmada.io is served"
+      - for: { var: FEDERATION_MEMBERS, split: ' ' }
+        task: federation-join-member
+        vars:
+          MEMBER_SPEC: '{{.ITEM}}'
+      # "done" means every member has reached Ready.
+      - |
+        for m in {{.FEDERATION_MEMBERS}}; do
+          name="${m%%=*}"
+          [ -z "$name" ] && continue
+          echo "Waiting for cluster/$name to become Ready..."
+          kubectl --kubeconfig={{.KARMADA_KUBECONFIG}} wait --for=condition=Ready \
+            cluster/"$name" --timeout={{.WAIT_TIMEOUT}}
+        done
+        echo "All members Ready"
+
+  federation-join-member:
+    internal: true
+    silent: true
+    vars:
+      MEMBER_NAME: '{{splitList "=" .MEMBER_SPEC | first}}'
+      KARMADA_KUBECONFIG: '{{.FEDERATION_KUBECONFIG_DIR}}/karmada.yaml'
+    # Skip empty entries produced by trailing/double spaces in FEDERATION_MEMBERS.
+    status:
+      - test -z "{{.MEMBER_NAME}}"
+    cmds:
+      # ── Register with karmadactl join ──────────────────────────────────
+      # Pass the EXTERNAL kubeconfig (localhost-based) so karmadactl can reach the
+      # member from this host to set up initial RBAC; the stored secret is patched
+      # below to the Docker-IP variant. karmadactl join creates an impersonation
+      # ServiceAccount in the member and blocks (non-tunable internal timeout) on
+      # that SA's legacy token Secret being populated. On a busy host the member's
+      # token controller is slow, so the first join can time out even though the
+      # Secret populates moments later — retry, a later attempt reuses it and
+      # completes immediately.
+      - |
+        if kubectl --kubeconfig={{.KARMADA_KUBECONFIG}} \
+            get cluster {{.MEMBER_NAME}} &>/dev/null; then
+          echo "Cluster '{{.MEMBER_NAME}}' already registered in Karmada — skipping join"
+        else
+          echo "Joining '{{.MEMBER_NAME}}' to Karmada..."
+          joined=false
+          for attempt in 1 2 3 4 5; do
+            if {{.KARMADACTL}} join {{.MEMBER_NAME}} \
+                --kubeconfig={{.KARMADA_KUBECONFIG}} \
+                --cluster-kubeconfig={{.FEDERATION_KUBECONFIG_DIR}}/{{.MEMBER_NAME}}.yaml \
+                --cluster-context=kind-{{.MEMBER_NAME}}; then
+              joined=true
+              echo "Cluster '{{.MEMBER_NAME}}' registered (attempt ${attempt})"
+              break
+            fi
+            echo "join attempt ${attempt} failed (member token Secret may still be populating); retrying in 10s..."
+            sleep 10
+          done
+          if [ "${joined}" != "true" ]; then
+            echo "ERROR: failed to join '{{.MEMBER_NAME}}' after 5 attempts"; exit 1
+          fi
+        fi
+      # ── Patch cluster secret + apiEndpoint → Docker-IP kubeconfig ───────
+      # The Karmada controller manager runs inside Docker; it cannot use localhost
+      # to reach the member API server. Point the stored secret and the Cluster's
+      # apiEndpoint at the kind container's docker-bridge IP (the member never goes
+      # Ready otherwise — health checks keep probing the localhost address).
+      - bash {{.REPO_DIR}}/hack/federation/patch-cluster-secret.sh {{.KARMADA_KUBECONFIG}} {{.MEMBER_NAME}} {{.FEDERATION_KUBECONFIG_DIR}}/{{.MEMBER_NAME}}-internal.yaml
+      # ── Apply the topology label when the member spec carries one ───────
+      - |
+        SPEC='{{.MEMBER_SPEC}}'
+        case "$SPEC" in
+          *=*)
+            LABEL_VALUE="${SPEC#*=}"
+            echo "Labeling cluster '{{.MEMBER_NAME}}' {{.FEDERATION_MEMBER_LABEL_KEY}}=${LABEL_VALUE}"
+            kubectl --kubeconfig={{.KARMADA_KUBECONFIG}} label cluster {{.MEMBER_NAME}} \
+              {{.FEDERATION_MEMBER_LABEL_KEY}}="${LABEL_VALUE}" --overwrite
+            ;;
+          *)
+            echo "No label for cluster '{{.MEMBER_NAME}}' (spec has no '=<label>')"
+            ;;
+        esac
+
+  federation-write-env:
+    internal: true
+    silent: true
+    cmds:
+      # Shell-sourceable facts for consumers (e.g. a cell operator that needs the
+      # hub docker IP without re-deriving it). We read the hub docker IP back from
+      # karmada-internal.yaml's server rather than re-running docker inspect — the
+      # IP was already derived there, and that keeps the docker Go-template out of
+      # the Taskfile.
+      - |
+        HUB_SERVER=$(kubectl --kubeconfig={{.FEDERATION_KUBECONFIG_DIR}}/karmada-internal.yaml \
+          config view --minify -o jsonpath='{.clusters[0].cluster.server}')
+        # server is https://<hub-docker-ip>:<nodeport>; strip scheme and port.
+        HUB_IP=${HUB_SERVER#https://}
+        HUB_IP=${HUB_IP%:*}
+        cat > {{.FEDERATION_KUBECONFIG_DIR}}/federation.env <<EOF
+        FEDERATION_HUB_CLUSTER={{.FEDERATION_HUB_CLUSTER}}
+        FEDERATION_HUB_DOCKER_IP=${HUB_IP}
+        KARMADA_API_NODEPORT={{.KARMADA_API_NODEPORT}}
+        FEDERATION_MEMBERS="{{.FEDERATION_MEMBERS}}"
+        EOF
+        echo "Wrote {{.FEDERATION_KUBECONFIG_DIR}}/federation.env (hub docker IP ${HUB_IP})"
diff --git a/cluster/federation/kind-hub.yaml b/cluster/federation/kind-hub.yaml
new file mode 100644
index 0000000..58eed82
--- /dev/null
+++ b/cluster/federation/kind-hub.yaml
@@ -0,0 +1,43 @@
+# Kind cluster configuration for the federation hub (Karmada control plane).
+#
+# extraPortMappings exposes the Karmada API server NodePort on the host so the
+# Karmada API server is reachable at https://localhost:${KARMADA_API_NODEPORT}
+# without any additional port-forwarding. Both the container port and the host
+# port are rendered from ${KARMADA_API_NODEPORT} via envsubst (the Taskfile
+# preprocesses this file the same way it does cluster/kind-config.yaml), so the
+# NodePort has a single source of truth. This matches the Karmada chart's
+# apiServer.nodePort and the KARMADA_API_NODEPORT Task var.
+
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+# Tune the hub for a busy host that also runs the full Karmada control plane in
+# this same cluster. kind renders its kubeadm config as v1beta3, so extraArgs are
+# maps here (not the v1beta4 list form).
+#   - etcd unsafe-no-fsync: these are throwaway federation clusters, and fsync
+#     contention between co-located etcds is what drives API server write
+#     latency into multi-second spikes.
+#   - scheduler/controllerManager leader-elect=false: single-instance static
+#     pods have nothing to elect, and a lease renewal that times out during a
+#     latency spike crash-loops them (which then re-lists everything and makes
+#     the spike worse).
+kubeadmConfigPatches:
+  - |
+    apiVersion: kubeadm.k8s.io/v1beta3
+    kind: ClusterConfiguration
+    etcd:
+      local:
+        extraArgs:
+          unsafe-no-fsync: "true"
+    controllerManager:
+      extraArgs:
+        leader-elect: "false"
+    scheduler:
+      extraArgs:
+        leader-elect: "false"
+nodes:
+  - role: control-plane
+    extraPortMappings:
+      - containerPort: ${KARMADA_API_NODEPORT}   # Karmada API server NodePort
+        hostPort: ${KARMADA_API_NODEPORT}
+        protocol: TCP
+        listenAddress: "127.0.0.1"
diff --git a/cluster/federation/kind-member.yaml b/cluster/federation/kind-member.yaml
new file mode 100644
index 0000000..88b79b4
--- /dev/null
+++ b/cluster/federation/kind-member.yaml
@@ -0,0 +1,25 @@
+# Kind cluster configuration for federation member (Karmada-joined) clusters.
+#
+# Same control-plane tuning as the hub (see kind-hub.yaml for the rationale):
+# etcd runs without fsync and the single-instance scheduler and controller-manager
+# run without leader election, so the member control planes stay stable on a busy
+# host instead of crash-looping on lease-renewal timeouts. kind renders its
+# kubeadm config as v1beta3, so extraArgs are maps here.
+#
+# Unlike the hub, members need no extraPortMappings.
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+kubeadmConfigPatches:
+  - |
+    apiVersion: kubeadm.k8s.io/v1beta3
+    kind: ClusterConfiguration
+    etcd:
+      local:
+        extraArgs:
+          unsafe-no-fsync: "true"
+    controllerManager:
+      extraArgs:
+        leader-elect: "false"
+    scheduler:
+      extraArgs:
+        leader-elect: "false"
diff --git a/components/flux/kustomization.yaml b/components/flux/kustomization.yaml
index d8f5711..6c198df 100644
--- a/components/flux/kustomization.yaml
+++ b/components/flux/kustomization.yaml
@@ -1,7 +1,7 @@
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
-  # Using installer manifests from Flux v2.3.0
+  # Using installer manifests from Flux v2.7.5
   - github.com/fluxcd/flux2/manifests/install?ref=v2.7.5
 
 patches:
diff --git a/components/karmada/values.yaml b/components/karmada/values.yaml
new file mode 100644
index 0000000..a532382
--- /dev/null
+++ b/components/karmada/values.yaml
@@ -0,0 +1,14 @@
+# Helm values for the Karmada control plane installed on the federation hub.
+#
+# Only static chart values live here. All runtime tuning (etcd --unsafe-no-fsync,
+# leader-election disable, apiserver probe relaxation) intentionally lives in the
+# Taskfile as post-install kubectl patches: the chart does not expose the etcd
+# StatefulSet command args or the apiserver probe fields as values, so splitting
+# the tuning half here and half there would be worse than keeping it in one
+# mechanism. See the federation-tune-karmada task for the rationale on each patch.
+#
+# The API NodePort is passed on the helm command line (--set apiServer.nodePort)
+# from KARMADA_API_NODEPORT so the port has a single source of truth shared with
+# the hub kind config.
+apiServer:
+  serviceType: NodePort
diff --git a/hack/ensure-tools.sh b/hack/ensure-tools.sh
index 489f715..ba6fa13 100755
--- a/hack/ensure-tools.sh
+++ b/hack/ensure-tools.sh
@@ -82,6 +82,16 @@ install_flux() {
   fi
 }
 
+install_helm() {
+  if ! command -v helm &>/dev/null; then
+    echo "Installing helm..."
+    case "$OS" in
+      darwin|linux) curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash ;;
+      msys*|mingw*|cygwin*) choco install kubernetes-helm -y || winget install Helm.Helm ;;
+    esac
+  fi
+}
+
 for tool in "${TOOLS[@]}"; do
   install_${tool} || true
 done
diff --git a/hack/federation/make-internal-kubeconfig.sh b/hack/federation/make-internal-kubeconfig.sh
new file mode 100755
index 0000000..51882c7
--- /dev/null
+++ b/hack/federation/make-internal-kubeconfig.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# make-internal-kubeconfig.sh <input-kubeconfig> <output-kubeconfig> <kind-cluster-name> [<port>]
+#
+# Produces a kubeconfig variant that uses a Kind node's Docker container IP
+# instead of localhost. Two callers use it:
+#   - member internals: the variant stored in Karmada so the controller manager
+#     (running inside Docker) can reach member cluster API servers across the
+#     kind bridge network — port defaults to 6443 (the in-container API port).
+#   - karmada-internal.yaml: the hub apiserver reached from inside the docker
+#     network — input is karmada.yaml, cluster name is the hub, and the port is
+#     the Karmada API NodePort.
+#
+# Background: Kind maps each cluster's API server to a random localhost port on
+# the developer machine. Inside Docker containers, "localhost" refers to the
+# container's own loopback — not the host. We therefore swap the server address
+# to the Kind control-plane container's Docker bridge IP (e.g. 172.18.0.x) and
+# set insecure-skip-tls-verify because the node certificate does not include the
+# Docker bridge IP in its SANs.
+#
+# Usage:
+#   hack/federation/make-internal-kubeconfig.sh \
+#     kubeconfigs/federation/compute-pop-dfw.yaml \
+#     kubeconfigs/federation/compute-pop-dfw-internal.yaml \
+#     compute-pop-dfw
+#
+#   hack/federation/make-internal-kubeconfig.sh \
+#     kubeconfigs/federation/karmada.yaml \
+#     kubeconfigs/federation/karmada-internal.yaml \
+#     federation-hub \
+#     32443
+
+set -euo pipefail
+
+INPUT="${1:?usage: $0 <input-kubeconfig> <output-kubeconfig> <kind-cluster-name> [<port>]}"
+OUTPUT="${2:?usage: $0 <input-kubeconfig> <output-kubeconfig> <kind-cluster-name> [<port>]}"
+CLUSTER_NAME="${3:?usage: $0 <input-kubeconfig> <output-kubeconfig> <kind-cluster-name> [<port>]}"
+# Kind API server always listens on port 6443 inside the container; the hub's
+# NodePort variant overrides this.
+PORT="${4:-6443}"
+
+CONTAINER_NAME="${CLUSTER_NAME}-control-plane"
+
+# Resolve the container's Docker bridge IP. This docker-inspect Go-template must
+# live in a shell script, never inline in the Taskfile — its {{...}} collides
+# with Task's own templating.
+DOCKER_IP=$(docker inspect \
+  -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' \
+  "${CONTAINER_NAME}" 2>/dev/null || true)
+
+if [ -z "${DOCKER_IP}" ]; then
+  echo "ERROR: Could not resolve Docker IP for container '${CONTAINER_NAME}'." >&2
+  echo "       Is the Kind cluster '${CLUSTER_NAME}' running?" >&2
+  exit 1
+fi
+
+echo "  ${CLUSTER_NAME}: Docker IP ${DOCKER_IP}:${PORT} → ${OUTPUT}"
+
+# Start from a copy of the input, then rewrite its server in place with kubectl
+# config (no PyYAML dependency). The cluster's entry name is read from the
+# kubeconfig itself so this works for both kind-exported configs (kind-<name>)
+# and the Karmada secret's config (karmada). The certificate-authority-data must
+# be unset BEFORE enabling insecure-skip-tls-verify — kubectl rejects a config
+# that carries both a CA and the insecure flag.
+cp "${INPUT}" "${OUTPUT}"
+ENTRY=$(kubectl --kubeconfig="${OUTPUT}" config view -o jsonpath='{.clusters[0].name}')
+kubectl --kubeconfig="${OUTPUT}" config unset "clusters.${ENTRY}.certificate-authority-data" >/dev/null
+kubectl --kubeconfig="${OUTPUT}" config set-cluster "${ENTRY}" \
+  --server="https://${DOCKER_IP}:${PORT}" \
+  --insecure-skip-tls-verify=true >/dev/null
diff --git a/hack/federation/patch-cluster-secret.sh b/hack/federation/patch-cluster-secret.sh
new file mode 100755
index 0000000..0062510
--- /dev/null
+++ b/hack/federation/patch-cluster-secret.sh
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# patch-cluster-secret.sh <karmada-kubeconfig> <cluster-name> <internal-kubeconfig>
+#
+# After "karmadactl join", Karmada stores the member cluster's kubeconfig in a
+# Secret referenced by the Cluster object's spec.secretRef, and sets
+# spec.apiEndpoint to the localhost address it resolved from the external
+# kubeconfig. The Karmada controller manager runs inside Docker and cannot use
+# localhost to reach member cluster API servers.
+#
+# This script:
+#   1. Replaces the kubeconfig in the Secret with the Docker-IP variant so that
+#      the Karmada controller can make API calls to the member cluster.
+#   2. Patches spec.apiEndpoint on the Cluster object so that health checks also
+#      use the Docker bridge IP instead of localhost.
+
+set -euo pipefail
+
+KARMADA_KUBECONFIG="${1:?usage: $0 <karmada-kubeconfig> <cluster-name> <internal-kubeconfig>}"
+CLUSTER_NAME="${2:?usage: $0 <karmada-kubeconfig> <cluster-name> <internal-kubeconfig>}"
+INTERNAL_KUBECONFIG="${3:?usage: $0 <karmada-kubeconfig> <cluster-name> <internal-kubeconfig>}"
+
+# ------------------------------------------------------------------
+# Read the Cluster object's secretRef (name + namespace)
+# ------------------------------------------------------------------
+SECRET_NAME=$(kubectl \
+  --kubeconfig="${KARMADA_KUBECONFIG}" \
+  get cluster "${CLUSTER_NAME}" \
+  -o jsonpath='{.spec.secretRef.name}' 2>/dev/null || true)
+
+if [ -z "${SECRET_NAME}" ]; then
+  echo "ERROR: Could not find spec.secretRef.name on cluster '${CLUSTER_NAME}'." >&2
+  echo "       Has karmadactl join completed successfully?" >&2
+  exit 1
+fi
+
+SECRET_NAMESPACE=$(kubectl \
+  --kubeconfig="${KARMADA_KUBECONFIG}" \
+  get cluster "${CLUSTER_NAME}" \
+  -o jsonpath='{.spec.secretRef.namespace}' 2>/dev/null || true)
+
+SECRET_NAMESPACE="${SECRET_NAMESPACE:-karmada-system}"
+
+echo "  Patching secret ${SECRET_NAMESPACE}/${SECRET_NAME} with Docker-IP kubeconfig..."
+
+# ------------------------------------------------------------------
+# Replace the kubeconfig data in the secret
+# ------------------------------------------------------------------
+kubectl \
+  --kubeconfig="${KARMADA_KUBECONFIG}" \
+  create secret generic "${SECRET_NAME}" \
+  --namespace="${SECRET_NAMESPACE}" \
+  --from-file=kubeconfig="${INTERNAL_KUBECONFIG}" \
+  --dry-run=client -o yaml \
+  | kubectl \
+      --kubeconfig="${KARMADA_KUBECONFIG}" \
+      apply -f -
+
+echo "  Secret ${SECRET_NAMESPACE}/${SECRET_NAME} updated — Karmada controller will use Docker bridge IP"
+
+# ------------------------------------------------------------------
+# Extract the Docker-IP server URL from the internal kubeconfig and
+# patch spec.apiEndpoint on the Cluster object so that Karmada's
+# cluster-status controller uses the same reachable address for health
+# checks. Without this patch the controller continues to probe the
+# localhost address stored by karmadactl join and the cluster never
+# transitions to Ready.
+# ------------------------------------------------------------------
+DOCKER_SERVER=$(kubectl \
+  --kubeconfig="${INTERNAL_KUBECONFIG}" \
+  config view --minify -o jsonpath='{.clusters[0].cluster.server}')
+
+if [ -z "${DOCKER_SERVER}" ]; then
+  echo "ERROR: Could not read server URL from ${INTERNAL_KUBECONFIG}" >&2
+  exit 1
+fi
+
+echo "  Patching spec.apiEndpoint on cluster '${CLUSTER_NAME}' → ${DOCKER_SERVER}..."
+kubectl \
+  --kubeconfig="${KARMADA_KUBECONFIG}" \
+  patch cluster "${CLUSTER_NAME}" \
+  --type=merge \
+  -p "{\"spec\":{\"apiEndpoint\":\"${DOCKER_SERVER}\"}}"
+
+echo "  Cluster '${CLUSTER_NAME}' patched — health checks will now use Docker bridge IP"