Agentes privados Jitterbit no Docker

Introdução

Os exemplos nesta página mostram como executar um ou mais agentes privados em contêiner usando a imagem do Docker hub da Jitterbit. A seção Serviço de verificação de saúde explica como usar o serviço de verificação de saúde em um contêiner em execução, e a seção Recursos de solução de problemas fornece alguns links para problemas comuns e suas soluções.

Os seguintes exemplos mostram como executar um único agente:

• Início rápido

• Registro manual com variáveis de ambiente

• Registro automático com variáveis de ambiente

• Registro automático com arquivo register.json

Os seguintes exemplos mostram como executar múltiplos agentes:

• Múltiplos agentes com Docker compose

• Múltiplos agentes com Helm e Kubernetes

Pré-requisitos

Você deve ter o seguinte para todos os exemplos nesta página:

• Docker

• Seu nome de usuário e senha da conta Harmony.

• O nome da sua organização Harmony.

Além disso, você deve ter o seguinte para executar os exemplos de múltiplos agentes:

• Docker Compose

• Helm

• Kubernetes

Início rápido

Este exemplo usa o comando jitterbit-config para solicitar as informações de registro do agente, o comando jitterbit para iniciar o agente e tail -F para aguardar e mostrar o arquivo de log do agente.

1. Selecione Console de Gerenciamento > Agentes no menu do Portal Harmony, em seguida, adicione um grupo de agentes privado, ou anote o nome e ID de um existente.

2. Em um terminal, execute este comando e responda aos prompts:

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

3. Para verificar o status do seu agente, atualize a página Console de Gerenciamento > Agentes.

4. No terminal, pressione Control+C para parar o agente, ou use o comando docker container stop.

5. (Opcional) Exclua o agente usando o Console de Gerenciamento. (Agentes iniciados dessa forma não são removidos automaticamente quando parados.)

Registro manual com variáveis de ambiente

No exemplo de início rápido, você deve inserir as informações de registro do agente quando solicitado. Neste exemplo, essas informações são fornecidas usando variáveis de ambiente.

1. Adicione um agente ao seu grupo de agentes e anote seu nome.

2. Crie um arquivo contendo o seguinte, com valores definidos de acordo com a tabela abaixo:

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

   Variável	Descrição do Valor
   HARMONY_ORIGIN	A URL de login para sua conta Harmony, https://REGION.jitterbit.com, onde REGION é uma das na-east, emea-west ou apac-southeast.
   HARMONY_USERNAME	Seu nome de usuário da conta Harmony.
   HARMONY_PASSWORD	Sua senha da conta Harmony.
   HARMONY_ORG_NAME	O nome da sua organização Harmony.
   HARMONY_AGENT_GROUP_NAME	O nome do grupo de agentes e o nome do ambiente, separados por um sublinhado.
   HARMONY_AGENT_NAME	O nome do agente.

   Exemplo

   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. Em um terminal, execute este comando para iniciar o agente, substituindo FILE pelo nome do arquivo criado na etapa 2:

   docker run --env-file FILE jitterbit/agent
   

4. Para verificar o status do seu agente, atualize a página Console de Gerenciamento > Agentes.

5. No terminal, pressione Control+C para parar o agente, ou use o comando docker container stop.

6. (Opcional) Exclua o agente usando o Console de Gerenciamento. (Agentes iniciados dessa forma não são removidos automaticamente quando parados.)

Registro automático com variáveis de ambiente

Existem duas desvantagens no exemplo de registro manual: você deve adicionar manualmente um agente no Console de Gerenciamento, e suas credenciais do Harmony são visíveis para qualquer pessoa com acesso ao sistema.

Este exemplo evita ambos os problemas. Ele usa registro automático para adicionar automaticamente um agente ao Harmony. Os valores de registro necessários são passados para o contêiner usando variáveis de ambiente (a maioria das quais é precedida por AUTO_REGISTER). Para autenticação, você pode usar um par de nome de usuário/senha criptografado ou um token de acesso. (Ambos os métodos são mostrados aqui.)

1. Escolha um método de autenticação:

   Nome de usuário/senhaToken de acesso

   1. Em um terminal, execute o seguinte comando jitterbit-utils para criptografar suas credenciais, substituindo USERNAME e PASSWORD pelo seu nome de usuário e senha do Harmony:

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

      Comando de exemplo

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

      Saída de exemplo

      $00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
      $003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=
      

   2. Copie os valores para usar na próxima etapa (usando a primeira linha para AUTO_REGISTER_ENCRYPTED_USERNAME e a segunda linha para AUTO_REGISTER_ENCRYPTED_PASSWORD).

   3. Crie um arquivo contendo o seguinte, com os 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=
      

   Exemplo de arquivo de variável de ambiente

   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=
   

   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 de agentes.
   AUTO_REGISTER_ENCRYPTED_USERNAME	A primeira linha da saída de jitterbit-utils -e.
   AUTO_REGISTER_ENCRYPTED_PASSWORD	A segunda linha da saída de jitterbit-utils -e.

   1. Selecione Console de Gerenciamento > Tokens de Acesso no menu do Portal Harmony, em seguida, crie um token de acesso. Escolha o ambiente com o qual seu grupo de agentes privado está associado e defina o escopo como Registro de Agente.

   2. Copie o token para definir o valor de AUTO_REGISTER_TOKEN na próxima etapa.

   3. 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_TOKEN=
      

   Exemplo de arquivo de variável de ambiente

   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
   

   Variável	Descrição do valor
   HARMONY_ORIGIN	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.
   AUTO_REGISTER_AGENT_GROUP_ID	O número de identificação do grupo de agentes.
   AUTO_REGISTER_TOKEN	Token de acesso com escopo Registro de Agente.

2. Execute este comando para iniciar o agente privado em contêiner, onde FILE é o nome do arquivo criado na etapa anterior:

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

   Dica

   Para habilitar a observabilidade nativa do Jitterbit com este método, adicione AUTO_REGISTER_AGENT_METRICS_TOKEN à lista de variáveis de ambiente passadas para o contêiner. O valor é um token de acesso com escopo Métrica do Agente.

3. Para verificar o status do seu agente, atualize a página Console de Gerenciamento > Agentes.

4. Para parar o agente, use o Console de Gerenciamento para parar a drenagem.

5. Para parar o contêiner, encontre o ID do contêiner com docker ps, e depois use docker container stop CONTAINER_ID.

Registro automático com o arquivo register.json

Uma alternativa ao uso de variáveis de ambiente é definir os valores necessários em um arquivo register.json. Este arquivo pode ser colocado em um subdiretório conf, de onde o contêiner do agente o lê e o utiliza para registrar o agente. Assim como no exemplo anterior, é possível autenticar usando um nome de usuário e senha, ou um token de acesso.

1. Escolha um método de autenticação:

   Nome de usuário/senhaToken de acesso

   1. Em um terminal, execute o seguinte comando jitterbit-utils para criptografar suas credenciais, substituindo USERNAME e PASSWORD pelo seu nome de usuário e senha do Harmony:

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

      Comando de exemplo

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

      Saída de exemplo

      $00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
      $003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=
      

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

      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	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 do agente.
      username	A primeira linha da saída do jitterbit-utils -e.
      password	A segunda linha da saída do jitterbit-utils -e.

      Exemplo conf/register.json

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

   1. Selecione Console de Gerenciamento > Tokens de Acesso no menu do Portal Harmony, em seguida, crie um token de acesso. Escolha o ambiente com o qual seu grupo de agentes privados está associado e defina o escopo como Registro de Agente.

   2. Copie o token para definir o valor de ACCESS_TOKEN na próxima etapa.

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

      conf/register.json

      {
          "cloudUrl": "https://REGION.jitterbit.com",
          "agentGroupId": GROUP_ID,
          "token": "ACCESS_TOKEN",
          "agentNamePrefix": "test",
          "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 é um dos na-east, emea-west ou apac-southeast.
      agentGroupId	O número de identificação do grupo de agentes.
      token	Token de acesso com escopo Registro de Agente.

      Exemplo 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. Execute este comando para iniciar o agente privado em contêiner:

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

   Dica

   Para habilitar a observabilidade nativa do Jitterbit com este método, adicione o parâmetro agentMetricsToken ao arquivo register.json. O valor é um token de acesso com escopo Agent Metric.

3. Para verificar o status do seu agente, atualize a página Console de Gerenciamento > Agentes.

4. Para parar o agente, use o Console de Gerenciamento para drain stop.

5. Para parar o contêiner, encontre o ID do contêiner com docker ps, e então use docker stop CONTAINER_ID.

Múltiplos agentes com docker compose

Neste exemplo, três agentes privados com configurações idênticas são executados em um grupo de agentes.

1. Crie um arquivo de variáveis de ambiente conforme mostrado acima.

2. Crie um arquivo docker-compose.yml contendo o seguinte:

   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: O nome do arquivo de variáveis de ambiente criado na etapa 1.

3. Execute este comando para iniciar o grupo de agentes privados:

   docker compose up -d
   

   Dica

   Execute docker compose logs -f para acompanhar os arquivos de log de todos os agentes, ou docker stats para monitorar o uso de recursos de cada agente.

4. Para verificar o status do seu agente, atualize a página Console de Gerenciamento > Agentes.

5. Execute este comando para parar o grupo de agentes privados e remover seus contêineres:

   docker compose down -d
   

Múltiplos agentes com helm e kubernetes

O Jitterbit fornece um chart do Helm que você pode usar para executar um cluster de agentes usando Kubernetes.

1. Inicie um cluster Kubernetes.

   Dica

   No Docker Desktop, selecione Configurações > Kubernetes > Habilitar Kubernetes.

2. Execute este comando para criptografar seu nome de usuário e senha do Harmony:

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

   Dica

   Você pode usar a mesma saída dos exemplos anteriores.

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

   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

   Linha	Valor	Substituir por
   9	REGION	A região da sua conta Harmony (na-east, emea-west ou apac-southeast).
   10	GROUP_ID	O número de identificação do grupo de agentes.
   11	ENCRYPTED_USERNAME	A primeira linha da saída do passo 2.
   12	ENCRYPTED_PASSWORD	A segunda linha da saída do passo 2.

   Cuidado

   Esta configuração especifica que o Kubernetes deve executar pelo menos 3 e no máximo 5 agentes se o Horizontal Pod Autoscaler estiver ativo, ou 4 agentes se não estiver. Como cada agente privado do Docker precisa de aproximadamente 0,25 núcleos de CPU e 2 GB de memória, você deve verificar se as especificações do seu host podem suportar esse número de agentes. Você também pode adicionar um elemento resources para definir os limites de utilização de recursos. Para mais detalhes, veja o exemplo do Jitterbit value.yml file.

4. Execute estes comandos para adicionar e atualizar o repositório do Helm:

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

5. Execute este comando para iniciar o cluster do agente privado:

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

   Dica

   Execute kubectl -n default get pods --watch para monitorar o status do cluster, ou kubectl exec -it private-agent-group-0 -- curl localhost:46912/axis/v1/cdk/internal/members para listar os membros do cluster do serviço em escuta.

6. Execute este comando para parar o cluster e remover os contêineres:

   helm uninstall private-agent-group
   

Variáveis de ambiente

As seguintes variáveis de ambiente são reconhecidas pela imagem Docker do agente privado Jitterbit:

Portas

Ao executar como um contêiner, as seguintes portas podem ser expostas:

Serviço de verificação de saúde

Para ver o status de um agente privado, mapeie a porta 3000 no contêiner para uma porta local e, em seguida, emita uma solicitação HTTP GET para localhost na porta mapeada. Você pode fazer isso usando a opção -p/--publish nos comandos docker run, ou definindo a chave ports no docker compose:

docker run -p 3000:3000 <outras opções> jitterbit/agent

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

Para chamar o serviço, use um navegador da web ou curl para fazer uma solicitação na porta 3000:

curl -i localhost:3000

A resposta está no formato JSON, com campos indicando (como true ou false) o status geral do agente privado e o status de serviços individuais:

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}}

Os códigos de resposta HTTP são os seguintes:

Recursos de solução de problemas

Essas seções na página de Solução de Problemas podem ajudar ao solucionar problemas de agentes privados executando no Docker:

• Agente privado Jitterbit não está em execução ou está parado ou inacessível.

• Agente privado Jitterbit mostrando versões ou IPs diferentes.

• Conexão, websocket e erros de I/O em agentes privados Jitterbit usando VMs do Azure.

• Solução de problemas do Docker.