Add multicloud federated learning parttern

content/patterns/multicloud-federated-learning/_index.adoc

@@ -0,0 +1,79 @@
+---
+title: Multicloud Federated Learning
+date: 2025-05-23
+summary: This pattern helps you develop and deploy federated learning applications on an open hybrid cloud via Open Cluster Management.
+rh_products:
+- Red Hat Advanced Cluster Management
+- Red Hat OpenShift Container Platform
+industries:
+- General
+aliases: /multicloud-federated-learning/
+links:
+  install: getting-started
+  help: https://groups.google.com/g/validatedpatterns
+  bugs: https://github.com/open-cluster-management-io/addon-contrib/issues
+ci: multicloudfederatedlearning
+---
+
+:toc:
+:imagesdir: /images
+:_content-type: ASSEMBLY
+include::modules/comm-attributes.adoc[]
+
+== Multicloud Federated Learning
+
+=== Background
+
+As machine learning (ML) evolves, protecting data privacy becomes increasingly important. Since ML depends on large volumes of data, it's essential to secure that data without disrupting the learning process.
+
+Federated Learning (FL) addresses this by allowing multiple clusters or organizations to collaboratively train models without sharing sensitive data. Computation happens where the data lives, ensuring privacy, regulatory compliance, and efficiency.
+
+By integrating FL with Advanced Cluster Management (ACM), this pattern provides an automated and scalable solution for deploying FL workloads across hybrid and multicluster environments.
+
+==== Technologies 
+* Open Cluster Management (OCM)
+  - ManagedCluster
+  - ManifestWork
+  - Placement
+  ...
+* Federated Learning frameworks 
+  - Flower
+  - OpenFL
+  ...
+* Grafana
+* OpenTelemetry
+
+=== Why Use Advanced Cluster Management for Federated Learning?
+
+**Advanced Cluster Management (ACM)** simplifies and automates the deployment and orchestration of Federated Learning (FL) workloads across clusters:
+
+- **Automatic Deployment & Simplified Operations**: ACM provides a unified and automated approach to running FL workflows across different runtimes (e.g., Flower, OpenFL). Its controller manages the entire FL lifecycle—including setup, coordination, status tracking, and teardown—across multiple clusters in a multicloud environment. This eliminates repetitive manual configurations, significantly reduces operational overhead, and ensures consistent, scalable FL deployments.
+
+- **Dynamic Client Selection**: ACM's scheduling capabilities allow FL clients to be selected not only based on where the data resides, but also dynamically based on cluster labels, resource availability, and governance criteria. This enables a more adaptive and intelligent approach to client participation.
+
+Together, these capabilities support a **flexible FL client model**, where clusters can join or exit the training process dynamically, without requiring static or manual configuration.
+
+=== Benefits
+
+- 🔒 Privacy-preserving training without moving sensitive data
+
+- ⚙️ Automated dynamic FL client orchestration across distributed clusters
+
+- 🧩 Adaptable to different FL frameworks, such as OpenFL and Flower
+
+- 🌍 Scalability across hybrid and edge clusters
+
+- 📉 Lower infrastructure and operational costs
+
+This approach empowers organizations to build smarter, privacy-first AI solutions with less complexity and more flexibility.
+
+=== Architecture
+
+image::/images/multicloud-federated-learning/multicluster-federated-learning-workflow.png[multicloud-federated-learning-workflow]
+
+- In this architecture, a central **Hub Cluster** acts as the aggregator, running the Federated Learning (FL) controller and scheduling workloads using ACM APIs like `Placement` and `ManifestWork`. 
+
+- Multiple **Managed Clusters**, potentially across different clouds, serve as FL clients—each holding private data. These clusters pull the global model from the hub, train it locally, and push model updates back. 
+
+- The controller manages this lifecycle using custom resources and supports runtimes like Flower and OpenFL. This setup enables scalable, multi-cloud model training with **data privacy preserved by design**, requiring no changes to existing FL training code.
+

content/patterns/multicloud-federated-learning/getting-started.adoc

@@ -0,0 +1,233 @@
+---
+title: Getting Started
+weight: 10
+aliases: /multicloud-federated-learning/getting-started/
+---
+
+:toc:
+:imagesdir: /images
+:_content-type: ASSEMBLY
+include::modules/comm-attributes.adoc[]
+
+== Deploying the Multicloud Federated Learning Pattern
+
+=== Prerequisites
+
+==== Ensure the following tools are installed:
+
+- link:https://kubernetes.io/docs/reference/kubectl/[`kubectl`]
+- link:https://kubectl.docs.kubernetes.io/installation/kustomize/[`kustomize`]
+- link:https://kind.sigs.k8s.io/[`kind`] (recommended version > v0.9.0)
+- link:https://www.gnu.org/software/make/[`make`] (for build automation)
+
+==== Optional (for container image building):
+
+- link:https://podman.io/[Podman] or link:https://www.docker.com/[Docker]
+- link:https://go.dev/doc/install[Go] (version 1.19 or higher)
+
+===== Advanced Cluster Management Environment
+
+Prepare at least three clusters: one hub cluster and two managed clusters.
+
+Verify the managed clusters are registered on the hub by running:
+
+[source,bash]
+----
+$ kubectl get mcl
+----
+
+Example output:
+[source,bash]
+----
+NAME       HUB ACCEPTED   MANAGED CLUSTER URLS                  JOINED   AVAILABLE   AGE
+cluster1   true           https://api.***.com:6443              True     True        5m
+cluster2   true           https://api.***.com:6443              True     True        5m
+----
+
+=== Deploy Federated Learning Controller
+
+. Clone and navigate to the repository:
++
+[source,bash]
+----
+$ git clone git@github.com:open-cluster-management-io/addon-contrib.git
+$ cd federated-learning-controller
+----
+
+. Build and push the controller image (or use pre-built `quay.io/myan/federated-learning-controller:latest`):
++
+[source,bash]
+----
+$ make docker-build docker-push IMG=<IMG> 
+----
+
+. Deploy the controller to the hub cluster:
++
+[source,bash]
+----
+$ kubectl config use-context kind-hub
+$ make deploy IMG=<controller-image> NAMESPACE=<controller-namespace(default is open-cluster-management)>
+----
+
+. Verify the deployment:
++
+The federated learning controller is running in the open-cluster-management namespace by default.
++
+[source,bash]
+----
+$ kubectl get pods -n open-cluster-management
+----
++
+Example output
++
+[source,bash]
+----
+NAME                                            READY   STATUS      RESTARTS   AGE
+cluster-manager-d9db64db5-c7kfj                 1/1     Running     0          3d22h
+cluster-manager-d9db64db5-t7grh                 1/1     Running     0          3d22h
+cluster-manager-d9db64db5-wndd8                 1/1     Running     0          3d22h
+federated-learning-controller-d7df846c9-nb4wc   1/1     Running     0          3d22h
+----
+
+=== Deploy the Federated Learning Instance
+
+. Build the Application Image
++
+*Note*: You can skip this step by using the pre-built image `quay.io/myan/flower-app-torch:latest`.
++
+[source,bash]
+----
+$ cd examples/flower
+
+$ export REGISTRY=<your-registry>
+$ export IMAGE_TAG=<your-tag>
+$ make build-app-image
+$ make push-app-image
+----
++ 
+Image format: `<REGISTRY>/flower-app-torch:<IMAGE_TAG>`
+
+. Deploy a Federated Learning Instance
++
+In this example, both the server and clients use the same image—either the one built above or the pre-built `quay.io/myan/flower-app-torch:latest`. Once the resource is created, the server is deployed to the hub cluster, and the clients are prepared for deployment to the managed clusters.
++
+Create a `FederatedLearning` resource in the controller namespace on the hub cluster:
++
+[source,yaml]
+----
+apiVersion: federation-ai.open-cluster-management.io/v1alpha1
+kind: FederatedLearning
+metadata:
+  name: federated-learning-sample
+spec:
+  framework: flower
+  server:
+    image: <REGISTRY>/flower-app-torch:<IMAGE_TAG>
+    rounds: 3
+    minAvailableClients: 2
+    listeners:
+      - name: server-listener
+        port: 8080
+        type: LoadBalancer
+    storage:
+      type: PersistentVolumeClaim
+      name: model-pvc
+      path: /data/models
+      size: 2Gi
+  client:
+    image: <REGISTRY>/flower-app-torch:<IMAGE_TAG>
+    placement:
+      clusterSets:
+        - global
+      predicates:
+        - requiredClusterSelector:
+            claimSelector:
+              matchExpressions:
+                - key: federated-learning-sample.client-data
+                  operator: Exists
+----
+
+. Schedule the Federated Learning Clients into Managed Clusters
++
+The above configuration schedules only clusters with a `ClusterClaim` having the key `federated-learning-sample.client-data`. You can combine this with other scheduling policies (refer to the Placement API for details).
++
+Add the `ClusterClaim` to these clusters own the data for the client:
+
+.. **Cluster1: **
++
+[source,bash]
+----
+$ kubectl config use-context kind-cluster1
+
+$ cat <<EOF | kubectl apply -f -
+apiVersion: cluster.open-cluster-management.io/v1alpha1
+kind: ClusterClaim
+metadata:
+  name: federated-learning-sample.client-data
+spec:
+  value: /data/private/cluster1
+EOF
+----
+
+.. **Cluster2: **
++
+[source,bash]
+----
+$ kubectl config use-context kind-cluster2
+$ cat <<EOF | kubectl apply -f -
+apiVersion: cluster.open-cluster-management.io/v1alpha1
+kind: ClusterClaim
+metadata:
+  name: federated-learning-sample.client-data
+spec:
+  value: /data/private/cluster2
+EOF
+----
+
+. Check the Federated Learning Instance Status
+
+.. After creating the instance, the server initially shows a status of `Waiting`
++
+*Example - server in hub cluster:*
++
+[source,bash]
+----
+$ kubectl get pods
+NAME                                            READY   STATUS      RESTARTS   AGE
+federated-learning-sample-server-7jnfs          0/1     Completed   0          9m
+----
+
+.. Once the required clients are ready, status changes to `Running`
++
+*Example - client in managed cluster:*
++
+[source,bash]
+----
+$ kubectl get pods -n open-cluster-management
+NAME                                     READY   STATUS      RESTARTS   AGE
+federated-learning-sample-client-75sc8   0/1     Completed   0          8m
+----
+
+.. After the training and aggregation rounds complete, the status becomes `Completed`
++
+*Example - Federated Learning instance:*
++
+[source,bash]
+----
+status:
+  listeners:
+  - address: 172.18.0.2:31166
+    name: listener(service):federated-learning-sample-server
+    port: 31166
+    type: NodePort
+  message: Model training successful. Check storage for details
+  phase: Completed
+----
+
+.. Download and Verify the Trained Model
++
+The trained MNIST model is saved in the `model-pvc` volume.
++
+- link:https://github.com/open-cluster-management-io/addon-contrib/blob/main/federated-learning-controller/examples/notebooks/deploy[Deploy a Jupyter notebook server]
+- link:https://github.com/open-cluster-management-io/addon-contrib/blob/main/federated-learning-controller/examples/notebooks/1.hub-evaluation.ipynb[Validate the model]
+

modules/comm-attributes.adoc

@@ -26,6 +26,7 @@
 :ie-pattern: Industrial Edge pattern
 :ie: Industrial Edge
 :fe-pattern: Federated Edge Observability pattern
+:mcfl-parttern: Multicloud Federated Learning pattern
 :mcg-pattern: Multicloud GitOps pattern
 :amx-mcg-pattern: Intel AMX accelerated Multicloud GitOps pattern
 :mcg-sgx-hello-world-pattern: Intel SGX protected application in Multicloud GitOps pattern