Ce guide détaille la mise en œuvre de tâches d'analyse fédérée à l'aide de SCQL (Secure Collaborative Query Language) au sein de l'écosystème Kuscia. Nous utiliserons KusciaAPI pour configurer des sources de données locales et orchestrer le calcul sécurisé entre deux entités, Alice et Bob.

Configuration des Certificats et Jetons d'Accès

Pour interagir avec KusciaAPI sous le protocole MTLS, il est impératif de récupérer les certificats et le jeton d'authentification. En mode de déploiement point à point (P2P), ces fichiers se trouvent généralement dans le répertoire /home/kuscia/var/certs/ de chaque nœud.

Les fichiers essentiels sont les suivants :

• kusciaapi-server.key : Clé privée du serveur.
• kusciaapi-server.crt : Certificat du serveur.
• ca.crt : Certificat de l'autorité de certification.
• token : Jeton à inclure dans les en-têtes HTTP (Token: <valeur>).

Initialisation des Données

Chaque participant doit enregistrer sa source de données et définir la structure des tables qu'il souhaite mettre à disposition pour l'analyse.

Préparation du Nœud Alice

Connectez-vous au contaneur du nœud Alice pour enregistrer la source de données locale :

docker exec -it ${USER}-kuscia-autonomy-alice bash

export CERTS_PATH=/home/kuscia/var/certs
curl -k -X POST 'https://localhost:8082/api/v1/domaindatasource/create' \
 --header "Token: $(cat ${CERTS_PATH}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CERTS_PATH}/kusciaapi-server.crt \
 --key ${CERTS_PATH}/kusciaapi-server.key \
 --cacert ${CERTS_PATH}/ca.crt \
 -d '{
  "domain_id": "alice",
  "datasource_id": "ds-local-alice",
  "type": "localfs",
  "name": "AliceLocalSource",
  "info": {
      "localfs": {
          "path": "/home/kuscia/var/storage/data"
      }
  },
  "access_directly": true
}'

Ensuite, créez la ressource de données (DomainData) pointant vers votre fichier CSV :

curl -k -X POST 'https://localhost:8082/api/v1/domaindata/create' \
 --header "Token: $(cat ${CERTS_PATH}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CERTS_PATH}/kusciaapi-server.crt \
 --key ${CERTS_PATH}/kusciaapi-server.key \
 --cacert ${CERTS_PATH}/ca.crt \
 -d '{
  "domain_id": "alice",
  "domaindata_id": "table-profil-alice",
  "datasource_id": "ds-local-alice",
  "name": "profil_utilisateurs",
  "type": "table",
  "relative_uri": "scql-alice.csv",
  "columns": [
    {"name": "id_client", "type": "str"},
    {"name": "score_credit", "type": "int"},
    {"name": "revenu_annuel", "type": "int"},
    {"name": "age", "type": "int"}
  ]
}'

Préparation du Nœud Bob

Répétez une procédure similaire pour Bob avec ses propres identifiants de table :

docker exec -it ${USER}-kuscia-autonomy-bob bash

# (Configuration du DataSource ds-local-bob omise pour la brièveté)

curl -k -X POST 'https://localhost:8082/api/v1/domaindata/create' \
 --header "Token: $(cat ${CERTS_PATH}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CERTS_PATH}/kusciaapi-server.crt \
 --key ${CERTS_PATH}/kusciaapi-server.key \
 --cacert ${CERTS_PATH}/ca.crt \
 -d '{
  "domain_id": "bob",
  "domaindata_id": "table-achats-bob",
  "datasource_id": "ds-local-bob",
  "name": "historique_achats",
  "type": "table",
  "relative_uri": "scql-bob.csv",
  "columns": [
    {"name": "id_client", "type": "str"},
    {"name": "montant_total", "type": "int"},
    {"name": "statut_actif", "type": "int"}
  ]
}'

Déploiement des composants SCQL

SCQL nécessite un composant "Broker" sur chaque nœud pour gérer les requêtes.

1. Définissez l'AppImage SCQL via un fichier YAML (ex: scql-image.yaml) en activant le routage kusciadatamesh.
2. Appliquez la configuration : kubectl apply -f scql-image.yaml.
3. Déployez le Broker spécifique à chaque domaine : ```

   Pour Alice

   kubectl apply -f /home/kuscia/scripts/templates/scql/broker_alice.yaml

   Pour Bob

   kubectl apply -f /home/kuscia/scripts/templates/scql/broker_bob.yaml

Exécution de l'Analyse Collaborative

1. Gestion du Projet

Alice initialise le projet et invite Bob :

curl -X POST http://127.0.0.1:80/intra/project/create \
--header "host: scql-broker-intra.alice.svc" \
--header "kuscia-source: alice" \
-d '{
    "project_id": "analyse_finance_2024",
    "name": "Analyse de Risque",
    "conf": { "spu_runtime_cfg": { "protocol": "SEMI2K", "field": "FM64" } }
}'

curl -X POST http://127.0.0.1:80/intra/member/invite \
--header "host: scql-broker-intra.alice.svc" \
--header "kuscia-source: alice" \
-d '{ "invitee": "bob", "project_id": "analyse_finance_2024" }'

Bob doit accepter l'invitation via l'endpoint /intra/invitation/process sur son propre Broker.

2. Enregistrement des Tables Logiques

Chaque partie lie ses données physiques (DomainData) à une table logique SCQL au sein du projet.

# Exemple pour Alice
curl -X POST http://127.0.0.1:80/intra/table/create \
--header "host: scql-broker-intra.alice.svc" \
-d '{
    "project_id": "analyse_finance_2024",
    "table_name": "vue_alice",
    "ref_table": "table-profil-alice",
    "db_type": "csvdb",
    "columns": [
        {"name":"id_client","dtype":"string"},
        {"name":"score_credit","dtype":"int"},
        {"name":"age","dtype":"int"}
    ]
}'

3. Configuration du Contrôle d'Accès (CCL)

Avant d'exécuter une requête, les participants doivent accorder des permissions sur les colonnes. Sans CCL explicite, aucune donnée ne peut être traitée.

curl -X POST http://127.0.0.1:80/intra/ccl/grant \
--header "host: scql-broker-intra.alice.svc" \
-H "Content-Type: application/json" \
-d '{
    "project_id": "analyse_finance_2024",
    "column_control_list":[
        {"col":{"column_name":"id_client","table_name":"vue_alice"},"party_code":"bob","constraint":1},
        {"col":{"column_name":"score_credit","table_name":"vue_alice"},"party_code":"bob","constraint":1}
    ]
}'

4. Lancement de la Requête Fédérée

Alice exécute une requête SQL pour obtenir des statistiques agrégées sans voir les données brutes de Bob :

curl -X POST http://127.0.0.1:80/intra/query \
--header "host: scql-broker-intra.alice.svc" \
--header "kuscia-source: alice" \
-H "Content-Type: application/json" \
-d '{
    "project_id": "analyse_finance_2024",
    "query": "SELECT a.score_credit, COUNT(*) as effectif, AVG(b.montant_total) as moyenne_achat FROM vue_alice a JOIN vue_bob b ON a.id_client = b.id_client WHERE a.age > 25 GROUP BY a.score_credit;"
}'

Maintenance et Diagnostic

Pour surveiller l'état des composants et diagnostiquer les erreurs, uitlisez les commandes Kubernetes à l'intérieur des conteneurs de nœuds :

• Statut des Pods : kubectl get po -A
• Configuraton du Broker : kubectl get cm scql-broker-configtemplate -oyaml
• Accès aux journaux : Les logs des moteurs SCQL se trouvent dans /home/kuscia/var/stdout/pods/.