Agentes privados de Jitterbit en Docker

Introducción

Los ejemplos en esta página te muestran cómo ejecutar uno o más agentes privados en contenedores utilizando la imagen de Docker hub de Jitterbit. La sección de Servicio de verificación de estado explica cómo usar el servicio de verificación de estado en un contenedor en ejecución, y la sección de Recursos de solución de problemas proporciona algunos enlaces a problemas comunes y sus soluciones.

Los siguientes ejemplos muestran cómo ejecutar un solo agente:

• Inicio rápido

• Registro manual con variables de entorno

• Registro automático con variables de entorno

• Registro automático con archivo register.json

Los siguientes ejemplos muestran cómo ejecutar múltiples agentes:

• Múltiples agentes con Docker compose

• Múltiples agentes con Helm y Kubernetes

Requisitos previos

Debes tener lo siguiente para todos los ejemplos en esta página:

• Docker

• Tu nombre de usuario y contraseña de la cuenta de Harmony.

• El nombre de tu organización en Harmony.

Además, debes tener lo siguiente para ejecutar los ejemplos de múltiples agentes:

• Docker Compose

• Helm

• Kubernetes

Inicio rápido

Este ejemplo utiliza el comando jitterbit-config para solicitar la información de registro del agente, el comando jitterbit para iniciar el agente, y tail -F para esperar y mostrar el archivo de registro del agente.

1. Selecciona Consola de Gestión > Agentes en el menú del Portal Harmony, luego agrega un grupo de agentes privado, o anota el nombre y ID de uno existente.

2. En una terminal, ejecuta este comando y responde a las solicitudes:

   docker run -it jitterbit/agent sh -c "\
   jitterbit-config; \
   jitterbit start; \
   tail -F log/jitterbit-agent.log"
   

3. Para verificar el estado de tu agente, actualiza la página Consola de Gestión > Agentes.

4. En la terminal, presiona Control+C para detener el agente, o utiliza el comando docker container stop.

5. (Opcional) Elimina el agente utilizando la Consola de Gestión. (Los agentes iniciados de esta manera no se eliminan automáticamente al detenerse.)

Registro manual con variables de entorno

En el ejemplo de inicio rápido, debes ingresar la información de registro del agente cuando se te solicite. En este ejemplo, esta información se proporciona utilizando variables de entorno.

1. Agrega un agente a tu grupo de agentes y anota su nombre.

2. Crea un archivo que contenga lo siguiente, con valores establecidos de acuerdo con la tabla a continuación:

   HARMONY_ORIGIN=
   HARMONY_USERNAME=
   HARMONY_PASSWORD=
   HARMONY_ORG_NAME=
   HARMONY_AGENT_GROUP_NAME=
   HARMONY_AGENT_NAME=
   

   Variable	Descripción del Valor
   HARMONY_ORIGIN	La URL de inicio de sesión para tu cuenta de Harmony, https://REGION.jitterbit.com, donde REGION es uno de na-east, emea-west o apac-southeast.
   HARMONY_USERNAME	Tu nombre de usuario de la cuenta de Harmony.
   HARMONY_PASSWORD	Tu contraseña de la cuenta de Harmony.
   HARMONY_ORG_NAME	El nombre de tu organización en Harmony.
   HARMONY_AGENT_GROUP_NAME	El nombre del grupo de agentes y el nombre del entorno, separados por un guion bajo.
   HARMONY_AGENT_NAME	El nombre del agente.

   Ejemplo

   HARMONY_ORIGIN=https://na-east.jitterbit.com
   HARMONY_USERNAME=example@jbexample.com
   HARMONY_PASSWORD=P@55w0rd
   HARMONY_ORG_NAME=Example Org
   HARMONY_AGENT_GROUP_NAME=Example Agent Group_Example Env
   HARMONY_AGENT_NAME=Example Agent 1
   

3. En una terminal, ejecuta este comando para iniciar el agente, reemplazando FILE con el nombre del archivo creado en el paso 2:

   docker run --env-file FILE jitterbit/agent
   

4. Para verificar el estado de tu agente, actualiza la página Consola de Gestión > Agentes.

5. En la terminal, presiona Control+C para detener el agente, o utiliza el comando docker container stop.

6. (Opcional) Eliminar el agente usando la Consola de Gestión. (Los agentes iniciados de esta manera no se eliminan automáticamente al detenerse.)

Registro automático con variables de entorno

Hay dos desventajas con el ejemplo de registro manual: debes agregar manualmente un agente en la Consola de Gestión, y tus credenciales de Harmony son visibles para cualquiera que tenga acceso al sistema.

Este ejemplo evita ambos problemas. Utiliza registro automático para agregar automáticamente un agente a Harmony. Los valores de registro requeridos se pasan al contenedor utilizando variables de entorno (la mayoría de las cuales están precedidas por AUTO_REGISTER). Para la autenticación, puedes usar un par de nombre de usuario/contraseña encriptado, o un token de acceso. (Ambos métodos se muestran aquí.)

1. Elige un método de autenticación:

   Nombre de usuario/contraseñaToken de acceso

   1. En una terminal, ejecuta el siguiente comando de jitterbit-utils para encriptar tus credenciales, reemplazando USERNAME y PASSWORD con tu nombre de usuario y contraseña de Harmony:

      docker run jitterbit/agent jitterbit-utils -e USERNAME PASSWORD
      

      Comando de ejemplo

      docker run jitterbit/agent jitterbit-utils -e example@jbexample.com P@55w0rd
      

      Salida de ejemplo

      $00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
      $003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=
      

   2. Copia los valores para usarlos en el siguiente paso (usando la primera línea para AUTO_REGISTER_ENCRYPTED_USERNAME, y la segunda línea para AUTO_REGISTER_ENCRYPTED_PASSWORD).

   3. Crea un archivo que contenga lo siguiente, con los valores sustituidos de acuerdo con la tabla a continuación:

      HARMONY_ORIGIN=
      AUTO_REGISTER=true
      AUTO_REGISTER_AGENT_GROUP_ID=
      AUTO_REGISTER_AGENT_NAME_PREFIX=auto
      AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP=false
      AUTO_REGISTER_ENCRYPTED_USERNAME=
      AUTO_REGISTER_ENCRYPTED_PASSWORD=
      

   Ejemplo de archivo de variable de entorno

   HARMONY_ORIGIN=https://na-east.jitterbit.com
   AUTO_REGISTER=true
   AUTO_REGISTER_AGENT_GROUP_ID=12345
   AUTO_REGISTER_AGENT_NAME_PREFIX=auto
   AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP=false
   AUTO_REGISTER_ENCRYPTED_USERNAME=$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
   AUTO_REGISTER_ENCRYPTED_PASSWORD=$003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=
   

   Variable	Descripción del valor
   HARMONY_ORIGIN	La URL de inicio de sesión para tu cuenta de Harmony, https://REGION.jitterbit.com, donde REGION es uno de na-east, emea-west o apac-southeast.
   AUTO_REGISTER_AGENT_GROUP_ID	El número de identificación del grupo de agentes.
   AUTO_REGISTER_ENCRYPTED_USERNAME	La primera línea de salida de jitterbit-utils -e.
   AUTO_REGISTER_ENCRYPTED_PASSWORD	La segunda línea de salida de jitterbit-utils -e.

   1. Selecciona Consola de administración > Tokens de acceso en el menú del Portal de Harmony, luego crea un token de acceso. Elige el entorno con el que está asociado tu grupo de agentes privado, y establece el alcance en Registro de agentes.

   2. Copia el token para establecer el valor de AUTO_REGISTER_TOKEN en el siguiente paso.

   3. Crea un archivo que contenga lo siguiente, con valores sustituidos de acuerdo con la tabla a continuación:

      HARMONY_ORIGIN=
      AUTO_REGISTER=true
      AUTO_REGISTER_AGENT_GROUP_ID=
      AUTO_REGISTER_AGENT_NAME_PREFIX=auto
      AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP=false
      AUTO_REGISTER_TOKEN=
      

   Ejemplo de archivo de variable de entorno

   HARMONY_ORIGIN=https://na-east.jitterbit.com
   AUTO_REGISTER=true
   AUTO_REGISTER_AGENT_GROUP_ID=12345
   AUTO_REGISTER_AGENT_NAME_PREFIX=auto
   AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP=false
   AUTO_REGISTER_TOKEN=jb_d86ec8a0-0693-4392-b345-ef4e134dab42
   

   Variable	Descripción del valor
   HARMONY_ORIGIN	La URL de inicio de sesión para tu cuenta de Harmony, https://REGION.jitterbit.com, donde REGION es uno de na-east, emea-west o apac-southeast.
   AUTO_REGISTER_AGENT_GROUP_ID	El número de identificación del grupo de agentes.
   AUTO_REGISTER_TOKEN	Token de acceso con el alcance Registro de Agentes.

2. Ejecuta este comando para iniciar el agente privado en contenedor, donde FILE es el nombre del archivo creado en el paso anterior:

   docker run --detach --env-file FILE jitterbit/agent
   

   Consejo

   Para habilitar la observabilidad nativa de Jitterbit con este método, agrega AUTO_REGISTER_AGENT_METRICS_TOKEN a la lista de variables de entorno pasadas al contenedor. El valor es un token de acceso con el alcance Métrica de Agente.

3. Para verificar el estado de tu agente, actualiza la página Consola de Administración > Agentes.

4. Para detener el agente, utiliza la Consola de Administración para detener el drenaje.

5. Para detener el contenedor, encuentra el ID del contenedor con docker ps, luego usa docker container stop CONTAINER_ID.

Registro automático con el archivo register.json

Una alternativa al uso de variables de entorno es establecer los valores requeridos en un archivo register.json. Este archivo se puede colocar en un subdirectorio conf, desde donde el contenedor del agente lo lee y lo utiliza para registrar el agente. Al igual que en el ejemplo anterior, puedes autenticarte utilizando un nombre de usuario y contraseña, o un token de acceso.

1. Elige un método de autenticación:

   Nombre de usuario/contraseñaToken de acceso

   1. En una terminal, ejecuta el siguiente comando jitterbit-utils para cifrar tus credenciales, reemplazando USERNAME y PASSWORD con tu nombre de usuario y contraseña de Harmony:

      docker run jitterbit/agent jitterbit-utils -e USERNAME PASSWORD
      

      Comando de ejemplo

      docker run jitterbit/agent jitterbit-utils -e example@jbexample.com P@55w0rd
      

      Salida de ejemplo

      $00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
      $003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=
      

   2. Crea un directorio y un archivo conf/register.json que contenga lo siguiente, con los valores establecidos (resaltados) de acuerdo con la tabla a continuación:

      conf/register.json

      {
          "cloudUrl": "https://REGION.jitterbit.com",
          "agentGroupId": GROUP_ID,
          "username": "ENCRYPTED_USERNAME",
          "password": "ENCRYPTED_PASSWORD",
          "agentNamePrefix": "test",
          "deregisterAgentOnDrainstop": false,
          "retryCount": 10,
          "retryIntervalSeconds": 5
      }
      

      Parámetro	Descripción del valor
      cloudUrl	La URL de inicio de sesión para tu cuenta de Harmony, https://REGION.jitterbit.com, donde REGION es uno de na-east, emea-west o apac-southeast.
      agentGroupId	El número de identificación del grupo de agentes.
      username	La primera línea de salida de jitterbit-utils -e.
      password	La segunda línea de salida de jitterbit-utils -e.

      Ejemplo conf/register.json

      {
          "cloudUrl": "https://na-east.jitterbit.com",
          "agentGroupId": 12345,
          "username": "$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C",
          "password": "$003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=",
          "agentNamePrefix": "test",
          "deregisterAgentOnDrainstop": false,
          "retryCount": 10,
          "retryIntervalSeconds": 5
      }
      

   1. Selecciona Consola de gestión > Tokens de acceso en el menú del Portal Harmony, luego crea un token de acceso. Elige el entorno con el que está asociado tu grupo de agentes privado, y establece el alcance en Registro de agente.

   2. Copia el token para establecer el valor de ACCESS_TOKEN en el siguiente paso.

   3. Crea un directorio y un archivo conf/register.json que contenga lo siguiente, con los valores establecidos (resaltados) de acuerdo con la tabla a continuación:

      conf/register.json

      {
          "cloudUrl": "https://REGION.jitterbit.com",
          "agentGroupId": GROUP_ID,
          "token": "ACCESS_TOKEN",
          "agentNamePrefix": "test",
          "deregisterAgentOnDrainstop": false,
          "retryCount": 10,
          "retryIntervalSeconds": 5
      }
      

      Parámetro	Descripción del valor
      cloudUrl	La URL de inicio de sesión para tu cuenta de Harmony, https://REGION.jitterbit.com, donde REGION es uno de na-east, emea-west o apac-southeast.
      agentGroupId	El número de identificación del grupo de agentes.
      token	Token de acceso con alcance Registro de agente.

      Ejemplo conf/register.json

      {
          "cloudUrl": "https://na-east.jitterbit.com",
          "agentGroupId": 12345,
          "token": "jb_21b0cda9-18f7-4953-bd71-8616def9d6bd",
          "agentNamePrefix": "test",
          "deregisterAgentOnDrainstop": false,
          "retryCount": 10,
          "retryIntervalSeconds": 5
      }
      

2. Ejecuta este comando para iniciar el agente privado en contenedor:

   docker run --detach --name jitterbit-agent --rm --volume ./conf:/conf --volume local_resources:/opt/jitterbit/Resources jitterbit/agent
   

   Consejo

   Para habilitar la observabilidad nativa de Jitterbit con este método, agrega el parámetro agentMetricsToken al archivo register.json. El valor es un token de acceso con el alcance Agente Métrico.

3. Para verificar el estado de tu agente, actualiza la página Consola de Administración > Agentes.

4. Para detener el agente, utiliza la Consola de Administración para detener el drenaje.

5. Para detener el contenedor, encuentra el ID del contenedor con docker ps, luego usa docker stop CONTAINER_ID.

Múltiples agentes con docker compose

En este ejemplo, tres agentes privados con configuraciones idénticas se ejecutan en un grupo de agentes.

1. Crea un archivo de variables de entorno como se muestra arriba.

2. Crea un archivo docker-compose.yml que contenga lo siguiente:

   docker-compose.yml

   services:
       agent1:
           env_file: FILE
           image: jitterbit/agent
           container_name: jitterbit-agent1
       agent2:
           env_file: FILE
           image: jitterbit/agent
           container_name: jitterbit-agent2
       agent3:
           env_file: FILE
           image: jitterbit/agent
           container_name: jitterbit-agent3
   

   • FILE: El nombre del archivo de variables de entorno creado en el paso 1.

3. Ejecuta este comando para iniciar el grupo de agentes privados:

   docker compose up -d
   

   Consejo

   Ejecuta docker compose logs -f para ver los archivos de registro de todos los agentes, o docker stats para monitorear el uso de recursos de cada agente.

4. Para verificar el estado de tu agente, actualiza la página Consola de Administración > Agentes.

5. Ejecuta este comando para detener el grupo de agentes privados y eliminar sus contenedores:

   docker compose down -d
   

Múltiples agentes con helm y kubernetes

Jitterbit proporciona un chart de Helm que puedes usar para ejecutar un clúster de agentes utilizando Kubernetes.

1. Inicia un clúster de Kubernetes.

   Consejo

   En Docker Desktop, selecciona Configuración > Kubernetes > Habilitar Kubernetes.

2. Ejecuta este comando para cifrar tu nombre de usuario y contraseña de Harmony:

   docker run jitterbit/agent jitterbit-utils -e USERNAME PASSWORD
   

   Consejo

   Puedes usar la misma salida de ejemplos anteriores.

3. Crea un archivo values.yaml que contenga lo siguiente, con valores sustituidos de acuerdo con la tabla a continuación:

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

   nameOverride: private-agent-group image: repository: jitterbit/agent pullPolicy: always agent: registerjson: cloudUrl: "https://REGION.jitterbit.com" agentGroupId: GROUP_ID username: ENCRYPTED_USERNAME password: ENCRYPTED_PASSWORD agentNamePrefix: "test" deregisterAgentOnDrainstop: true hpa: enabled: true minReplicas: 3 maxReplicas: 5 replicas: 4

   Línea	Valor	Reemplazar con
   9	REGION	La región de tu cuenta de Harmony (na-east, emea-west o apac-southeast).
   10	GROUP_ID	El número de identificación del grupo de agentes.
   11	ENCRYPTED_USERNAME	La primera línea de salida del paso 2.
   12	ENCRYPTED_PASSWORD	La segunda línea de salida del paso 2.

   Precaución

   Esta configuración especifica que Kubernetes debe ejecutar al menos 3 y como máximo 5 agentes si el Horizontal Pod Autoscaler está activo, o 4 agentes si no lo está. Dado que cada agente privado de Docker necesita aproximadamente 0.25 núcleos de CPU y 2 GB de memoria, debes verificar que las especificaciones de tu host puedan soportar este número de agentes. También puedes agregar un elemento resources para establecer los límites de utilización de recursos. Para más detalles, consulta el ejemplo de Jitterbit en el archivo value.yml.

4. Ejecuta estos comandos para agregar y actualizar el repositorio del gráfico de Helm:

   helm repo add jitterbit https://jitterbit.github.io/charts
   helm repo update
   

5. Ejecuta este comando para iniciar el clúster de agentes privados:

   helm upgrade -i -f values.yaml private-agent-group jitterbit/agent-group
   

   Consejo

   Ejecuta kubectl -n default get pods --watch para monitorear el estado del clúster, o kubectl exec -it private-agent-group-0 -- curl localhost:46912/axis/v1/cdk/internal/members para listar los miembros del clúster del servicio en escucha.

6. Ejecuta este comando para detener el clúster y eliminar los contenedores:

   helm uninstall private-agent-group
   

Variables de entorno

Las siguientes variables de entorno son reconocidas por la imagen Docker del agente privado de Jitterbit:

Puertos

Al ejecutarse como un contenedor, se pueden exponer los siguientes puertos:

Servicio de verificación de estado

Para ver el estado de un agente privado, mapea el puerto 3000 en el contenedor a un puerto local, luego emite una solicitud HTTP GET a localhost en el puerto mapeado. Puedes hacer esto utilizando la opción -p/--publish en los comandos docker run, o configurando la clave ports en docker compose:

docker run -p 3000:3000 <otras opciones> jitterbit/agent

services:
    agent:
        env_file: FILE
        image: jitterbit/agent
        container_name: jitterbit-agent
        ports:
            - "3000"

Para llamar al servicio, utiliza un navegador web o curl para hacer una solicitud en el puerto 3000:

curl -i localhost:3000

La respuesta está en formato JSON, con campos que indican (como true o false) el estado general del agente privado y el estado de los servicios individuales:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 04 Aug 2025 09:10:11 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Content-Length: 112

{"agent":true,"servers":{"apache_http":true,"apache_https":true,"tomcat_http":true,"tomcat_shutdown_http":true}}

Los códigos de respuesta HTTP son los siguientes:

Recursos de solución de problemas

Estas secciones en la página de solución de problemas pueden ayudar al solucionar problemas de agentes privados que se ejecutan en Docker:

• Agente privado de Jitterbit no en ejecución o detenido o inalcanzable.

• Agente privado de Jitterbit mostrando diferentes versiones o IPs.

• Errores de conexión, websocket y E/S en agentes privados de Jitterbit utilizando máquinas virtuales de Azure.

• Solución de problemas de Docker.