Registro de agente para agentes privados Jitterbit

Introdução

Antes que um agente privado possa processar operações de projeto de integração, ele deve se registrar em um servidor Harmony. As informações necessárias para o registro incluem a URL do servidor Harmony para a região da sua organização, suas credenciais da conta Harmony, o nome do grupo de agentes privados ao qual ele deve se juntar e o nome do próprio agente. Para obter o nome de um agente privado, você deve primeiro adicionar um usando a página Agentes do Console de Gerenciamento. Você pode então fornecê-lo como uma das informações obrigatórias de registro durante o passo de instalação no Windows (com entrada manual no instalador), o passo de configuração no Linux (com entrada manual ou parâmetros para jitterbit-config), ou ao iniciar um contêiner Docker (com variáveis de ambiente). Essa abordagem de registro é conhecida como registro manual.

Se você deseja provisionar e descartar automaticamente agentes privados em contêiner (por exemplo, usando Kubernetes), deve usar o recurso de auto-registro do agente privado Jitterbit. Com isso, você não precisa adicionar um agente na página Agentes do Console de Gerenciamento. O sistema adiciona automaticamente um agente privado a um grupo de agentes nomeado, gera um nome de agente e, em seguida, o registra. O sistema também pode opcionalmente desregistrar e remover o agente privado do grupo de agentes quando o agente para. (Há uma desvantagem: você não pode usar um proxy com registro automático.)

Como funciona

Esta seção é uma visão geral dos conceitos e configurações principais que governam como um agente se registra e desregistra, e como ele se comporta após uma reinicialização.

O arquivo credentials.txt

Quando um agente privado se registra no Harmony pela primeira vez, ele cria o arquivo JITTERBIT_HOME/Resources/credentials.txt. Este arquivo contém as credenciais criptografadas do agente e é usado para autenticar e reconectar ao Harmony após uma reinicialização. Ele deve ser preservado para permitir que o agente reinicie.

Comportamento do agente na reinicialização

O parâmetro deregisterAgentOnDrainstop do arquivo register.json controla o que acontece quando um agente privado para ou reinicia. (Esse parâmetro também pode ser passado como uma variável de ambiente em ambientes automatizados.) Os valores permitidos são true e false. Cada valor tem o seguinte comportamento:

• deregisterAgentOnDrainstop=false: Este é o valor padrão. Com isso, um agente não é removido do Harmony quando para, mas permanece listado em um estado Parado.

  Quando o agente reinicia, ele usa seu arquivo existente credentials.txt para reautenticar-se com o Harmony e retomar as operações. Esta é a abordagem recomendada para a maioria dos casos de uso, especialmente quando você precisa que os agentes persistam entre reinicializações planejadas ou não planejadas.

• deregisterAgentOnDrainstop=true: Com isso, o agente se desregistra ativamente do Harmony quando é parado e é removido da lista de agentes do grupo de agentes no Console de Gerenciamento.

  A partir da versão 12.4 do agente Docker, reiniciar o contêiner desregistra o agente existente e registra um novo automaticamente, sem necessidade de limpeza manual. Isso torna essa configuração bem adequada para ambientes de autoescalonamento, onde os agentes são considerados descartáveis e são frequentemente criados e destruídos. Observe que reiniciar o processo do agente Jitterbit dentro de um contêiner em execução (sem reiniciar o contêiner em si) ainda faz com que o agente se desregistre, removendo-o do Harmony, mas não aciona um novo registro. Para recuperar, reinicie o contêiner.

  Em agentes Docker que executam versões anteriores e em agentes Linux, o credentials.txt permanece após a desregistração e causa falhas de autenticação na reinicialização do contêiner. Para recuperar, você deve remover manualmente o arquivo credentials.txt obsoleto, o que força um novo registro na próxima inicialização.

Métodos de registro

Existem dois mecanismos para registrar um agente privado:

• Manual: Com esse método, você primeiro adiciona um agente no Console de Gerenciamento para criar uma entrada de agente. Em seguida, você fornece os detalhes do agente durante o processo de instalação (no Windows e Linux) ou com variáveis de ambiente (para Docker).

• Automático: Esta abordagem é utilizada principalmente para agentes conteinerizados em plataformas como Docker e Kubernetes. Ela permite que um agente se crie e registre automaticamente no Harmony. Utiliza um arquivo de configuração register.json ou variáveis de ambiente para fornecer as informações necessárias. Esta abordagem é ideal para implantações automatizadas e com escalonamento automático.

Registro manual

Para registrar um agente manualmente, siga estas etapas:

1. Acesse Console de Gerenciamento > Agentes.

2. Adicione um grupo de agentes privado ou identifique um existente e, em seguida, adicione um novo agente privado a ele.

3. Forneça as informações de registro. O momento em que você faz isso depende do tipo de host do agente:

   WindowsLinuxDocker

   Durante a instalação, a interface do usuário solicita que você selecione a qual grupo de agentes se juntar e qual agente registrar.

   Durante a configuração, o comando jitterbit-config solicita que você selecione a qual grupo de agentes se juntar e qual agente registrar. (Alternativamente, esses valores podem ser fornecidos como parâmetros para jitterbit-config.)

   Ao executar o contêiner, utilize as variáveis de ambiente abaixo.

Registro manual de um agente privado Docker usando variáveis de ambiente

Para usar o registro manual com agentes privados conteinerizados, defina valores para as seguintes variáveis de ambiente e passe-os para o contêiner:

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

Com o registro automático, existem duas maneiras de fornecer informações de registro: em um arquivo register.json ou como variáveis de ambiente.

Registrar um agente privado Docker usando o arquivo register.json

Para registrar automaticamente um agente privado Docker usando um arquivo register.json, siga estas etapas:

1. Crie um diretório e um arquivo conf/register.json contendo o seguinte, com os valores definidos de acordo com a tabela abaixo:

   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	Descrição do valor
   cloudUrl	A URL de login para sua conta Harmony, https://REGION.jitterbit.com, onde REGION é uma das opções na-east, emea-west ou apac-southeast.
   agentGroupId	O número de identificação do grupo de agentes privados.
   username	Seu nome de usuário da conta Harmony criptografado.
   password	Sua senha da conta Harmony criptografada.
   agentNamePrefix	Um prefixo para o nome do agente privado gerado automaticamente.

   Exemplo 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 o agente privado do Docker com o diretório conf montado no diretório /conf do contêiner. (Veja Registro automático com o arquivo register.json para um exemplo.)

   Exemplo

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

Você deve usar um arquivo credentials.txt ou um arquivo register.json. O agente privado não iniciará se o diretório conf contiver ambos. O arquivo register.json é convertido em um arquivo credentials.txt e, em seguida, removido. Na versão 12.4 ou posterior do agente Docker, reiniciar o contêiner quando deregisterAgentOnDrainstop=true estiver habilitado desregistra o agente existente e registra um novo automaticamente. Em versões anteriores do Docker, o credentials.txt permanece após a desregistração e deve ser removido manualmente antes que o agente possa reiniciar.

Para usar o arquivo register.json em agentes privados Linux não conteinerizados, remova o arquivo /opt/jitterbit/Resources/credentials.txt, crie um arquivo /opt/jitterbit/Resources/register.json conforme mostrado acima e, em seguida, reinicie o agente.

Registrar um agente privado do Docker usando variáveis de ambiente

Para registrar automaticamente um agente privado do Docker usando variáveis de ambiente, siga estas etapas:

1. Crie um arquivo contendo o seguinte, com valores substituídos de acordo com a tabela abaixo:

   (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=
   

   Variável	Descrição do valor
   HARMONY_ORIGIN	A URL de login para sua conta Harmony, https://REGION.jitterbit.com, onde REGION é um dos na-east, emea-west ou apac-southeast.
   AUTO_REGISTER_AGENT_GROUP_ID	O número de identificação do grupo do agente privado.
   AUTO_REGISTER_ENCRYPTED_USERNAME	Seu nome de usuário da conta Harmony criptografado.
   AUTO_REGISTER_ENCRYPTED_PASSWORD	Sua senha da conta Harmony criptografada.

   Exemplo

   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 o agente privado do Docker, passando o arquivo de variáveis de ambiente usando a opção --env-file para docker run:

   Exemplo

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

   Dica

   Como alternativa, use a opção -e/--env para definir variáveis de ambiente individualmente.

Comparação de parâmetros register.json e variáveis de ambiente

A tabela a seguir compara os parâmetros usados no arquivo register.json com seus equivalentes em variáveis de ambiente: