Registro de agentes para agentes privados de Jitterbit

Introducción

Antes de que un agente privado pueda procesar operaciones de proyectos de integración, debe registrarse con un servidor Harmony. La información necesaria para registrarse incluye la URL del servidor Harmony para la región de su organización, las credenciales de su cuenta de Harmony, el nombre del grupo de agentes privados al que se unirá y el nombre del propio agente. Para obtener el nombre de un agente privado, primero debe agregar uno utilizando la página Agentes de la Consola de Administración. Luego puede proporcionarlo como una de las piezas requeridas de información de registro durante el paso de instalación en Windows (con entrada manual en el instalador), el paso de configuración en Linux (con entrada manual o parámetros para jitterbit-config), o al iniciar un contenedor Docker (con variables de entorno). Este enfoque para el registro se conoce como registro manual.

Si desea aprovisionar y eliminar automáticamente agentes privados en contenedores (por ejemplo, utilizando Kubernetes), debe utilizar la función de auto-registro del agente privado de Jitterbit. Con esto, no es necesario agregar un agente con la página Agentes de la Consola de Administración. El sistema agrega automáticamente un agente privado a un grupo de agentes nombrado, genera un nombre de agente y luego lo registra. El sistema también puede, opcionalmente, desregistrar y eliminar el agente privado del grupo de agentes cuando el agente se detiene. (Hay una desventaja: no se puede usar un proxy con el registro automático.)

Cómo funciona

Esta sección es una visión general de los conceptos clave y configuraciones que rigen cómo un agente se registra y desregistra, y cómo se comporta después de un reinicio.

El archivo credentials.txt

Cuando un agente privado se registra con Harmony por primera vez, crea el archivo JITTERBIT_HOME/Resources/credentials.txt. Este archivo contiene las credenciales encriptadas del agente y se utiliza para autenticar y reconectar a Harmony después de un reinicio. Debe ser preservado para permitir que el agente se reinicie.

Comportamiento del agente al reiniciar

El parámetro deregisterAgentOnDrainstop del archivo register.json controla lo que sucede cuando un agente privado se detiene o reinicia. (Este parámetro también se puede pasar como una variable de entorno en entornos automatizados). Los valores permitidos son true y false. Cada valor tiene el siguiente comportamiento:

• deregisterAgentOnDrainstop=false: Este es el valor predeterminado. Con esto, un agente no se elimina de Harmony cuando se detiene, sino que permanece listado en un estado de Detenido.

  Cuando el agente se reinicia, utiliza su archivo existente credentials.txt para re-autenticarse con Harmony y reanudar operaciones. Este es el enfoque recomendado para la mayoría de los casos de uso, especialmente cuando se necesita que los agentes persistan a través de reinicios planificados o no planificados.

• deregisterAgentOnDrainstop=true: Con esto, el agente se desregistra activamente de Harmony cuando se detiene, y se elimina de la lista de agentes del grupo de agentes en la Consola de Administración.

  A partir de la versión 12.4 del agente de Docker, reiniciar el contenedor desregistra el agente existente y registra uno nuevo automáticamente, sin necesidad de limpieza manual. Esto hace que esta configuración sea adecuada para entornos de escalado automático donde los agentes se consideran desechables y se crean y destruyen con frecuencia. Tenga en cuenta que reiniciar el proceso del agente Jitterbit dentro de un contenedor en ejecución (sin reiniciar el contenedor en sí) aún provoca que el agente se desregistre, eliminándolo de Harmony, pero no activa un nuevo registro. Para recuperarse, reinicie el contenedor.

  En agentes de Docker que ejecutan versiones anteriores y en agentes de Linux, credentials.txt permanece después de la desregistración y causa fallos de autenticación al reiniciar el contenedor. Para recuperarse, debe eliminar manualmente el archivo credentials.txt obsoleto, lo que obliga a un nuevo registro en el próximo inicio.

Métodos de registro

Existen dos mecanismos para registrar un agente privado:

• Manual: Con este método, primero agrega un agente en la Consola de Administración para crear una entrada de agente. Luego proporciona los detalles del agente durante el proceso de instalación (en Windows y Linux), o con variables de entorno (para Docker).

• Automático: Este enfoque se utiliza principalmente para agentes en contenedores con plataformas como Docker y Kubernetes. Permite que un agente se cree y registre automáticamente en Harmony. Utiliza un archivo de configuración register.json o variables de entorno para proporcionar la información necesaria. Este enfoque es ideal para implementaciones automatizadas y de escalado automático.

Registro manual

Para registrar manualmente un agente, sigue estos pasos:

1. Ve a Consola de Administración > Agentes.

2. Agrega un grupo de agentes privado, o identifica uno existente, y luego agrega un nuevo agente privado a él.

3. Proporciona la información de registro. Cuándo lo hagas depende del tipo de host del agente:

   WindowsLinuxDocker

   Durante la instalación, la interfaz de usuario te solicita que selecciones a qué grupo de agentes unirte y qué agente registrar.

   Durante la configuración, el comando jitterbit-config te solicita que selecciones a qué grupo de agentes unirte y qué agente registrar. (Alternativamente, estos valores pueden proporcionarse como parámetros a jitterbit-config.)

   Al ejecutar el contenedor, utiliza las variables de entorno a continuación.

Registro manual de un agente privado de Docker utilizando variables de entorno

Para utilizar el registro manual con agentes privados en contenedores, establece valores para las siguientes variables de entorno y pásalos al contenedor:

docker run -d \
-e HARMONY_ORIGIN=https://na-east.jitterbit.com \
-e HARMONY_USERNAME=example@jbexample.com \
-e HARMONY_PASSWORD=P@55w0rd \
-e HARMONY_ORG_NAME="Example Org" \
-e HARMONY_AGENT_GROUP_NAME="Example Agent Group_Example Environment" \
-e HARMONY_AGENT_NAME=ExampleAgent \
jitterbit/agent

cat > agent.env <<EOF
HARMONY_ORIGIN=https://qa-green.jitterbit.com
HARMONY_USERNAME=example@jbexample.com
HARMONY_PASSWORD=J1tt_erb1t
HARMONY_ORG_NAME="JB Example Company"
HARMONY_AGENT_GROUP_NAME="Agent Group A_Default Environment"
HARMONY_AGENT_NAME=XMPL_3
ENABLE_JITTERBIT_METRICS=true
EOF
docker run -d --env-file=agent.env jitterbit/agent

Registro automático

Con el registro automático, hay dos formas de proporcionar información de registro: en un archivo register.json o como variables de entorno.

Registrar un agente privado de Docker usando el archivo register.json

Para registrar automáticamente un agente privado de Docker usando un archivo register.json, sigue estos pasos:

1. Crea un directorio y un archivo conf/register.json que contenga lo siguiente, con valores establecidos 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": "PREFIX",
       "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 privados.
   username	Tu nombre de usuario de cuenta de Harmony encriptado.
   password	Tu contraseña de cuenta de Harmony encriptada.
   agentNamePrefix	Un prefijo para el nombre del agente privado generado automáticamente.

   Ejemplo conf/register.json

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

2. Inicie el agente privado de Docker con el directorio conf montado en el directorio /conf del contenedor. (Vea Registro automático con el archivo register.json para un ejemplo.)

   Ejemplo

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

Debe usar un archivo credentials.txt o un archivo register.json. El agente privado no se iniciará si el directorio conf contiene ambos. El archivo register.json se convierte en un archivo credentials.txt y luego se elimina. En la versión 12.4 o posterior del agente de Docker, reiniciar el contenedor cuando deregisterAgentOnDrainstop=true está habilitado desregistra el agente existente y registra uno nuevo automáticamente. En versiones anteriores de Docker, credentials.txt permanece después de la desregistración y debe ser eliminado manualmente antes de que el agente pueda reiniciarse.

Para usar el archivo register.json en agentes privados de Linux no contenedorizados, elimine el archivo /opt/jitterbit/Resources/credentials.txt, cree un archivo /opt/jitterbit/Resources/register.json como se muestra arriba y luego reinicie el agente.

Registrar un agente privado de Docker usando variables de entorno

Para registrar automáticamente un agente privado de Docker usando variables de entorno, siga estos pasos:

1. Cree 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_ENCRYPTED_USERNAME=
   AUTO_REGISTER_ENCRYPTED_PASSWORD=
   

   Variable	Descripción del valor
   HARMONY_ORIGIN	La URL de inicio de sesión para su 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 privados.
   AUTO_REGISTER_ENCRYPTED_USERNAME	Su nombre de usuario de cuenta de Harmony encriptado.
   AUTO_REGISTER_ENCRYPTED_PASSWORD	Su contraseña de cuenta de Harmony encriptada.

   Ejemplo

   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=
   

2. Inicie el agente privado de Docker, pasando el archivo de variables de entorno usando la opción --env-file para docker run:

   Ejemplo

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

   Consejo

   Alternativamente, use la opción -e/--env para establecer variables de entorno individualmente.

Comparación de parámetros de register.json y variables de entorno

La siguiente tabla compara los parámetros utilizados en el archivo register.json con sus equivalentes en variables de entorno: