Generar desplegables y escritores universales de destino

Generate deployables crea un runner portátil a partir del catálogo y/o de definiciones Output Target guardadas. El runner puede conservar salidas CSV/Excel y, opcionalmente, escribir varias definiciones lógicas en un único destino físico.

DSE usa ahora un Universal Destination Writer Framework. Todos los presets actuales de Output Target tienen una ruta de escritura ejecutable. La implementación se adapta a la tecnología: proveedor nativo, ODBC, REST/OData, SDK de almacenamiento de objetos, archivos o gateway.

“Runtime writer” significa que el runner generado conoce cómo ejecutar la ruta. Aun así puede necesitar requisitos externos: driver ODBC del proveedor, credenciales/token de API, permisos cloud o un gateway aprobado para VSAM/IMS/CICS.

Flujo recomendado

1. Descubra las fuentes y revise el catálogo.
2. Cree/revise mappings en Compose targets.
3. Abra Generate deployables y agregue uno o más targets guardados.
4. Configure el destino físico antes de activar la escritura.
5. Revise la tecnología del writer, nombres de objetos y modo de escritura.
6. Active Route selected targets to one destination solo cuando quiera que el runner escriba físicamente.
7. Pruebe la conexión, seleccione plataforma/RID y genere.
8. Ejecute, revise View results y reconcilie los conteos del destino.

Targets lógicos y destino físico

Un Output Target guardado es un contrato lógico de datos. No tiene que coincidir con la tecnología física elegida al ejecutar.

Ejemplos:

MongoDB + Couchbase + InfluxDB -> PostgreSQL

Oracle + MongoDB + DynamoDB -> Redis

Cada fila conserva su procedencia y mappings; DSE no mezcla indiscriminadamente registros de targets diferentes.

Configure primero, active después

El preset, modo, nombres de objetos y tipos permanecen editables aunque el checkbox de routing esté desmarcado. El checkbox controla la ejecución externa, no el editor.

Tecnologías de writer

Tabla Destination object routing

Destination object es editable. Mantenga cada nombre no vacío, único y válido. Object type se limita a los tipos que el writer puede ejecutar: Table, Collection, Hash, Index, Label, Measurement, Bucket, etc.

Append y Replace

• Append conserva datos existentes y agrega los nuevos registros.
• Replace limpia una vez el objeto/prefijo propiedad de la ruta y escribe el conjunto actual.

Por seguridad, Salesforce, Dynamics 365 CRM, SharePoint, ServiceNow, Workday y SAP OData exponen solo Append en el writer API directo. Un reemplazo destructivo completo debe implementarse mediante un gateway aprobado con reglas de negocio explícitas.

Conexión

Para producción, no incruste secretos cuando no sea necesario. Use:

DSX_DESTINATION_CONNECTION_STRING

ODBC requiere un string explícito con Driver= o DSN=. DSE no intenta adivinar el nombre del driver instalado.

REST/OData acepta normalmente Url=/Endpoint=, Token=/AccessToken=, Username=, Password=, ApiKey= y parámetros específicos del destino.

VSAM/IMS/CICS/Generic pueden usar Endpoint=https://... o una conexión ODBC autorizada.

Modelo canónico

El runner transforma primero los registros de origen en un sobre DSE neutral con id estable, procedencia y campos mapeados. Después el adapter físico traduce ese registro al formato del destino. Así se evita implementar una combinación distinta para cada par origen/destino.

AI Advisor

En Destinos, seleccione exactamente una recomendación de IA con el botón de opción. Usar destino seleccionado en Deployables prepara ese destino para la próxima sesión de Generate Deployables. Crear destinos borrador crea o actualiza solo el destino seleccionado, evitando borradores de IA duplicados.

AI Advisor puede recomendar el destino y enviar la propuesta a Generate Deployables. La IA no ejecuta escrituras ocultas. El usuario revisa tecnología, objetos, modo, conexión y paquete generado antes de ejecutar.

Como todos los presets actuales tienen una ruta de writer, la recomendación puede conservar su tecnología original, siempre que se satisfagan sus requisitos de runtime.

Solución de problemas

• No puedo cambiar el preset: use una compilación con el fix del dropdown; routing desactivado no debe bloquear el editor.
• ODBC pide Driver/DSN: instale el driver del proveedor en el host que ejecutará el deployable y configure el string.
• REST devuelve 401/403: revise endpoint, token, tenant/site y permisos de escritura.
• SaaS no ofrece Replace: es intencional por seguridad.
• VSAM/IMS/CICS pide gateway: configure el gateway de escritura del sitio o una superficie ODBC autorizada.
• Falta connection string: configure DSX_DESTINATION_CONNECTION_STRING.

Recomendaciones de producción

Empiece con pocos registros, use Append durante validación, mantenga secretos fuera del paquete, aplique mínimo privilegio, use prefijos/objetos dedicados, conserve CSV/Excel/run-summary y reconcilie conteos/claves antes del cutover.

Confiabilidad empresarial, linaje y seguridad de reinicio

Los deployables generados pueden incluir una capa de confiabilidad empresarial además de CSV/Excel y el routing físico.

Cada ejecución recibe un Run ID y, cuando está habilitado, genera en output/audit/<run-id>/:

• lineage.jsonl: eventos estructurados con origen, campos, ruta de destino, objetos mapeados, conteos, tecnología del writer, modo de escritura, estado y huella del mapeo;
• run-summary.json: copia estable por ejecución del resumen, guardada dentro del directorio de auditoría para que una ejecución posterior no sobrescriba el registro histórico;
• run-manifest.json: resumen de gobernanza con conteos, reintentos, información de reanudación y hashes SHA-256;
• integrity.sha256: hashes del resumen, lineage, manifest y archivos generados.

Los artefactos de linaje no incluyen cadenas de conexión ni credenciales.

Lease y heartbeat

Habilitar arrendamiento de ejecución y latido crea un lease por esquema y un heartbeat en el directorio de estado. Dos runners con el mismo esquema y DSX_STATE_DIR no pueden ejecutarse al mismo tiempo. Para un diseño activo/pasivo, use un directorio durable compartido.

Puede usar DSX_RUN_ID/--run-id, DSX_STATE_DIR/--state-dir, --lease-timeout-seconds y --heartbeat-seconds.

Reintentos y checkpoints

Las lecturas con fallos transitorios usan backoff exponencial limitado. Las escrituras solo se reintentan cuando el writer expone semántica transaccional o Upsert suficientemente segura.

La reanudación guarda checkpoints de escrituras de destino completadas. Después de un fallo, un nuevo proceso puede evitar repetir esas escrituras y aun reconstruir CSV/Excel. La reanudación se deshabilita para Replace.

Diferencia con CDC

Los checkpoints mejoran la recuperación, pero no son Change Data Capture (CDC) basado en logs. La lectura actual sigue siendo Snapshot. El CDC de producción necesita adaptadores por origen y cursores durables como LSN de SQL Server CDC, WAL de PostgreSQL, resume tokens de MongoDB, continuaciones de Cosmos Change Feed o posiciones de shards de DynamoDB Streams.

Consulte Docs/Enterprise-Reliability-CDC-Governance-HA-Plan.md.

<!-- DSE_DEPLOYABLE_CERTIFICATION_HELP_V1 -->

20. Ejecución certificada de los desplegables generados para Windows y Linux

Use esta sección después de completar Generate deployables. Documenta el flujo de certificación/ejecución de los paquetes generados win-x64 y linux-x64 nativos. Son runners de integración generados, no los SKU comerciales de instalación Windows/Container de DSE.

20.1 Desplegable de Windows (windows/win-x64)

Copie la carpeta de Windows generada a la máquina de certificación (o extraiga el archivo transferido) y trabaje desde el directorio windows\win-x64.

Verifique que estos archivos generados estén presentes antes de la primera ejecución:

• DataSourceExplorer.Runner.exe
• manager.cmd
• run.cmd
• schema-catalog.json
• source-connections.json
• destination-route.json — cuando el enrutamiento al destino está habilitado

Inicie el Runtime Manager local:

cd /d C:\Path\To\deployables\windows\win-x64
manager.cmd

manager.cmd inicia DataSourceExplorer.Runner.exe --manager. El administrador escucha en 127.0.0.1 y normalmente abre el navegador predeterminado automáticamente. Si no se abre, ejecute el archivo directamente y use la Local management URL mostrada en la consola.

DataSourceExplorer.Runner.exe --manager

1. Confirme que Runtime status sea READY y que no exista una ejecución activa.
2. En Connections, confirme que cada origen y destino requerido aparezca como Configured. Deje los campos protegidos en blanco para conservar el valor guardado/integrado.
3. Para la primera certificación, use Manual only y establezca el directorio de salida en output.
4. Seleccione Run now y espere a que el estado vuelva a READY.
5. Confirme que Last result y Run history indiquen Success y verifique de forma independiente los datos de salida/destino esperados.

Para una ejecución única sin interfaz:

run.cmd

El generador intenta primero una publicación autónoma. Si tuvo que usar una publicación dependiente del framework, instale los runtimes correspondientes de .NET 8 y ASP.NET Core 8 en la máquina de destino.

20.2 Desplegable Linux (linux/linux-x64) — flujo Ubuntu Hyper-V validado

El procedimiento siguiente sigue la guía validada de Ubuntu Server 26.04.1 LTS / Microsoft Hyper-V proporcionada para la certificación. Ejecuta el desplegable Linux nativo; Docker no es necesario.

Acceso seguro recomendado desde el navegador de Windows

En vez de exponer el administrador en la red de la VM, puede crear un túnel de puerto SSH local desde Windows PowerShell después de leer el puerto del administrador en el registro de Linux:

ssh -L 18093:127.0.0.1:<manager-port> <linux-user>@<VM-IP>

Después abra http://127.0.0.1:18093/ en Windows. Mantenga abierta la sesión SSH mientras usa el administrador. El relay socat descrito abajo sigue siendo útil en una red de certificación aislada/de confianza.

Objetivo

Este procedimiento crea una máquina virtual ligera de Ubuntu Server y ejecuta el desplegable nativo de Linux generado por DSE. Reproduce el flujo de Windows: copiar el paquete generado, iniciar DSE Deployable Runtime Manager, abrir el administrador desde el host Windows, ejecutar el desplegable y verificar el resultado.

El paquete descrito aquí es un desplegable nativo linux-x64. Docker no es necesario para este flujo.

Requisitos previos

• Host Windows con Hyper-V habilitado
• ISO de Ubuntu Server LTS
• Carpeta linux generada por DSE que contiene linux/linux-x64
• Al menos 4 vCPU, 4 GB de RAM y un disco virtual de 40 GB
• Acceso de red desde la VM a los sistemas de origen/destino de DSE

Windows → Hyper-V → Ubuntu → DSE Runtime Manager → Browser

1. Crear la máquina virtual Hyper-V

Cree una VM de generación 2 con esta configuración base:

Durante la instalación de Ubuntu, seleccione Install OpenSSH server. Al terminar, expulse la ISO y arranque desde el disco virtual.

2. Preparar Ubuntu

Inicie sesión en Ubuntu y actualice el sistema. Después verifique CPU, memoria, disco y dirección IP.

sudo apt update
sudo apt upgrade -y
hostname -I
nproc
free -h
df -h

Si el VHDX es de 40 GB pero el volumen raíz tiene solo unos 18-19 GB, amplíe el volumen lógico LVM para usar el espacio libre.

sudo vgs
sudo lvextend -l +100%FREE -r /dev/ubuntu-vg/ubuntu-lv
df -h

3. Conectarse desde Windows mediante SSH

Use la IP actual de la VM mostrada por hostname -I. La dirección del Default Switch de Hyper-V puede cambiar después de reiniciar.

ssh <linux-user>@<VM-IP>

4. Copiar la carpeta Linux generada

Ejecute ssh/scp desde Windows PowerShell, no desde el shell de Ubuntu. DSE genera una carpeta linux, no un archivo linux.zip. Sustituya la ruta, el usuario y la IP del ejemplo por los valores reales.

ssh <linux-user>@<VM-IP> "rm -rf /home/<linux-user>/dse-deploy/linux && mkdir -p /home/<linux-user>/dse-deploy"
scp -r "C:\Path\To\GeneratedDeployables\...\linux" <linux-user>@<VM-IP>:/home/<linux-user>/dse-deploy/

Si Linux muestra “Could not resolve hostname c:”, ejecutó scp desde Ubuntu. Salga a Windows PowerShell y ejecute el comando allí.

5. Preparar el desplegable

Instale socat si utilizará el relay, entre en la carpeta linux-x64 copiada y aplique permisos de ejecución de Linux. Los scripts generados por la versión actual de DSE usan UTF-8 sin BOM, por lo que no es necesario extraer ni quitar BOM.

sudo apt update && sudo apt install -y socat
cd ~/dse-deploy/linux/linux-x64
chmod +x DataSourceExplorer.Runner manager.sh run.sh
ls -l DataSourceExplorer.Runner manager.sh run.sh

6. Verificar la conectividad de origen/destino

Antes de iniciar DSE, compruebe que la VM Ubuntu puede alcanzar el puerto requerido. El ejemplo usa MongoDB en el puerto 27017.

timeout 5 bash -c '</dev/tcp/<source-host>/<source-port>' \
  && echo 'Port reachable' \
  || echo 'Port NOT reachable'

# MongoDB example
timeout 5 bash -c '</dev/tcp/192.168.50.124/27017' \
  && echo 'MongoDB port reachable' \
  || echo 'MongoDB port NOT reachable'

7. Iniciar DSE Deployable Runtime Manager

Inicie el administrador y revise su registro. El administrador se enlaza a 127.0.0.1 y selecciona un puerto local.

cd ~/dse-deploy/linux/linux-x64
./manager.sh
sleep 2
cat .dse-manager/manager-console.log
curl http://127.0.0.1:<manager-port>/ | head

Un registro correcto contiene una línea como: Local management URL: http://127.0.0.1:51827. El puerto puede cambiar después de reiniciar.

8. Hacer accesible el administrador desde el navegador de Windows

Use socat en Ubuntu para redirigir un puerto estable de la VM (18093) al puerto loopback actual del administrador. Los comandos detectan automáticamente la IP y el puerto.

cd ~/dse-deploy/linux/linux-x64
VM_IP=$(hostname -I | awk '{print $1}')
MANAGER_PORT=$(grep -oE '127\.0\.0\.1:[0-9]+' .dse-manager/manager-console.log | tail -1 | cut -d: -f2)
nohup socat TCP-LISTEN:18093,bind="$VM_IP",reuseaddr,fork TCP:127.0.0.1:"$MANAGER_PORT" > ~/dse-relay.log 2>&1 &
echo "Open: http://$VM_IP:18093/"
ss -ltnp | grep 18093

Use esta redirección solo en una red de prueba confiable. Mientras socat esté activo, el administrador será accesible por la interfaz de red de la VM.

9. Ejecutar el desplegable desde la interfaz

1. Abra en Edge o Chrome la URL mostrada por el comando de redirección.
2. Confirme que Runtime status muestre READY y que no haya una ejecución activa.
3. En Connections, confirme que origen y destino muestren Configured. Deje vacíos los campos protegidos para conservar los valores integrados.
4. Para la primera prueba, configure Scheduler configuration como Manual only, Output directory como output y guarde la configuración.
5. Seleccione Run now y espere a que el estado vuelva a READY.
6. Confirme que Last result y Run history indiquen Success y verifique los archivos de salida y los datos de destino.

10. Detener, reiniciar y limpiar

La IP de la VM y el puerto del administrador pueden cambiar después de reiniciar. Ejecute manager.sh de nuevo, lea el nuevo puerto y reinicie la redirección socat. Para detenerla:

pkill -f 'socat TCP-LISTEN:18093' || true

Lista de verificación

• Ubuntu inicia desde el VHDX y SSH funciona
• El sistema de archivos raíz tiene espacio libre suficiente
• El puerto de origen/destino es accesible desde Ubuntu
• DataSourceExplorer.Runner, manager.sh y run.sh tienen permiso de ejecución
• manager-console.log informa una URL de administración local
• El navegador de Windows abre http://<VM-IP>:18093/
• Runtime status vuelve a READY después de Run now
• Run history muestra Success y existen los resultados/datos esperados

Solución de problemas

Para integrar esta guía en la ayuda del producto, use la página HTML localizada incluida. Mantenga los comandos sin traducir y traduzca solo las explicaciones y la guía de la interfaz.