Federated Execution Manager (FEM) - Cliente Local

El Federated Execution Manager (FEM) es un componente de software diseñado para coordinar y gestionar la ejecución de procesos distribuidos en un entorno de computación federada (FL) o descentralizado donde múltiples dispositivos o clientes (los nodos de datos federados o FDN), proporcionan recursos de cómputo y datos.

¿Qué es FEM?

FEM es responsable de controlar y orquestar el ciclo de vida de las tareas federadas. Consta de dos partes:

  • un módulo orquestador (FEM-orchestrator) que garantiza que las tareas lleguen a los múltiples FDN de forma segura y coordinada

  • un módulo cliente (FEM-client) instalado en el FDN participante que recoge dichas tareas y las asigna en la infraestructura local.

En resumen, el FEM-client interactúa con el FEM-orchestrator a través de un broker de mensajes (RabbitMQ) y obtiene los detalles de las tareas federadas a través de múltiples nodos de datos federados (FDN). El cliente FEM trabaja junto con el orquestador central FEM para gestionar flujos de trabajo de computación distribuida, como experimentos de aprendizaje federado (FL) y otras tareas de procesamiento de datos.

arch

¿Qué es FEM-client?

Las funciones clave del cliente FEM incluyen:

  • Recepción de tareas: asegura interacciones seguras entre el FDN y el orquestador central mediante un broker de mensajes (RabbitMQ) y obtiene los detalles de la tarea federada.

  • Stage-in de tareas: prepara el entorno de trabajo, gestionando volúmenes de datos, la descarga de imágenes de contenedor y las sincronizaciones de código fuente con Git.

  • Ejecución de tareas: ejecuta tareas en la infraestructura local delegando la gestión de recursos a los ejecutores o launchers personalizables. El ejecutor predeterminado es «docker».

  • Stage-out de tareas: intercambia los archivos de salida y los archivos de registro necesarios con el orquestador central.

Requisitos mínimos de infraestructura

  • Para ejecutar el FEM-client, el nodo desplegado debe proporcionar un entorno computacional básico capaz de ejecutar tareas federadas localmente:

    • Requisitos técnicos mínimos:

      • S.O. basado en Unix

      • Docker y Docker Compose

      • 2 CPUs y 4 GB de RAM

    • Requisitos mínimos de conectividad del cliente:

      • Conexión saliente al servidor RabbitMQ

      • Puerto del servicio IMPacT: 8071 (AMQPS 1.0 sobre TLS)

      • Destino: IP o FQDN del servidor FEM (https://rbtmq.impact-data.bsc.es:8071)

  • FEM-client incluye una interfaz similar a TES (Task Execution Service) que se comunica a través de RabbitMQ.

  • Se espera que el nodo:

    • Use sus recursos informáticos locales (por ejemplo, clúster, servidor, nodo HPC, etc.).

    • Mapee las acciones estándar de TES (por ejemplo, enviar trabajo, consultar estado, listar trabajos, eliminar trabajo) a su infraestructura local.

    • Este mapeo se realiza a través del archivo localconfig en FEM-client, que vincula las acciones TES a APIs locales o a herramientas/scripts de línea de comandos ya en uso en el sitio. Esta arquitectura flexible asegura que FEM-client pueda integrarse con una amplia variedad de sistemas mientras mantiene la localidad de datos y la autonomía.

Por favor, considera que las herramientas, pipelines o frameworks FL lanzados por FEM pueden necesitar de sus propios requisitos de conectividad.

Opcional: configuración de GPU

Esta sección no es obligatoria, pero si el sistema host no está configurado correctamente, FEM-client no podrá usar las GPU. En cualquier caso, FEM-client está preparado para volver a CPU si la configuración falla.

# Check if nvidia drivers and utils are installed in the system
nvidia-smi -L

Example of expected output (anything that’s not an error):

GPU 0: NVIDIA GeForce RTX 3060 (UUID: GPU-b90ebde0-2285-0f1e-249e-55dc6dd7abf1)

nvidia-container-runtime --version

Example of expected output (anything that’s not an error):

Nvidia Container Runtime Hook Version 1.17.7 commit: bae3e7842ebe26812d8bd6a9be6a14a83dc91d8f

docker info | grep -A5 Runtimes

Example of expected output (nvidia included in runtimes):

 Runtimes: oci runc io.containerd.runc.v2 nvidia
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 05044ec0a9a75232cad458027ca83437aae3f4da
 runc version: v1.1.14-0-g2c9f5602f0ba
 init version:

If any of the previous gives an error, install the needed packages, drivers or config from the ones provided: sudo apt update

# Install/Update nvidia drivers
### CAUTION: Updating NVIDIA drivers may affect existing GPU workloads or compatibility. Ensure you review driver requirements and test appropriately in your environment. Repalce -570- by the most adequated for your local installation ###
sudo apt install nvidia-driver-570-server
sudo apt install nvidia-utils-570-server

# Install the nvidia-container-toolkit
# Point to the necessary repositories:
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update
sudo apt install nvidia-container-toolkit

# Let docker allow nvidia as runtime:
sudo nano /etc/docker/daemon.json

Paste this inside:

{
       "runtimes": {
        "nvidia": {
            "args": [],
            "path": "nvidia-container-runtime"
        }
   }
}

If any of the changes were made, restart the docker runner:

# Restart docker
sudo systemctl restart docker 

# Retry commands of previous block

Primeros pasos

  1. Clona el repositorio:

git clone https://gitlab.bsc.es/fl/fem-client.git

  1. Navega al directorio del proyecto:

cd fem-client

  1. Prepara los archivos de configuración:

Asociado a cada proyecto/federación (y normalmente bajo acceso restringido), existe un repositorio con los archivos de configuración de FEM-client ya preconfigurados para conectarse al nodo orquestador del proyecto/federación. Pide instrucciones y acceso a tu responsable de federación/proyecto.

Dentro de la carpeta fem-client/, clona el repositorio proporcionado y sigue sus instrucciones:

git clone https://gitlab.bsc.es/fl/IMPACT-DATA-fem-client-config.git

La estructura resultante después de seguir las instrucciones debería verse así:

fem-client/
├── config/
│   └── config.py
└── app/
│   └── [...]
├── Dockerfile

  1. Inicia el cliente Una vez configurada la carpeta config:

bash setup_service.sh

  1. Supervisa el receptor: docker logs -f fem-client

Instalación de FEM-client (desde la imagen)

Si el proceso falla durante el docker build, existe la opción de descargar la imagen preconstruida de este proyecto:

  1. Descarga la imagen del registro de Docker. Las credenciales para iniciar sesión se transmitiran separadamente.

docker login gitlab.bsc.es
docker pull registry.gitlab.bsc.es/fl/fem-client:v3.0.0
docker logout #optional, if you don't want to keep logged in in this machine

  1. Una vez terminada la descarga, comprueba que Docker puede encontrarla con el siguiente comando: docker images

Si registry.gitlab.bsc.es/fl/fem-client aparece en la lista, sigue los pasos 1-5 de la sección “Primeros pasos”, y docker-compose ejecutará el proyecto desde la imagen en lugar de construirlo desde cero.

Desarrollo de una herramienta para ejecuciones FEM (opcional para desarrolladores de herramientas)

Para integrar una herramienta (un pipeline analítico, un predictor de modelo IA, etc.) con FEM-client, se requieren dos partes principales:

  1. Empaquetado de la herramienta: la herramienta debe empaquetarse como un contenedor.

  2. Registro de la herramienta en FEM-Orchestrator: la herramienta debe añadirse a la base de datos del FEM-Orchestrator.

1. Empaquetado de la herramienta

Ten en cuenta los siguientes puntos al construir el contenedor de la herramienta:

Cumplimiento del motor de contenedores local

FEM-client admite múltiples backends de ejecución de contenedores a través de launchers. Asegúrate de que el contenedor de tu herramienta sea compatible con al menos uno de los siguientes:

Launcher

Descripción

Requisitos del nodo

Requisitos de la herramienta

Docker

Predeterminado. Interactúa con Docker Client

Docker CE versión 19.1 o superior

Contenedor Docker

JobMan

Un gestor de trabajos Kubernetes

Jobman y K8s

Contenedor de pod y aplicación

Ejecución del contenedor

  • La herramienta debe ejecutarse de forma no interactiva (sin entrada de usuario en tiempo de ejecución).

  • Los parámetros deben pasarse como argumentos de línea de comandos.

  • El contenedor debe ejecutarse con el mismo UID:GID que FEM-client, garantizando que FEM-client pueda acceder y eliminar cualquier archivo generado en el volumen sandbox.

Manejo de datos

FEM-client lanzará el contenedor de la herramienta con los siguientes volúmenes de datos, aunque se pueden especificar volúmenes adicionales en la base de datos (ver paso 2):

  • Volumen de datos (dentro de la ruta de host $DATA_PATH): montado como solo lectura (ro). Contiene los archivos de entrada proporcionados por el nodo de datos federado.

  • Volumen sandbox de usuario (dentro de la ruta de host $SANDBOX_PATH): montado como lectura/escritura (rw). Es el directorio de trabajo donde la herramienta puede escribir archivos temporales y de salida de una ejecución. Cualquier argumento de línea de comandos que haga referencia a archivos o directorios debe asumir que las rutas deben estar dentro de estos volúmenes.

Salida y registro

  • La herramienta debe escribir sus resultados en el volumen sandbox de usuario para que FEM-client pueda recuperarlos. Los registros deben imprimirse en stdout/stderr para una supervisión adecuada.

Permisos y contexto de ejecución

Dado que FEM-client se ejecuta bajo un UID:GID específico, asegúrate de que:

  • La herramienta no cree archivos como root dentro del volumen sandbox.

  • La herramienta establezca correctamente la propiedad y los permisos de los archivos para permitir que FEM-client lea y elimine archivos después de la ejecución.

  • Usa chown dentro del contenedor si es necesario para establecer la propiedad correctamente:

chown $(id -u):$(id -g) /sandbox/output-file.csv

  • Evita establecer permisos de archivos excesivamente restrictivos (por ejemplo, chmod 600), ya que FEM-client necesita gestionar el contenido del sandbox.

Comportamiento de salida

El contenedor debe finalizar con un código de salida significativo, ya que FEM-client lo recogerá (State.ExitCode) de la ejecución del contenedor para detectar y reaccionar adecuadamente a fallos de ejecución:

  • 0 → Ejecución exitosa

  • Distinto de cero → Ejecución fallida (debe proporcionar mensajes de error relevantes)

Ejemplo de ejecución

docker run --rm \
  --user $UID:$GID \ # Run under the same UID:GID as FEM-client
  -v $DATA_PATH:/data:ro \
  -v $SANDBOX_PATH:/sandbox:rw \
  -e NODE_NAME:$node_name   \
  my-tool-image \
    --input /data/input-file.csv \
    --output /sandbox/local_weights.json
    --my_threshold 33 \
    --logfile /sanbox/myTool.log
    --errfile /sandbox/myErr.log

Donde:

  • $DATA_PATH: directorio raíz de los conjuntos de datos a los que el nodo de datos federado permite acceso (por ejemplo, imágenes, registros clínicos, etc.). Valor tomado del archivo de configuración del nodo FEM-client. El punto de montaje del contenedor (/data en el ejemplo anterior) puede configurarse libremente a cualquier ruta estática en el contenedor según los requisitos de la herramienta. Aun así, debe configurarse correctamente más tarde en la base de datos de FEM-client (ver paso 2).

  • $SANDBOX_PATH: corresponde a la ruta absoluta de la carpeta donde se espera que se creen los resultados de esa ejecución de usuario en particular. El punto de montaje del contenedor (/sandbox en el ejemplo anterior) puede configurarse libremente a una ruta estática en el contenedor según los requisitos de la herramienta. Aun así, debe configurarse correctamente más tarde en la base de datos de FEM-client (ver paso 2).

  • $UID y $GID: corresponden al identificador de usuario y al identificador de grupo (sin privilegios) que ejecutan el contenedor de la herramienta.

  • $node_name:

2. Registro de la herramienta en FEM-orchestrator

Una vez que la imagen del contenedor se haya construido y subido al registro de contenedores del proyecto (si se requiere), debe registrarse en la base de datos de FEM-Orchestrator.

Modelo de datos de la herramienta

Recurso

Descripción

FEM-tool-schema.json

JSON schema defining tool registration requirements

Una muestra del documento se incluye a continuación:

{
  "_id": "tool_unique_identifier",
  "name": "tool_name",
  "author": "Your Name",
  "version": "1.0",
  "visibility": "public",
  "image": {
    "label": "registry.gitlab.bsc.es/namespace/tool_image_name:v2.0",
    "hash": "image_hash_value",
    "name": "tool_image_name",
    "repository": "registry.gitlab.bsc.es/fl/",
    "tag": "v2.0"
  },
  "port_mappings": [
    {
      "host_port": 4433,
      "container_port": 4433
    }
  ],
  "var_envs": {
    "FLOWER_CENTRAL_SERVER_IP": "flower.fl.bsc.es"
  },
  "volumes": [
    {
      "host_path": "$HOST_FEMC_PATH/config/rabbitmq-certificates",
      "container_path": "/app/config/rabbitmq-certificates"
    }
  ],
  "cpus": 4.0,
  "memory": "6gb",
  "gpus": "device=0",
  "persistent": false,
  "pre_checks": true,
  "source_code": {
    "url": "https://gitlab.bsc.es/project/repository.git --branch master"
  },
  "command": {
    "base": "python3 /app/myTool.py",
    "args": [
      {
        "id": "input",
        "type": "str",
        "default_value": "/data/input-file.csv",
        "position": 1,
        "prefix": "--",
        "separate": false,
        "required": true
      },
      {
        "id": "output",
        "type": "str",
        "default_value": "/sandbox/results.json",
        "position": 2,
        "prefix": "",
        "separate": false,
        "required": true
      },
      {
        "id": "my_threshold",
        "type": "int",
        "default_value": "33",
        "position": 3,
        "prefix": "--",
        "separate": false,
        "required": false
      }
    ]
  }
}