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 Solução de Problemas explica como usar o serviço de verificação de integridade em um contêiner em execução e apresenta alguns 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 o 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 o 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 é um dos 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 estã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 é 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_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 do agente.

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

6. Se AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP estiver definido como true, o agente é removido automaticamente quando parado. Caso contrário, exclua o agente no Console de Gerenciamento.

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, você pode se 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/senha

   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
      

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

$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
$003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=

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

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

        ??? tip "Exemplo conf/register.json"

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

=== "Token de acesso"
    1.  Selecione **Management Console > Access Tokens** no menu do Portal Harmony, em seguida, [crie um token de acesso](/pt/management-console/access-tokens/#create). Escolha o [ambiente](/pt/management-console/environments/) 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 `` na próxima etapa.

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

        ```json title="conf/register.json" hl_lines="2-4"
        {
            "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**.                                                                                             |

        ??? tip "Exemplo conf/register.json"

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

1. Execute este comando para iniciar o agente privado em contêiner:

   docker run --detach --name jitterbit-agent --rm --volume ./conf:/conf 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 Métrica de Agente.

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

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

4. Para parar o contêiner, encontre o ID do contêiner com docker ps, em seguida, use docker stop CONTAINER_ID.

5. Se deregisterAgentOnDrainstop estiver definido como true, o agente é removido automaticamente quando parado. Caso contrário, delete o agente no Console de Gerenciamento.

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

Jitterbit fornece um Helm chart 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

1. 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

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

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

1. Execute este comando para iniciar o cluster de agentes privados:

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

1. 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:

Solução de Problemas

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, faça 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 dos 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

Essas seções na página de Solução de Problemas podem ajudar ao solucionar problemas com agentes privados em execução 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.

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

• Solução de problemas do Docker.