IBM App Connect Enterprise y Event Streams

IBM App Connect Enterprise ya cuenta con el modelo de runtime adecuado para la integración orientada a eventos. El laboratorio ilustra cómo publicar un evento de negocio, cómo consumirlo de forma segura y cómo mantener el diseño fácil de redirigir desde un broker local a IBM Event Streams.

El laboratorio es deliberadamente sencillo.

Haremos:

• Iniciar un broker compatible con Kafka de forma local con Docker
• Crear dos topics Kafka
• Construir un flujo ACE que recibe HTTP y publica un evento
• Construir un segundo flujo ACE que consume el evento y republica una copia auditada
• Validar el resultado desde la línea de comandos
• Identificar exactamente qué cambia cuando la misma integración se apunta a IBM Event Streams

Para este laboratorio, el runtime utiliza la imagen Docker gratuita de IBM App Connect Enterprise for Developers.

1. Objetivo del laboratorio

Al finalizar este laboratorio deberías ser capaz de:

• Explicar cómo ACE utiliza los nodos KafkaProducer y KafkaConsumer en un flujo de eventos sencillo
• Separar la lógica del flujo de los detalles de conexión al runtime mediante una política Kafka
• Validar el tráfico de topics desde fuera de ACE
• Comprender qué partes permanecen sin cambios al pasar de un laboratorio local a IBM Event Streams

2. Software necesario

Para este laboratorio, utiliza:

• Imagen Docker de IBM App Connect Enterprise for Developers (ibmcom/ace:latest)
• App Connect Enterprise Toolkit instalado localmente en tu estación de trabajo
• Docker Engine y el plugin Docker Compose

Si Docker no está instalado en tu máquina, sigue los pasos del Apéndice A — Instalación de Docker antes de continuar.

Si todavía no tienes el App Connect Enterprise Toolkit instalado, obtenlo a través de IBM App Connect Enterprise Developer Edition. La descarga requiere una cuenta IBM gratuita.

Referencia IBM:

• Download ACE Developer Edition and get started

Instalación e inicio de ACE Developer Edition en Linux

Descarga el archivo .tar.gz desde el enlace IBM indicado anteriormente y extráelo:

tar -xzf ACE-*-LINUX64-DEVELOPER.tar.gz
cd ace-12.0.x.x

Acepta la licencia y configura el entorno:

sudo ./ace make registry global accept license silently
source /opt/ibm/ace-12.0.x.x/ace_env.sh

Inicia el Toolkit:

./ace toolkit

En el primer arranque, selecciona un directorio de espacio de trabajo cuando se solicite y, si es necesario, abre la perspectiva Integration Development mediante Window → Perspective → Open Perspective → Other.

3. Lo que vamos a construir

Flujos de mensajes y nodos ACE

Un flujo de mensajes ACE es un grafo dirigido de nodos de procesamiento. Cada nodo realiza un paso: recibir un mensaje, transformarlo, enrutarlo o enviarlo a un sistema externo. El Toolkit es la herramienta de autoría donde se colocan y conectan los nodos. Tras desplegar el flujo, el runtime ACE lo ejecuta.

Los nodos se comunican pasando un árbol de mensajes que es una representación estructurada en memoria de las cabeceras, el cuerpo y el entorno del mensaje. Cada nodo puede leer el árbol, modificarlo o reemplazarlo antes de pasarlo al siguiente nodo. Los nodos Compute de ESQL permiten remodelar el árbol con precisión antes de que llegue a un nodo de transporte como KafkaProducer.

Los dos nodos de transporte relevantes para este laboratorio son:

• El nodo KafkaProducer serializa el cuerpo del mensaje actual y lo publica en un topic Kafka. Como ACE gestiona internamente el ciclo de vida del cliente productor Kafka, la lógica de tu flujo no administra conexiones ni reintentos directamente.
• El nodo KafkaConsumer funciona como un disparador continuo. Sondea un topic Kafka en un intervalo configurable y, por cada mensaje que recibe, inicia una nueva ejecución del flujo. Desde la perspectiva del flujo, es el punto de entrada, el equivalente de un nodo HTTP Input, pero orientado a eventos en lugar de orientado a peticiones.

El patrón de dos flujos y dos topics

El laboratorio utiliza deliberadamente dos flujos y dos topics. Entender por qué esa forma importa es más relevante que el código que la implementa.

POST /orders
  -> Compute
  -> KafkaProducer
  -> HTTPReply

KafkaConsumer(topic ace-out)
  -> Compute
  -> KafkaProducer(topic ace-audit)
  -> Trace

El Flujo 1 conecta una petición HTTP síncrona con un evento asíncrono. El emisor recibe una respuesta inmediata. El evento de negocio (el pedido) queda ahora en un topic Kafka donde cualquier número de sistemas downstream puede consumirlo de forma independiente, a su propio ritmo, sin que el emisor lo conozca. Este es el núcleo del desacoplamiento orientado a eventos: el productor del evento y los consumidores no están acoplados ni en el tiempo ni en el código.

El Flujo 2 representa un procesador downstream. Consume el evento, añade sus propios metadatos y republica una copia enriquecida en un segundo topic. El segundo topic (ace-audit) está separado del primero (ace-out) para que el evento original se conserve sin modificaciones. Cualquier sistema que necesite el pedido en bruto lee de ace-out. Cualquier sistema que necesite la copia auditada y procesada lee de ace-audit. Un único topic que transportara ambas formas acoplaría la lógica de auditoría a cada consumidor que lee el original.

Esto será suficiente para ilustrar ambas direcciones de la interacción Kafka en ACE sin hacer que el artículo dependa de un entorno grande. La autoría se realizará en el Toolkit y el runtime utilizado para el laboratorio será el contenedor de la imagen IBM ACE developer.

4. Crear el entorno de laboratorio local

Por qué usar Redpanda en un laboratorio Kafka

El archivo compose que se muestra a continuación utiliza Redpanda como broker local en lugar de Apache Kafka. Redpanda implementa el protocolo de wire de Kafka de forma completa y un cliente que habla Kafka (incluidos los nodos KafkaProducer y KafkaConsumer de ACE) no puede distinguirlo a nivel de protocolo. Los topics, los grupos de consumidores, los offsets, la semántica de publicación y consumo, y la negociación de bootstrap que ACE realiza al iniciar un flujo funcionan de forma idéntica. Toda interacción que pruebes con Redpanda se traduce directamente a IBM Event Streams, que está construido sobre Apache Kafka.

Las razones prácticas para elegir Redpanda aquí son:

• Sin ZooKeeper. Apache Kafka requiere un conjunto ZooKeeper (o un quórum KRaft en versiones más recientes) junto al broker. Redpanda es un proceso único autocontenido, lo que mantiene el archivo compose corto y el arranque rápido.
• Sin autenticación de registro. La imagen developer de Redpanda se descarga desde Docker Hub sin credenciales. La imagen developer de ACE hace lo mismo. El laboratorio completo arranca con un solo docker compose up -d sin ningún paso previo de inicio de sesión.
• CLI rpk integrada. El comando rpk está incluido dentro del contenedor Redpanda. Permite crear topics y consumir mensajes directamente con docker compose exec sin instalar un cliente Kafka separado en tu máquina.
• Diseñado para desarrollo local. Los flags --overprovisioned y --mode dev-container del comando compose ajustan Redpanda para un entorno de portátil con un único nodo y recursos limitados. Un broker Kafka estándar necesita más ajustes para funcionar bien en esas condiciones.

Lo que Redpanda no reemplaza es la configuración específica de IBM Event Streams: certificados TLS, credenciales SCRAM, tokens IAM y la integración con el registro de esquemas que usa un despliegue de Event Streams en producción. Nada de eso es relevante para nuestro laboratorio. La sección 10 cubre exactamente qué cambia cuando se apuntan los mismos flujos a IBM Event Streams.

Configuración preliminar

Crea una carpeta de trabajo:

mkdir -p ~/ace-eventstreams-lab
cd ~/ace-eventstreams-lab

Crea un archivo docker-compose.yaml que defina los nodos ACE y Redpanda:

cat > docker-compose.yaml <<'EOF'
services:
  ace:
    image: ibmcom/ace:latest
    depends_on:
      - redpanda
    environment:
      LICENSE: "accept"
      ACE_SERVER_NAME: "ACESERVER"
    ports:
      - "7600:7600"
      - "7800:7800"
      - "7843:7843"

  redpanda:
    image: docker.redpanda.com/redpandadata/redpanda:latest
    command:
      - redpanda
      - start
      - --overprovisioned
      - --smp
      - "1"
      - --memory
      - "1G"
      - --reserve-memory
      - "0M"
      - --node-id
      - "0"
      - --check=false
      - --kafka-addr
      - internal://0.0.0.0:9092,external://0.0.0.0:19092
      - --advertise-kafka-addr
      - internal://redpanda:9092,external://localhost:19092
      - --pandaproxy-addr
      - internal://0.0.0.0:8082,external://0.0.0.0:18082
      - --advertise-pandaproxy-addr
      - internal://redpanda:8082,external://localhost:18082
      - --mode
      - dev-container
    ports:
      - "19092:19092"
      - "18082:18082"
EOF

Inicia el entorno de laboratorio:

docker compose up -d

Confirma que ambos contenedores están en funcionamiento (espera y repite hasta que estén operativos; esto llevará un tiempo porque las imágenes deben descargarse):

docker compose ps

Crea los dos topics utilizados en el laboratorio y confirma que existen:

docker compose exec redpanda rpk topic create ace-out
docker compose exec redpanda rpk topic create ace-audit
docker compose exec redpanda rpk topic list

5. El proyecto de política ACE y la política

Qué es una política Kafka y por qué importa

En ACE, una política es un artefacto XML almacenado en un Policy Project que externaliza la configuración de un flujo de mensajes. Una política Kafka específicamente almacena los detalles de conexión que los nodos Kafka de ACE necesitan para alcanzar un broker: las direcciones del servidor bootstrap, el protocolo de seguridad y, cuando la seguridad está habilitada, credenciales, configuración TLS y mecanismos SASL.

Sin una política, habría que incrustar esos detalles directamente en cada nodo KafkaProducer y KafkaConsumer, lo que dificultaría el mantenimiento y la promoción de los flujos entre entornos.

Con una política Kafka, el nodo del flujo almacena únicamente la referencia a la política y en tiempo de ejecución, ACE resuelve esa referencia y utiliza los detalles de conexión de la política en lugar de los del nodo. El BAR file del flujo es el mismo en todos los entornos. Solo cambia la política desplegada.

Un flujo de mensajes debe codificar lógica de negocio y transformación de datos. No debe codificar dónde vive el broker, qué puerto usa ni cómo funciona la autenticación. La política es lo que mantiene separadas esas dos preocupaciones.

En este laboratorio, la referencia a la política tiene este aspecto:

{EventStreamsPolicyProject}:LocalKafkaPolicy

donde EventStreamsPolicyProject es el nombre del Policy Project que creas en el Toolkit y LocalKafkaPolicy es el nombre de la política Kafka individual dentro de él. Cada nodo KafkaProducer y KafkaConsumer del laboratorio utiliza la misma referencia. Si más adelante apuntas el laboratorio a IBM Event Streams, actualizas LocalKafkaPolicy o despliegas una nueva para el entorno de destino, y los flujos no requieren cambios.

Un detalle de diseño a tener en cuenta: el Toolkit requiere un valor en el campo Bootstrap servers de cada nodo antes de guardarlo. Ese valor no se usa en tiempo de ejecución cuando se adjunta una política, ya que la política lo sobreescribe, pero debe estar presente. Para este laboratorio, lo configuramos como redpanda:9092 en todos los nodos.

Crear el proyecto y la política

En el Toolkit:

1. Crea un nuevo Policy Project llamado EventStreamsPolicyProject
2. Añade una política Kafka llamada LocalKafkaPolicy
3. Configúrala para el broker del laboratorio local:

Bootstrap servers: redpanda:9092
Security protocol: PLAINTEXT

Utilizamos redpanda:9092 y no localhost:19092 porque el runtime ACE se ejecuta dentro de la red Docker, donde alcanza a Redpanda por su nombre de servicio. localhost:19092 se seguirá usando para la comunicación desde la máquina host (para los comandos curl y rpk).

Para este laboratorio local, mantenemos la política intencionalmente sencilla. No mezcles TLS, SCRAM ni IAM por ahora.

6. Crear la aplicación ACE

Qué hacen realmente los nodos de estos flujos

Antes de construir los flujos, conviene ser precisos sobre lo que hace cada tipo de nodo.

• El nodo HTTP Input abre un listener en el servidor HTTP de ACE. Cuando llega una petición a la ruta configurada (/orders), el nodo deserializa el cuerpo de la petición y lo coloca en el árbol de mensajes bajo InputRoot.JSON, y el flujo comienza a ejecutarse. No hay sondeo. La ejecución se desencadena directamente por la conexión HTTP entrante.
• El nodo Compute (ESQL) es el paso de transformación. ESQL es el lenguaje integrado de ACE para trabajar con el árbol de mensajes. El nodo ejecuta el módulo ESQL que le asocias, de modo que tras el nodo Compute, el árbol de mensajes contiene lo que hayas puesto en OutputRoot. El siguiente nodo del flujo verá eso, y no la petición original.
• El nodo KafkaProducer toma el cuerpo del mensaje actual en OutputRoot.JSON.Data, lo serializa y lo publica en el topic configurado. El nodo gestiona el ciclo de vida del productor Kafka: mantiene una conexión con el broker, gestiona la selección de partición y espera el acuse de recibo del broker antes de propagar el mensaje al siguiente nodo. El flujo no avanza hacia HTTP Reply hasta que el broker ha confirmado la publicación.
• El nodo HTTP Reply envía la respuesta HTTP al emisor. Para cuando este nodo se ejecuta, el evento producido ya está en el topic Kafka. La respuesta es deliberadamente mínima en este laboratorio. En un flujo de producción normalmente incluirías un ID de correlación o un cuerpo de estado.
• El nodo KafkaConsumer es un nodo disparador. ACE sondea el topic configurado en un intervalo configurable y cuando llega un mensaje, el nodo lo coloca en el árbol de mensajes y el resto del flujo se ejecuta. Un flujo KafkaConsumer es un proceso de fondo continuo y no tiene ningún emisor esperando una respuesta. El ID de grupo de consumidores que configuras en el nodo es lo que Kafka utiliza para rastrear qué mensajes ha procesado ya este consumidor en particular. Si detienes y reinicias el flujo, Kafka continúa desde donde lo dejó para ese ID de grupo.
• Los grupos de consumidores merecen una nota específica. Un grupo de consumidores es un grupo con nombre de uno o más consumidores Kafka que colectivamente consumen un topic. Kafka asigna particiones a los consumidores del grupo. Si un flujo se escala a múltiples instancias, todas las instancias con el mismo ID de grupo comparten el trabajo: cada mensaje es procesado exactamente por una instancia. Si utilizas un ID de grupo diferente, cada instancia recibe todos los mensajes de forma independiente. Este laboratorio usa un único consumidor con el ID de grupo ace-eventstreams-demo.
• El nodo Trace escribe una entrada de registro formateada en el log del servidor de integración ACE. En este laboratorio registra que el flujo de auditoría procesó un pedido específico. Es la forma más sencilla de observabilidad, confirmando que el segundo flujo se ejecutó y puede inspeccionarse.

Construir la aplicación

Crea una aplicación llamada AceEventStreamsLab.

Dentro de ella, construye dos flujos de mensajes:

Flujo 1: HTTP a Kafka

Crea un flujo llamado HttpToKafka.msgflow con estos nodos:

Configuración sugerida:

• HTTP Input
  • Sufijo de ruta: /orders
• KafkaProducer
  • Nombre del topic: ace-out
  • Servidores bootstrap: redpanda:9092
  • Política Kafka: {EventStreamsPolicyProject}:LocalKafkaPolicy

En la aplicación, crea un nuevo archivo ESQL llamado NormalizeOrderEvent.esql y pega este código:

CREATE COMPUTE MODULE NormalizeOrderEvent
  CREATE FUNCTION Main() RETURNS BOOLEAN
  BEGIN
    CREATE LASTCHILD OF OutputRoot DOMAIN 'JSON';

    SET OutputRoot.JSON.Data.eventType = 'OrderCreated';
    SET OutputRoot.JSON.Data.source = 'ACE';
    SET OutputRoot.JSON.Data.orderId = COALESCE(InputRoot.JSON.Data.orderId, '');
    SET OutputRoot.JSON.Data.customer = COALESCE(InputRoot.JSON.Data.customer, '');
    SET OutputRoot.JSON.Data.amount = COALESCE(InputRoot.JSON.Data.amount, 0);
    SET OutputRoot.JSON.Data.currency = COALESCE(InputRoot.JSON.Data.currency, 'EUR');
    SET OutputRoot.JSON.Data.processingNote = 'Published by ACE to topic ace-out';

    RETURN TRUE;
  END;
END MODULE;

A continuación, abre las propiedades del nodo Compute y establece el campo ESQL Module en NormalizeOrderEvent (usa la opción de explorar y seleccionar).

Flujo 2: auditoría Kafka a Kafka

Crea un segundo flujo llamado KafkaAudit.msgflow con estos nodos:

Configuración sugerida:

• KafkaConsumer
  • Nombre del topic: ace-out
  • Servidores bootstrap: redpanda:9092
  • ID de grupo de consumidores: ace-eventstreams-demo
  • Política Kafka: {EventStreamsPolicyProject}:LocalKafkaPolicy
• KafkaProducer
  • Nombre del topic: ace-audit
  • Servidores bootstrap: redpanda:9092
  • Política Kafka: {EventStreamsPolicyProject}:LocalKafkaPolicy

Crea un segundo archivo ESQL llamado AddAuditMetadata.esql con el código siguiente:

CREATE COMPUTE MODULE AddAuditMetadata
  CREATE FUNCTION Main() RETURNS BOOLEAN
  BEGIN
    CREATE LASTCHILD OF OutputRoot DOMAIN 'JSON';

    SET OutputRoot.JSON.Data = InputRoot.JSON.Data;
    SET OutputRoot.JSON.Data.auditStage = 'Consumed and republished by ACE';
    SET OutputRoot.JSON.Data.auditFlow = 'KafkaAudit';

    RETURN TRUE;
  END;
END MODULE;

A continuación, abre las propiedades del nodo Compute y establece el campo ESQL Module en AddAuditMetadata.

Configura el patrón del nodo Trace con algo pequeño y legible, por ejemplo:

Kafka audit flow processed order ${Root.JSON.Data.orderId}

7. Desplegar la aplicación

Qué significa el despliegue en ACE

Cuando despliegas desde el Toolkit, empaqueta tus flujos y recursos en un BAR file (Broker Archive) y lo envía al servidor de integración a través de la API de administración. Un BAR file es un archivo ZIP que contiene los binarios compilados del flujo, los módulos ESQL y otros recursos de los que depende el flujo. El servidor de integración lo desempaqueta e inicia los flujos.

Los Policy Projects no se incluyen en el BAR de la aplicación. Se despliegan como artefactos separados. Esto es intencionado: el mismo BAR de la aplicación puede ejecutarse en desarrollo, pruebas y producción, siendo lo único que cambia entre entornos la política desplegada. Esa separación es el objetivo de externalizar los detalles de conexión en una política.

El orden de despliegue importa por esa razón. Cuando el runtime ACE carga un flujo que hace referencia a {EventStreamsPolicyProject}:LocalKafkaPolicy, busca esa política en el conjunto de políticas desplegadas actualmente. Si la política no está presente, el nodo no puede inicializar su conexión Kafka y el flujo falla al arrancar. Desplegar el Policy Project primero garantiza que esté presente antes de que se carguen los flujos que dependen de él.

Antes de poder desplegar desde el Toolkit, necesitas conectarlo al servidor de integración que se ejecuta en el contenedor Docker.

En el Toolkit, abre la vista Integration Servers. Haz clic derecho y elige Connect to an Integration Server. Introduce las siguientes propiedades de conexión:

Hostname: localhost
Port:     7600

Deja los campos de seguridad en blanco para este laboratorio local. El puerto 7600 es el puerto de administración ACE expuesto por la configuración de Docker Compose.

Una vez establecida la conexión y visible el servidor en la vista, despliega en este orden:

1. Haz clic derecho sobre EventStreamsPolicyProject y selecciona Deploy. Espera a que se complete.
2. Haz clic derecho sobre AceEventStreamsLab y selecciona Deploy.

Tras el despliegue, el endpoint POST /orders estará disponible en el puerto 7800.

8. Probar la ruta de publicación

Envía un evento de negocio a ACE:

curl -X POST http://localhost:7800/orders \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "SO-1001",
    "customer": "ACME",
    "amount": 125.50,
    "currency": "EUR"
  }'

Consume un mensaje directamente del topic de origen:

docker compose exec redpanda rpk topic consume ace-out -n 1

Deberías ver el evento normalizado producido por ACE.

9. Probar la ruta de consumo y auditoría

Ahora validemos el segundo flujo. Consume un mensaje del topic de auditoría:

docker compose exec redpanda rpk topic consume ace-audit -n 1

Si el segundo flujo está activo, deberías ver el mismo evento de negocio con los campos adicionales:

• auditStage
• auditFlow

Esto prueba que:

• ACE publicó en Kafka
• ACE consumió desde Kafka
• ACE republicó un evento derivado

Eso ya es un patrón de integración orientada a eventos válido, aunque la lógica de negocio sea deliberadamente pequeña.

10. Qué cambia al pasar a IBM Event Streams

El punto importante es que el diseño del flujo de mensajes no necesita cambiar. Algunos cambios necesarios en el runtime son:

1. Reemplazar el servidor bootstrap local redpanda:9092 por los servidores bootstrap de IBM Event Streams
2. Pasar de PLAINTEXT a la configuración segura apropiada
3. Añadir las credenciales requeridas y, si es necesario, el material del truststore
4. Redesplegar la política Kafka actualizada y las credenciales

11. Lecciones prácticas para producción

Usa políticas, no valores de broker codificados directamente

No pongas detalles de broker específicos del entorno en cada nodo. Mantenlos en la política Kafka para que pasar de desarrollo a pruebas y a producción sea una cuestión de runtime, no un rediseño del flujo.

El escalado tiene consecuencias en el orden

IBM documenta tres formas principales de escalar el consumo Kafka en ACE:

• instancias de flujo adicionales
• múltiples flujos desplegados en el mismo grupo de consumidores
• múltiples conexiones Kafka

Eso mejora el rendimiento, pero también puede afectar las expectativas de ordenación. Si el orden importa, trata el escalado y el comportamiento de commit como parte del diseño funcional, no solo como ajuste del runtime.

Mantén el primer flujo sencillo

La mejor primera integración de ACE y Event Streams no es una complicada. Es un camino corto que demuestra:

• Conexión
• Escritura en topic
• Lectura de topic
• Transformación trazable

Una vez que ese camino sea estable, añade validación de esquemas, enrutamiento de errores, reintentos, manejo de mensajes fallidos y seguridad más robusta.

12. Conclusiones clave

• Los nodos Kafka de ACE son suficientes para construir una primera integración orientada a eventos limpia
• Un broker compatible con Kafka local es una buena forma de validar la forma del flujo antes de pasar a IBM Event Streams
• La política Kafka es la costura crítica entre la lógica del flujo y la configuración del entorno
• Un flujo de publicación más un flujo de consumo y auditoría es un mejor primer laboratorio que un escenario completo de extremo a extremo
• Pasar a IBM Event Streams debería ser principalmente un cambio de configuración, no un rediseño

Documentación IBM

Para detalles más profundos específicos de IBM, consulta estas referencias oficiales:

• Using Kafka with IBM App Connect Enterprise
• Connecting IBM App Connect to IBM Event Streams
• KafkaConsumer node
• Producing messages on Kafka topics
• Consuming messages from Kafka topics
• Configuring security credentials for connecting to Kafka
• Policies overview
• Scaling messages with Kafka

Apéndice A — Instalación de Docker

Si Docker Engine y el plugin Compose no están ya presentes en tu máquina, usa los comandos siguientes según tu distribución. Ejecuta estos pasos antes de comenzar la sección 2.

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker

RHEL / Rocky / Alma / CentOS Stream

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

Verifica la instalación:

docker version
docker compose version

Ambos comandos deben devolver información de versión sin errores. Si docker compose version falla, el plugin Compose no está instalado: vuelve a ejecutar el comando de instalación y comprueba la salida para detectar errores.