Validation-Environment

Validation-Environment es un framework para crear entornos reproducibles de validación de espacios de datos PIONERA. Se utiliza para desplegar dataspaces, validar conectores, ejecutar pruebas funcionales, recoger métricas y generar evidencias experimentales de forma trazable.

Estado de la versión 1.0

El desarrollo objetivo comprometido para el Validation Environment en el proyecto PIONERA queda cerrado en esta versión. El repositorio se conserva como línea base reproducible para despliegue, validación y auditoría de los componentes evaluados. Futuras adaptaciones, extensiones o generalizaciones deben tratarse como evolución posterior al cierre PIONERA.

Referencia inicial de la topología local del framework.

El punto de entrada principal es main.py. El framework está organizado para trabajar con distintos adapters y topologías sin duplicar la lógica común de validación.

Entorno recomendado de operación

La vía recomendada para usar el framework desde una estación de trabajo es Windows con WSL. En ese modo, WSL ejecuta el CLI, Docker Desktop aporta el motor de contenedores para la topología local, y el framework gestiona los accesos SSH, kubeconfigs y túneles necesarios para operar topologías VM desde la misma terminal.

El framework también soporta ejecución directa dentro de una VM cuando el operador decide instalarlo allí, pero la ruta principal de operación y depuración documentada para estaciones de trabajo es WSL sobre Windows.

Estado consolidado del proyecto

El repositorio consolida el framework como herramienta de despliegue, validación y generación de evidencias. Incluye:

• ejecución por niveles 1-6;
• adapters inesdata y edc;
• topologías local, vm-single y vm-distributed;
• validación con Newman, Playwright, Kafka opcional y componentes;
• generación de evidencias bajo experiments/;
• documentación pública en docs/.

El estado detallado se mantiene en docs/30_framework_current_state.md.

Alcance de cierre

El framework conserva soporte de código para los adapters y topologías documentados, pero la evidencia de cierre distingue entre capacidad implementada y validación oficial reproducida:

Adapter	local	vm-single	vm-distributed
inesdata	Evidencia obtenida en refactoring-local-vm-single	Evidencia obtenida en refactoring-local-vm-single	Evidencia obtenida en refactoring-vm-distributed-inesdata-ai
edc	Evidencia obtenida en refactoring-local-vm-single	Evidencia obtenida en refactoring-local-vm-single	Evidencia obtenida en refactoring-vm-distributed-edc-ai

La línea funcional de main toma como referencia refactoring-local-vm-single, que consolida evidencias para los adapters INESData y EDC en las topologías local y vm-single. Las validaciones vm-distributed se mantienen en ramas especializadas por adapter: refactoring-vm-distributed-inesdata-ai para INESData y refactoring-vm-distributed-edc-ai para EDC.

Por tanto, las evidencias local y vm-single deben tomarse desde la línea estable refactoring-local-vm-single; la evidencia INESData vm-distributed desde refactoring-vm-distributed-inesdata-ai; y la evidencia EDC vm-distributed desde refactoring-vm-distributed-edc-ai.

Referencias de reproducibilidad

Las siguientes referencias pueden usarse como punto de restauración de cierre v1.0 si las ramas o repositorios externos cambian después de esta entrega. La rama main incluye esta nota documental; la línea funcional estable que consolida local y vm-single para INESData y EDC corresponde a refactoring-local-vm-single.

Alcance	Referencia	Commit
Línea estable local y vm-single para INESData y EDC	refactoring-local-vm-single	532926e16a9f8845f65d328a8c6107d86f576c7d
INESData vm-distributed	refactoring-vm-distributed-inesdata-ai	a178910806ff8aaa5d0042d915ec24c48d7052fe
EDC vm-distributed	refactoring-vm-distributed-edc-ai	a8c7e3e580cd2f62650e4466cdab99d0ac43f95b

Cuando sea necesario reconstruir el entorno frente a cambios posteriores en los repositorios fuente, estos commits locales sirvieron como referencia durante la validación de la línea estable:

Repositorio fuente	Commit de referencia
ProyectoPIONERA/AIModelHub	91ef338c4203
ProyectoPIONERA/AIModelHub-Use-Cases	371d349c924c
ProyectoPIONERA/Ontology-Hub	23455014e676
ProyectoPIONERA/mapping-editor	eba85129e05c
ProyectoPIONERA/morph-kgv	19c9bcbd791e
ProyectoPIONERA/automap	f6debd99f104
ProyectoPIONERA/EDC-asset-filter-dashboard - dashboard EDC	3a36d8d3282e
ProyectoPIONERA/EDC-asset-filter-dashboard/asset-filter-template - runtime del conector EDC importado en el framework	9175ce552d93

Índice

Sección	Qué contiene
Entorno recomendado de operación	Uso recomendado desde Windows con WSL
Funcionalidades principales	Capacidades del framework
Adapters	Implementaciones soportadas
Topologías	local, vm-single y vm-distributed
Instalación y compilación	Clonado, bootstrap y entorno Python
Configuración	Ficheros .config, overlays y variables PIONERA_*
Guía de uso con ejemplos	Menú, CLI, niveles y ejemplos de comandos
Requisitos técnicos y dependencias	Herramientas necesarias
Validación	Level 6, Newman, Playwright, Kafka y componentes
Pruebas y cómo ejecutarlas	Tests unitarios del framework
Estructura del repositorio	Carpetas principales
Documentación	Rutas de lectura en docs/
Cómo contribuir	Issues, forks y pull requests
Agradecimientos y financiación	Financiación del proyecto
Autores y contacto	Contacto público del proyecto
Licencia	Licencia Apache 2.0

Funcionalidades principales

• desplegar un dataspace por niveles;
• seleccionar el adapter de conectores: inesdata o edc;
• preparar servicios comunes como Keycloak, MinIO, PostgreSQL y Vault;
• desplegar conectores provider/consumer;
• desplegar componentes opcionales como ontology-hub y ai-model-hub cuando el adapter lo soporte;
• sincronizar entradas de hosts de forma planificada e idempotente;
• ejecutar validaciones API con Newman;
• ejecutar validaciones UI con Playwright;
• comprobar transferencias y almacenamiento en MinIO;
• recoger métricas de control plane y benchmarks Kafka opcionales;
• persistir resultados en experiments/;
• producir reportes y artefactos de validación.

Adapters

Adapter	Uso
inesdata	Despliegue y validación con conectores INESData y su portal.
edc	Despliegue y validación con conectores EDC genéricos; la evidencia de cierre está disponible en local, vm-single y vm-distributed.

Cada adapter tiene su propio deployer:

deployers/inesdata/
deployers/edc/

Los artefactos compartidos viven en:

deployers/shared/
deployers/infrastructure/

Topologías

El framework reconoce tres topologías canónicas:

local
vm-single
vm-distributed

local es la ruta de desarrollo y validación en la máquina operadora. vm-single despliega el entorno en una VM con Kubernetes gestionado por el framework. vm-distributed separa servicios comunes, conectores y componentes por roles de infraestructura y se configura mediante perfiles locales, preflight SSH/HTTP/Kubernetes y URLs públicas parametrizables.

Las tres topologías comparten el mismo modelo de niveles, adapters y namespaces funcionales. Los valores reales de dominio, IP, SSH, kubeconfig y credenciales permanecen en ficheros locales ignorados por Git o en variables de entorno, no en la documentación versionada.

El hecho de que una topología esté implementada no implica que todos los adapters tengan evidencia oficial de cierre en esa topología. Consulta la matriz de alcance antes de preparar una ejecución para auditoría.

Instalación y compilación

1. Clona el repositorio:

git clone https://github.com/ProyectoPIONERA/Validation-Environment.git
cd Validation-Environment
git submodule update --init --recursive

También puedes clonar todo en un solo paso con git clone --recurse-submodules. El submódulo del dashboard EDC apunta al repositorio oficial ProyectoPIONERA/EDC-asset-filter-dashboard para conservar su autoría y fijar una versión reproducible. El runtime del conector EDC no es un submódulo aparte: está importado y versionado dentro de este repositorio en adapters/edc/sources/connector; su origen upstream queda descrito en adapters/edc/sources/connector/UPSTREAM.md.

2. Prepara dependencias del framework:

node --version
npm --version
java -version
bash scripts/bootstrap_framework.sh

En Linux/WSL, este comando instala también las dependencias del sistema que Playwright necesita para arrancar los navegadores. Si el entorno no permite instalar paquetes del sistema, usa --without-system-deps.

npm es obligatorio porque las validaciones usan Newman y Playwright, también en topología vm-single. Java 17+ es obligatorio para construir las imágenes locales de conectores EDC/INESData que después se cargan en Minikube. En una VM Ubuntu nueva, el bootstrap instala Node.js con npm y OpenJDK 17 automáticamente mediante apt-get cuando faltan. Si usas --without-system-deps o tu entorno no permite instalar paquetes del sistema, instálalos antes del bootstrap:

sudo apt-get update
sudo apt-get install -y nodejs npm openjdk-17-jdk

El bootstrap también crea automáticamente los ficheros locales deployer.config y los overlays deployers/infrastructure/topologies/*.config a partir de sus .example cuando aún no existen. No los sobrescribe si ya estaban creados.

3. Activa el entorno Python raíz:

source .venv/bin/activate

4. Para una ejecución local básica no tienes que crear configuración manualmente. Revisa los ficheros generados solo si necesitas ajustar credenciales, dominios, dataspaces o componentes:

deployers/infrastructure/deployer.config
deployers/infrastructure/topologies/local.config
deployers/infrastructure/topologies/vm-single.config
deployers/infrastructure/topologies/vm-distributed.config
deployers/inesdata/deployer.config
deployers/edc/deployer.config

5. Abre el menú guiado:

python3 main.py menu

También puedes ejecutar python3 main.py en una terminal interactiva; antes de mostrar el menú, el framework preguntará la topología activa. Si ya sabes la topología, pásala explícitamente con --topology para entrar directo.

El menú guiado es la entrada recomendada para usuarios que quieran ejecutar los niveles de despliegue sin memorizar comandos.

Configuración

La configuración común de infraestructura vive en:

deployers/infrastructure/deployer.config

La configuración específica de cada adapter vive en:

deployers/inesdata/deployer.config
deployers/edc/deployer.config

Usa los ficheros .example como plantilla cuando existan:

deployers/infrastructure/deployer.config.example
deployers/inesdata/deployer.config.example

Los .config locales son la configuración efectiva del despliegue. Los perfiles .profiles/*.env sirven como entrada local para rellenar esos .config desde el asistente o desde batch, pero no sustituyen a las capas efectivas hasta que se aplican. Para adaptar el framework a otro contexto, revisa Mapa de configuración y despliegue y Referencia de variables de configuración.

La variable PUBLIC_HOSTNAME en deployers/infrastructure/deployer.config controla el hostname público del entorno. Cuando está configurada, bootstrap.py la usa automáticamente para establecer el frontendUrl de Keycloak, lo que asegura que los tokens JWT contengan el issuer correcto para acceso externo vía HTTPS:

PUBLIC_HOSTNAME=<your-public-hostname>

También puedes sobreescribir valores con variables PIONERA_*, por ejemplo:

PIONERA_DS_1_NAME=demo \
PIONERA_DS_1_NAMESPACE=demo \
PIONERA_DS_1_CONNECTORS=citycouncil,company \
python3 main.py inesdata hosts --topology local --dry-run

Inicio rápido para vm-single en una VM

Si vas a ejecutar el framework dentro de una VM Ubuntu y tu objetivo es vm-single, empieza ajustando la base común y el overlay de topología con una separación explícita:

cd ~/Validation-Environment
bash scripts/bootstrap_framework.sh --skip-root-node --skip-ui-node --skip-playwright
nano deployers/infrastructure/deployer.config
nano deployers/infrastructure/topologies/vm-single.config

Si el fichero local ya existe, el bootstrap lo reutiliza y no lo sobrescribe. Para el overlay vm-single, el bloque mínimo esperado es:

VM_EXTERNAL_IP=192.0.2.10
INGRESS_EXTERNAL_IP=192.0.2.10

Notas prácticas:

• usa una IP real de tu VM o del ingress publicado por tu cluster; aquí se usa 192.0.2.10 solo como ejemplo documental;
• si entras por el menú con --topology vm-single y faltan las claves VM_EXTERNAL_IP/INGRESS_EXTERNAL_IP en deployers/infrastructure/topologies/vm-single.config, el framework detecta una dirección candidata de la VM y ofrece escribirla automáticamente;
• si mantienes claves de topología dentro de deployers/infrastructure/deployer.config, el CLI ya avisa con un warning de migración y te indica el overlay correcto;
• después de guardar el fichero, puedes comprobar los valores activos con:

grep -E '^(VM_EXTERNAL_IP|INGRESS_EXTERNAL_IP)=' \
  deployers/infrastructure/topologies/vm-single.config

• antes de arrancar Level 1, obtén la IP principal de la VM con:

hostname -I

• usa esa IP de la VM solo como valor provisional inicial en VM_EXTERNAL_IP e INGRESS_EXTERNAL_IP;
• en vm-single, Level 1 prepara el clúster k3s gestionado en la VM para asegurar una configuración reproducible;
• después de Level 1, comprueba que el clúster k3s y el Ingress están disponibles con:

kubectl get nodes
kubectl get ingress -A

• regla práctica: usa como valor final la IP/DNS público que termina en la VM o en el proxy externo que publica el Ingress;
• si la IP/DNS publicada cambia, actualiza esas claves en deployers/infrastructure/topologies/vm-single.config o exporta los overrides PIONERA_VM_EXTERNAL_IP y PIONERA_INGRESS_EXTERNAL_IP antes de Levels 3-6;
• para vm-single, entra directamente por:

python3 main.py menu --topology vm-single

Hosts locales

El framework planifica o aplica entradas en el fichero hosts del sistema. Por defecto, la operación solo planifica.

En topología local, el camino canónico sigue siendo resolver los hostnames públicos hacia 127.0.0.1 y mantener minikube tunnel activo. Si un entorno necesita una dirección distinta de loopback, declárala explícitamente en LOCAL_HOSTS_ADDRESS y LOCAL_INGRESS_EXTERNAL_IP dentro de deployers/infrastructure/topologies/local.config.

Para despliegues locales completos con WSL + Docker, una configuración prudente de Minikube en ese mismo overlay es:

PG_HOST=localhost
VT_URL=http://localhost:8200
LOCAL_HOSTS_ADDRESS=
LOCAL_INGRESS_EXTERNAL_IP=
LOCAL_RESOURCE_PROFILE=single-adapter
MINIKUBE_DRIVER=docker
MINIKUBE_CPUS=10
MINIKUBE_MEMORY=14336
MINIKUBE_PROFILE=minikube

Regla práctica:

• 10 CPU / 14336 MB es el punto de partida recomendado para validar un adapter local cada vez;
• no configures MINIKUBE_MEMORY por encima de la memoria disponible en Docker Desktop;
• para mantener inesdata y edc coexistiendo en local, usa el baseline documentado de 10 CPU / 18432 MB y LOCAL_RESOURCE_PROFILE=coexistence si Docker Desktop tiene margen suficiente;
• si Docker Desktop no alcanza ese baseline, Level 1 avisa que el entorno queda en modo de un adapter local y Level 3/4/5 bloquean la instalación del segundo adapter mientras el primero siga activo; si la ejecución es interactiva, el framework muestra un plan de cambio y elimina, tras confirmación exacta, solo los recursos locales del adapter anterior;
• en ejecución no interactiva, el cambio de adapter debe autorizarse de forma explícita con PIONERA_LOCAL_ADAPTER_SWITCH_CONFIRM="SWITCH TO EDC" o PIONERA_LOCAL_ADAPTER_SWITCH_CONFIRM="SWITCH TO INESDATA", según el adapter destino;
• si Level 6 detecta ambos adapters en local con memoria efectiva inferior a ese baseline, bloquea la validación antes de contaminar resultados con NodeNotReady;
• errores como 401, 500 o crashes internos de una aplicación siguen apuntando primero a bugs funcionales o de integración, no a falta de CPU.

Planificación:

python3 main.py inesdata hosts --topology local --dry-run
python3 main.py edc hosts --topology local --dry-run
python3 main.py inesdata local-repair --topology local
python3 main.py inesdata local-repair --topology local --recover-connectors

Aplicación explícita:

PIONERA_SYNC_HOSTS=true \
PIONERA_HOSTS_FILE=/etc/hosts \
python3 main.py edc hosts --topology local

En WSL, el fichero hosts de Windows suele estar en:

/mnt/c/Windows/System32/drivers/etc/hosts

La sincronización es idempotente: si una entrada ya existe, el framework la omite en lugar de duplicarla.

En el menú interactivo, cuando el adapter activo expone hostnames públicos, los niveles 3-6 hacen una comprobación previa en topología local. Si faltan entradas, el framework muestra cuáles son y pregunta si quieres aplicar solo las entradas ausentes antes de continuar.

Para Level 6 en topología local, la validación completa sigue dependiendo de hostnames públicos accesibles por Ingress. Mantén minikube tunnel activo y asegúrate de que hosts resuelve correctamente Keycloak, MinIO, registration-service y los conectores. Los mecanismos internos de port-forward que el framework reserva para validaciones Kafka concretas no sustituyen ese requisito del flujo completo.

Coexistencia de adapters

Los adapters comparten los servicios comunes desplegados en common-srvs (Keycloak, MinIO, PostgreSQL, Vault) cuando se ejecutan sobre el mismo cluster, pero cada dataspace debe tener un nombre y namespace propios.

Por ejemplo, es válido desplegar:

inesdata -> DS_1_NAME=demo, DS_1_NAMESPACE=demo
edc      -> DS_1_NAME=demoedc, DS_1_NAMESPACE=demoedc

No se debe reutilizar el mismo DS_1_NAME o DS_1_NAMESPACE para dos adapters distintos en el mismo cluster local, porque eso provoca colisiones de namespace, registration-service, bases de datos, usuarios y artefactos generados. Usa nombres similares para conectores solo cuando el dataspace resultante produce hostnames distintos.

Guía de uso con ejemplos

Menú y niveles

El menú se abre con:

python3 main.py menu

Niveles disponibles:

Nivel	Acción
1	Setup Cluster
2	Deploy Common Services
3	Deploy Dataspace
4	Deploy Connectors
5	Deploy Components
6	Run Validation Tests

La opción 0 ejecuta los niveles 1 a 6 de forma secuencial.

Opciones operativas del menú:

Opción	Uso
S	Preseleccionar adapter para la sesión actual del menú.
P	Previsualizar el plan de despliegue.
H	Planificar o aplicar entradas de hosts, mostrando hostnames concretos y el motivo si el sync queda omitido.
U	Mostrar URLs de acceso derivadas de la configuración activa.
M	Ejecutar métricas o benchmarks independientes.
X	Recrear el dataspace seleccionado.
B/D/R/C/L	Accesos de desarrollo: bootstrap, doctor, recovery, cleanup e imágenes locales.
I/O/A	Validaciones UI de INESData, Ontology Hub y AI Model Hub.
?	Mostrar ayuda.
Q	Salir.

Al seleccionar edc, el menú recuerda revisar H antes de ejecutar niveles que dependen de hostnames públicos.

La opción U muestra las URLs de acceso en formato legible e incluye endpoints compartidos como Keycloak, MinIO API, MinIO Console, registration-service, URLs de conectores/componentes y el bucket MinIO de cada conector cuando aplican en la configuración activa.

Si no preseleccionas adapter con S, el menú lo pedirá automáticamente cuando una operación de Level 3 a Level 6 lo necesite.

La referencia completa está en docs/33_menu_reference.md.

Validación local y acceso público

En topología local, el framework sigue un comportamiento coherente con un entorno más parecido a producción:

• navegador, Playwright y validación completa de Level 6 usan hostnames públicos vía Ingress;
• la comunicación interna entre conectores usa nombres internos de Kubernetes;
• port-forward queda reservado como mecanismo local de soporte o diagnóstico.

Esto significa que Level 6 completo no debe considerarse correcto si solo funciona mediante port-forward. Primero deben estar operativos hosts, Ingress y minikube tunnel.

Requisitos técnicos y dependencias

Para ejecución local, el framework espera:

Bloque	Herramientas principales
Base local	Python 3.10+, Git, Docker
Kubernetes local	Minikube, Helm, kubectl
Validación	Node.js, npm, Newman, Playwright
Builds de conectores	Java 17+ / OpenJDK 17
Operación	cliente PostgreSQL psql, permisos para hosts cuando aplique

Verificación rápida:

python3 --version
git --version
docker --version
minikube version
helm version
kubectl version --client=true
psql --version
node --version
npm --version
npx newman -v

El bootstrap del framework prepara .venv, dependencias Python, dependencias Node.js, navegadores Playwright y, en Linux/WSL, las dependencias del sistema necesarias para ejecutar esos navegadores:

bash scripts/bootstrap_framework.sh

El bootstrap requiere Python 3.10+. Si python3 apunta a una versión más antigua pero la máquina ya tiene otra versión compatible instalada, el script usa automáticamente la primera opción disponible entre python3.10, python3.11, python3.12 y python3.13. También se fuerza explícitamente con:

PIONERA_PYTHON_BIN=python3.11 bash scripts/bootstrap_framework.sh

Si un entorno no permite instalar paquetes del sistema desde el bootstrap, usa bash scripts/bootstrap_framework.sh --without-system-deps.

Minikube tunnel

En despliegues locales completos, mantén minikube tunnel abierto en otra terminal mientras ejecutas los niveles y la validación:

minikube tunnel

Cuando minikube tunnel solicite contraseña, la consola no siempre muestra un indicador visible. Introduce la contraseña y pulsa Enter.

Los accesos funcionales locales deben ejercitar los hostnames publicados por Ingress. El framework reserva port-forward para apoyo interno, diagnósticos o clientes host-side, pero no lo usa como sustituto de los endpoints de navegador o API. El fallback de port-forward para conectores está desactivado por defecto y solo debe habilitarse temporalmente con PIONERA_ALLOW_CONNECTOR_PORT_FORWARD_FALLBACK=true.

PostgreSQL es una excepción operativa interna: el servicio PostgreSQL del cluster sigue usando el puerto 5432. En topología local, el framework usa PG_PORT=5432 como puerto local preferente para psql y Python. Si ese puerto local está ocupado por un kubectl port-forward antiguo del framework, lo libera y lo recrea como 127.0.0.1:5432 -> common-srvs-postgresql:5432. Si el puerto pertenece a Windows, WSL u otro proyecto, el framework no mata ese proceso: falla con un diagnóstico para que el usuario libere el puerto manualmente.

Level 6 comprueba esos hostnames antes de ejecutar la limpieza y las suites de validación. Si vas a validar conectores ya desplegados, ejecuta Level 6 desde el mismo checkout que ejecutó Level 4, porque las credenciales locales generadas para Keycloak, MinIO y conectores viven bajo deployers/<adapter>/deployments/.

Acceso externo (entorno VM/PIONERA)

En entornos desplegados en VM, el acceso desde navegador se publica mediante el dominio o proxy externo configurado para la VM. El framework soporta PUBLIC_HOSTNAME para ajustar el frontendUrl de Keycloak y mantiene scripts operativos para preparar el acceso público vía nginx en la VM:

cd deployers/inesdata/scripts
bash setup-nginx-proxy.sh [cluster_ip] [vm_ip] [public_hostname] [internal_domain]

Ejemplo:

bash setup-nginx-proxy.sh 192.168.49.2 <vm_ip> <public_hostname> <internal_domain>

El script:

1. instala nginx e iptables persistentes en la VM;
2. configura reglas de redirección hacia el clúster;
3. ajusta el acceso a UIs de conectores, /auth/ y /s3-console/;
4. ayuda a publicar un hostname externo coherente para browser, Keycloak y MinIO.

La arquitectura y las URLs de referencia están documentadas en docs/41_pionera_connector_external_access.md.

CLI principal

Listar adapters:

python3 main.py list

Desplegar:

python3 main.py inesdata deploy --topology local
python3 main.py edc deploy --topology vm-distributed

Validar:

python3 main.py inesdata validate --topology local
python3 main.py edc validate --topology vm-distributed

Ejecutar despliegue y validación:

python3 main.py inesdata run --topology local
python3 main.py edc run --topology vm-distributed

Previsualizar sin modificar el entorno:

python3 main.py inesdata deploy --topology local --dry-run
python3 main.py edc run --topology vm-distributed --dry-run

Recrear un dataspace de forma controlada:

python3 main.py edc recreate-dataspace --topology local --confirm-dataspace demoedc
python3 main.py edc recreate-dataspace --topology local --confirm-dataspace demoedc --with-connectors

Validación

Level 6 ejecuta la validación integral del adapter activo. Según el adapter y el perfil activo, incluye:

• Newman;
• validación funcional EDC+Kafka después de Newman cuando el adapter la soporta;
• Playwright;
• comprobaciones de storage/MinIO;
• validaciones de componentes;
• métricas;
• reportes en experiments/.

En esta versión de cierre, la evidencia actualizada de edc está disponible en local, vm-single y vm-distributed. La ruta vm-distributed se mantiene en la rama especializada refactoring-vm-distributed-edc-ai.

En topología local, Level 6 usa por defecto el modo de orquestación stable: Newman, Kafka, Playwright y componentes se coordinan con menos solapamiento para reducir ruido de Minikube local. En vm-single y vm-distributed el modo efectivo por defecto sigue siendo fast.

En ese modo estable local, el framework también comprueba la salud de Kubernetes antes y después de la validación. Si el nodo o los pods relevantes no están listos, espera una ventana corta y falla temprano si el entorno sigue bloqueado. Si durante la ejecución aparecen reinicios o eventos NodeNotReady, quedan registrados en local_stability_preflight.json y local_stability_postflight.json dentro del experimento.

Para forzar el modo rápido en local:

python3 main.py inesdata validate --topology local --validation-mode fast

También se declara con PIONERA_VALIDATION_MODE=fast.

En el layout role-aligned, Level 5 publica componentes configurados en components_namespace. Level 6 valida esos componentes después de las suites del dataspace y ejecuta por defecto las suites automatizadas A5.2 registradas para ontology-hub, ai-model-hub y semantic-virtualization. La única suite de validación A5.2 desactivada por defecto es Kafka/streaming transfer, por su coste temporal.

Colecciones Newman principales:

Colección	Uso
01_environment_health.json	Salud básica, reachability y autenticación.
02_connector_management_api.json	CRUD aislado del Management API.
03_provider_setup.json	Preparación del escenario E2E del provider.
04_consumer_catalog.json	Descubrimiento de catálogo.
05_consumer_negotiation.json	Negociación contractual.
06_consumer_transfer.json	Transferencia y recuperación de datos.

Playwright se resuelve por adapter:

validation/ui/playwright.inesdata.config.ts
validation/ui/playwright.edc.config.ts

La documentación de validación está en docs/37_validation.md.

Métricas y Kafka

Ejecutar métricas:

python3 main.py inesdata metrics --topology local
python3 main.py edc metrics --topology local

Ejecutar métricas con benchmark standalone de broker Kafka:

python3 main.py inesdata metrics --topology local --kafka

Helper reproducible de Kafka:

bash scripts/run_kafka_benchmark.sh --messages 10
bash scripts/run_kafka_benchmark.sh --messages 10 --max-retries 3 --retry-backoff 15
bash scripts/run_kafka_benchmark.sh --prepare-only
bash scripts/run_kafka_benchmark.sh --teardown-only

El benchmark standalone genera kafka_metrics.json cuando se ejecuta y mide el broker Kafka, no el flujo E2E del dataspace. Además, Level 6 ejecuta la validación funcional EDC+Kafka después de Newman para adapters compatibles y genera kafka_transfer_results.json. Esa suite está desactivada por defecto para ahorrar tiempo. En ejecuciones interactivas, Level 6 pregunta Run Kafka validation suites too?; en ejecuciones no interactivas, usa PIONERA_LEVEL6_RUN_KAFKA=true.

En local, esa validación usa por defecto un broker Kafka temporal dentro de Kubernetes. Los conectores acceden al broker por DNS de cluster y el proceso Python del framework usa un port-forward temporal solo para crear topics y verificar mensajes desde el host.

En vm-distributed, los conectores viven en VMs o clusters distintos. Por eso KAFKA_CLUSTER_BOOTSTRAP_SERVERS debe apuntar a un endpoint Kafka alcanzable desde todas las VMs de conectores, normalmente un NodePort o una ruta equivalente expuesta por la VM de servicios comunes. No debe usarse localhost, host.minikube.internal ni nombres *.svc de Kubernetes como endpoint del conector. Para INESData, usa una imagen de conector que incluya soporte data-plane-kafka, o activa de forma explícita el flujo de build e importación remota de imágenes cuando el despliegue sea de desarrollo.

Imágenes locales

Durante desarrollo, usa la opción L - Build and Deploy Local Images del menú para construir, cargar y redesplegar imágenes locales del adapter activo.

En topología local, Level 4 de INESData prepara automáticamente inesdata-connector e inesdata-connector-interface desde las fuentes locales antes de crear los conectores. Esto evita validar con imágenes remotas antiguas cuando Level 6 ejecuta flujos como Kafka o Playwright.

La opción L está pensada para iteración de desarrollo y preserva datos en redeploys INESData: reutiliza los valores existentes de Helm y no recrea credenciales, dataspace ni servicios comunes. Si un release todavía no existe, ejecuta primero el nivel correspondiente.

Cuando el adapter activo es edc, las acciones rápidas de L construyen y cargan imágenes locales del conector EDC, del dashboard EDC o de ambos. Si ya hay deployments EDC en ejecución, el framework los reinicia para que tomen la imagen nueva sin recrear datos.

Además, Level 4 de EDC prepara automáticamente esas imágenes locales en modo auto cuando se despliega en topología local y no hay una imagen explícita publicada que usar. En vm-single y vm-distributed, el framework usa por defecto imágenes de registry o las imágenes declaradas en los ficheros de configuración; para compilar e importar desde fuentes en VM hay que activar explícitamente el modo local de imágenes.

Si la receta corresponde a un componente de Level 5 ya desplegado, como Ontology Hub o AI Model Hub, el framework reinicia su deployment para que Kubernetes use la imagen recién cargada. Si el componente aún no existe, carga la imagen y deja el despliegue para Level 5.

Scripts relevantes:

adapters/inesdata/scripts/sync_sources.sh
adapters/inesdata/scripts/build_images.sh
adapters/inesdata/scripts/local_build_load_deploy.sh
adapters/edc/scripts/sync_sources.sh
adapters/edc/scripts/build_image.sh
adapters/edc/scripts/sync_dashboard_sources.sh
adapters/edc/scripts/build_dashboard_image.sh
adapters/edc/scripts/build_dashboard_proxy_image.sh

Para EDC, las fuentes locales se gestionan bajo:

adapters/edc/sources/

El runtime del conector EDC se mantiene dentro del framework en:

adapters/edc/sources/connector

Esa copia procede del subdirectorio asset-filter-template del repositorio ProyectoPIONERA/EDC-asset-filter-dashboard; la referencia upstream concreta se documenta en adapters/edc/sources/connector/UPSTREAM.md. No hay un repositorio externo separado llamado "adapter EDC".

El dashboard EDC se sincroniza desde:

https://github.com/ProyectoPIONERA/EDC-asset-filter-dashboard

Ese dashboard está versionado como submódulo en:

adapters/edc/sources/dashboard

El framework fija por defecto el commit declarado en EDC_DASHBOARD_REPO_REF. Los overlays propios del framework se mantienen separados bajo adapters/edc/overlays/dashboard.

Limpieza y doctor

El menú incluye accesos directos de desarrollo:

Herramienta	Uso
Bootstrap Framework Dependencies	Prepara o repara dependencias.
Run Framework Doctor	Ejecuta checks del entorno local.
Repair Local Access / Connectors	Reconcila hosts y, si hace falta, reinicia conectores tras un reinicio local o de WSL.
Cleanup Workspace	Limpia caches y artefactos temporales.
Build and Deploy Local Images	Construye imágenes locales y reinicia componentes desplegados cuando aplica; recomendado para desarrollo en topología local.

El script de limpieza también se ejecuta manualmente con:

bash scripts/clean_workspace.sh
bash scripts/clean_workspace.sh --apply
bash scripts/clean_workspace.sh --apply --include-results

Experimentos y reportes

Un experimento es una ejecución reproducible del flujo de validación y medición. Incluye despliegue, validación API, validación UI, métricas, Kafka y artefactos de componentes según el alcance ejecutado.

Estructura habitual:

experiments/
  experiment_<timestamp>/
    metadata.json
    experiment_results.json
    aggregated_metrics.json
    kafka_metrics.json
    kafka_transfer_results.json
    summary.json
    summary.md
    graphs/

Los reportes Playwright quedan dentro del experimento correspondiente cuando se ejecutan desde Level 6.

Estructura del repositorio

Ruta	Descripción
main.py	CLI principal y menú guiado.
framework/	Núcleo reutilizable de validación, métricas y reportes.
adapters/	Integraciones específicas por adapter.
deployers/	Deployers, configuración y artefactos de despliegue.
deployers/infrastructure/	Contratos, topologías, hosts y utilidades transversales.
deployers/shared/	Charts y artefactos reutilizables.
validation/	Suites Newman, Playwright y validaciones de componentes.
tests/	Pruebas unitarias del framework.
docs/	Documentación estable del framework.

Pruebas y cómo ejecutarlas

Pruebas focalizadas de topologías, contratos, hosts y CLI:

python3 -m unittest \
  tests.test_deployer_shared_contracts \
  tests.test_deployer_shared_topology \
  tests.test_deployer_shared_hosts_manager \
  tests.test_main_cli

Descubrimiento general:

python3 -m unittest discover tests

El descubrimiento general incluye las suites disponibles de Vault, Kafka, Ontology, métricas o componentes que dependan del entorno local disponible.

Documentación

La documentación está en docs/.

Orden recomendado:

• Inicio rápido
• Referencia del menú
• Arquitectura
• Deployers y topologías
• Adapters
• Validación
• Desarrollo y testing
• Troubleshooting
• Acceso externo a conectores
• Guía de navegación para auditoría
• Guía operativa de vm-distributed
• Manual de usuario
• Manual técnico
• Mapa de configuración y despliegue
• Estructura para vm-distributed
• Referencia de variables de configuración
• Resultados tabulares E5.2

Imágenes, diagramas y vídeos explicativos

Diagramas disponibles:

• Entorno local de validación
• Entorno distribuido de validación
• Arquitectura del entorno de pruebas
• Vista simplificada de estructura vm-distributed
• Estructura del framework para vm-distributed
• Resultados de validación de componentes

Los vídeos explicativos se enlazan desde docs/README.md cuando estén publicados. La estructura recomendada es:

1. resumen del framework y metodología de validación;
2. despliegue básico y topologías;
3. validación de componentes y evidencias.

Cómo contribuir

El flujo recomendado para contribuciones es:

1. abre un issue describiendo el cambio, bug o mejora;
2. crea un fork o una rama de trabajo;
3. ejecuta las pruebas relevantes antes de abrir el pull request;
4. abre un pull request explicando el objetivo, alcance, pruebas ejecutadas y riesgos conocidos.

No incluyas credenciales, tokens, claves privadas, kubeconfigs reales, logs con secretos ni datos personales en commits, issues o pull requests. Usa placeholders y ficheros locales ignorados por Git para configuración de entorno.

Referencias técnicas

• INESData local environment
• INESData connector management API collection
• Eclipse EDC Management API
• Eclipse EDC Kafka sample
• DataSpaceUnit local deployment

Agradecimientos y fuentes de financiación

Este trabajo ha recibido financiación del proyecto PIONERA (Enhancing interoperability in data spaces through artificial intelligence), financiado en el contexto de la convocatoria de Productos y Servicios Tecnológicos para Espacios de Datos del Ministerio para la Transformación Digital y de la Función Pública, dentro del marco del PRTR financiado por la Unión Europea (NextGenerationEU).

---

Autores y contacto

Este repositorio forma parte del trabajo software del proyecto PIONERA. Para consultas, incidencias o propuestas de cambio, usa los issues y pull requests del repositorio en GitHub.

• Mantenedores del framework:
  • Adrián Vargas (adrian.vargas@upm.es)
  • Raffaele Cuzzaniti (r.cuzzaniti@upm.es)

Licencia

Validation-Environment está disponible bajo la Apache License 2.0.