Jitterbit private Agents auf Docker

Einführung

Die Beispiele auf dieser Seite zeigen, wie man einen oder mehrere containerisierte private Agents mit Jitterbits Docker Hub-Image ausführt. Der Abschnitt Health-Check-Dienst erklärt, wie man den Health-Check-Dienst auf einem laufenden Container verwendet, und der Abschnitt Fehlerbehebungsressourcen bietet einige Links zu häufigen Problemen und deren Lösungen.

Die folgenden Beispiele zeigen, wie man einen einzelnen Agenten ausführt:

• Schnellstart

• Manuelle Registrierung mit Umgebungsvariablen

• Automatische Registrierung mit Umgebungsvariablen

• Automatische Registrierung mit register.json-Datei

Die folgenden Beispiele zeigen, wie man mehrere Agenten ausführt:

• Mehrere Agenten mit Docker Compose

• Mehrere Agenten mit Helm und Kubernetes

Voraussetzungen

Für alle Beispiele auf dieser Seite müssen Sie Folgendes haben:

• Docker

• Ihren Benutzernamen und Ihr Passwort für das Harmony-Konto.

• Ihren Namen der Harmony-Organisation.

Zusätzlich müssen Sie Folgendes haben, um die Beispiele mit mehreren Agenten auszuführen:

• Docker Compose

• Helm

• Kubernetes

Schnellstart

Dieses Beispiel verwendet den jitterbit-config-Befehl, um nach den Registrierungsinformationen des Agents zu fragen, den jitterbit-Befehl, um den Agenten zu starten, und tail -F, um auf die Protokolldatei des Agents zu warten und diese anzuzeigen.

1. Wählen Sie Management Console > Agents im Menü des Harmony Portals und fügen Sie eine private Agentengruppe hinzu oder notieren Sie den Namen und die ID einer vorhandenen Gruppe.

2. Führen Sie in einem Terminal diesen Befehl aus und antworten Sie auf die Eingabeaufforderungen:

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

3. Um den Status Ihres Agents zu überprüfen, aktualisieren Sie die Seite Management Console > Agents.

4. Drücken Sie im Terminal Control+C, um den Agenten zu stoppen, oder verwenden Sie den docker container stop Befehl.

5. (Optional) Löschen Sie den Agenten über die Management Console. (Agents, die auf diese Weise gestartet werden, werden beim Stoppen nicht automatisch entfernt.)

Manuelle Registrierung mit Umgebungsvariablen

Im Schnellstartbeispiel müssen Sie die Registrierungsinformationen des Agents eingeben, wenn Sie dazu aufgefordert werden. In diesem Beispiel werden diese Informationen über Umgebungsvariablen bereitgestellt.

1. Fügen Sie einen Agenten zu Ihrer Agentengruppe hinzu und notieren Sie seinen Namen.

2. Erstellen Sie eine Datei mit folgendem Inhalt, wobei die Werte gemäß der Tabelle unten festgelegt werden:

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

   Variable	Wertbeschreibung
   HARMONY_ORIGIN	Die Anmelde-URL für Ihr Harmony-Konto, https://REGION.jitterbit.com, wobei REGION eines von na-east, emea-west oder apac-southeast ist.
   HARMONY_USERNAME	Ihr Benutzername für das Harmony-Konto.
   HARMONY_PASSWORD	Ihr Passwort für das Harmony-Konto.
   HARMONY_ORG_NAME	Ihr Name der Harmony-Organisation.
   HARMONY_AGENT_GROUP_NAME	Der Name der Agentengruppe und der Name der Umgebung, durch einen Unterstrich getrennt.
   HARMONY_AGENT_NAME	Der Name des Agents.

   Beispiel

   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. Führen Sie in einem Terminal diesen Befehl aus, um den Agenten zu starten, wobei Sie FILE durch den Namen der in Schritt 2 erstellten Datei ersetzen:

   docker run --env-file FILE jitterbit/agent
   

4. Um den Status Ihres Agenten zu überprüfen, aktualisieren Sie die Seite Management Console > Agents.

5. Drücken Sie im Terminal Control+C, um den Agenten zu stoppen, oder verwenden Sie den Befehl docker container stop.

6. (Optional) Löschen Sie den Agenten über die Management Console. (Agenten, die auf diese Weise gestartet werden, werden beim Stoppen nicht automatisch entfernt.)

Automatische Registrierung mit Umgebungsvariablen

Es gibt zwei Nachteile beim Beispiel der manuellen Registrierung: Sie müssen einen Agenten manuell in der Management Console hinzufügen, und Ihre Harmony-Anmeldeinformationen sind für jeden sichtbar, der Zugriff auf das System hat.

Dieses Beispiel vermeidet beide Probleme. Es verwendet die automatische Registrierung, um einen Agenten automatisch zu Harmony hinzuzufügen. Die erforderlichen Registrierungswerte werden über Umgebungsvariablen in den Container übergeben (von denen die meisten mit AUTO_REGISTER beginnen). Für die Authentifizierung können Sie entweder ein verschlüsseltes Benutzername/Passwort-Paar oder ein Zugriffstoken verwenden. (Beide Methoden werden hier gezeigt.)

1. Wählen Sie eine Authentifizierungsmethode:

   Benutzername/PasswortZugriffstoken

   1. Führen Sie in einem Terminal den folgenden jitterbit-utils Befehl aus, um Ihre Anmeldeinformationen zu verschlüsseln, wobei Sie USERNAME und PASSWORD durch Ihren Harmony-Benutzernamen und Ihr Passwort ersetzen:

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

      Beispielbefehl

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

      Beispielausgabe

      $00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
      $003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=
      

   2. Kopiere die Werte für die Verwendung im nächsten Schritt (verwende die erste Zeile für AUTO_REGISTER_ENCRYPTED_USERNAME und die zweite Zeile für AUTO_REGISTER_ENCRYPTED_PASSWORD).

   3. Erstelle eine Datei, die Folgendes enthält, wobei die Werte gemäß der Tabelle unten ersetzt werden:

      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=
      

   Beispiel für eine Umgebungsvariablendatei

   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	Wertbeschreibung
   HARMONY_ORIGIN	Die Anmelde-URL für dein Harmony-Konto, https://REGION.jitterbit.com, wobei REGION eines von na-east, emea-west oder apac-southeast ist.
   AUTO_REGISTER_AGENT_GROUP_ID	Die ID-Nummer der Agentengruppe.
   AUTO_REGISTER_ENCRYPTED_USERNAME	Die erste Zeile der Ausgabe von jitterbit-utils -e.
   AUTO_REGISTER_ENCRYPTED_PASSWORD	Die zweite Zeile der Ausgabe von jitterbit-utils -e.

   1. Wähle Management Console > Zugriffstoken aus dem Menü des Harmony-Portals und erstelle ein Zugriffstoken. Wähle die Umgebung, mit der deine private Agentengruppe verbunden ist, und setze den Umfang auf Agentenregistrierung.

   2. Kopiere das Token, um den Wert von AUTO_REGISTER_TOKEN im nächsten Schritt festzulegen.

   3. Erstellen Sie eine Datei mit den folgenden Inhalten, wobei die Werte gemäß der Tabelle unten ersetzt werden:

      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=
      

   Beispiel für eine Umgebungsvariablendatei

   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	Wertbeschreibung
   HARMONY_ORIGIN	Die Anmeldungs-URL für Ihr Harmony-Konto, https://REGION.jitterbit.com, wobei REGION eines von na-east, emea-west oder apac-southeast ist.
   AUTO_REGISTER_AGENT_GROUP_ID	Die ID-Nummer der Agentengruppe.
   AUTO_REGISTER_TOKEN	Zugriffstoken mit dem Geltungsbereich Agent Registration.

2. Führen Sie diesen Befehl aus, um den containerisierten privaten Agenten zu starten, wobei FILE der Name der in den vorherigen Schritt erstellten Datei ist:

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

   Hinweis

   Um Jitterbit native Observability mit dieser Methode zu aktivieren, fügen Sie AUTO_REGISTER_AGENT_METRICS_TOKEN zur Liste der Umgebungsvariablen hinzu, die an den Container übergeben werden. Der Wert ist ein Zugriffstoken mit dem Geltungsbereich Agent Metric.

3. Um den Status Ihres Agenten zu überprüfen, aktualisieren Sie die Seite Management Console > Agents.

4. Um den Agenten zu stoppen, verwenden Sie die Management Console, um ihn drain stop.

5. Um den Container zu stoppen, finden Sie die Container-ID mit docker ps und verwenden Sie dann docker container stop CONTAINER_ID.

Automatische Registrierung mit der register.json-Datei

Eine Alternative zur Verwendung von Umgebungsvariablen besteht darin, die erforderlichen Werte in einer register.json-Datei festzulegen. Diese Datei kann in einem conf-Unterverzeichnis platziert werden, von wo aus der Agent-Container sie liest und zur Registrierung des Agents verwendet. Wie im vorherigen Beispiel können Sie sich entweder mit einem Benutzernamen und Passwort oder mit einem Zugriffstoken authentifizieren.

1. Wählen Sie eine Authentifizierungsmethode:

   Benutzername/PasswortZugriffstoken

   1. Führen Sie in einem Terminal den folgenden jitterbit-utils-Befehl aus, um Ihre Anmeldeinformationen zu verschlüsseln, und ersetzen Sie USERNAME und PASSWORD durch Ihren Harmony-Benutzernamen und Ihr Passwort:

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

      Beispielbefehl

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

      Beispielausgabe

      $00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
      $003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=
      

   2. Erstellen Sie ein Verzeichnis und eine Datei conf/register.json, die Folgendes enthält, wobei die Werte (hervorgehoben) gemäß der Tabelle unten festgelegt sind:

      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
      }
      

      Parameter	Wertbeschreibung
      cloudUrl	Die Anmelde-URL für Ihr Harmony-Konto, https://REGION.jitterbit.com, wobei REGION eines von na-east, emea-west oder apac-southeast ist.
      agentGroupId	Die ID-Nummer der Agentengruppe.
      username	Die erste Zeile der Ausgabe von jitterbit-utils -e.
      password	Die zweite Zeile der Ausgabe von jitterbit-utils -e.

      Beispiel conf/register.json

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

   1. Wählen Sie Management Console > Zugriffstoken im Menü des Harmony Portals und erstellen Sie ein Zugriffstoken. Wählen Sie die Umgebung, mit der Ihre private Agentengruppe verbunden ist, und setzen Sie den Scope auf Agentenregistrierung.

   2. Kopieren Sie das Token, um den Wert von ACCESS_TOKEN im nächsten Schritt festzulegen.

   3. Erstellen Sie ein Verzeichnis und eine Datei conf/register.json, die Folgendes enthält, wobei die Werte (hervorgehoben) gemäß der Tabelle unten festgelegt sind:

      conf/register.json

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

      Parameter	Wertbeschreibung
      cloudUrl	Die Anmelde-URL für Ihr Harmony-Konto, https://REGION.jitterbit.com, wobei REGION eines von na-east, emea-west oder apac-southeast ist.
      agentGroupId	Die ID-Nummer der Agentengruppe.
      token	Zugriffstoken mit dem Scope Agentenregistrierung.

      Beispiel 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. Führen Sie diesen Befehl aus, um den containerisierten privaten Agenten zu starten:

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

   Tipp

   Um Jitterbit native Observability mit dieser Methode zu aktivieren, fügen Sie den Parameter agentMetricsToken zur Datei register.json hinzu. Der Wert ist ein Zugriffstoken mit dem Scope Agent Metric.

3. Um den Status Ihres Agents zu überprüfen, aktualisieren Sie die Seite Management Console > Agents.

4. Um den Agenten zu stoppen, verwenden Sie die Management Console, um ihn drain stop zu setzen.

5. Um den Container zu stoppen, finden Sie die Container-ID mit docker ps, und verwenden Sie dann docker stop CONTAINER_ID.

Mehrere Agenten mit docker compose

In diesem Beispiel laufen drei private Agenten mit identischen Konfigurationen in einer Agentengruppe.

1. Erstellen Sie eine Datei mit Umgebungsvariablen wie oben beschrieben.

2. Erstellen Sie eine Datei docker-compose.yml, die Folgendes enthält:

   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: Der Name der Umgebungsvariablen-Datei, die in Schritt 1 erstellt wurde.

3. Führen Sie diesen Befehl aus, um die private Agentengruppe zu starten:

   docker compose up -d
   

   Tipp

   Führen Sie docker compose logs -f aus, um die Protokolldateien aller Agenten zu überwachen, oder docker stats, um die Ressourcennutzung jedes Agenten zu überwachen.

4. Um den Status Ihres Agenten zu überprüfen, aktualisieren Sie die Seite Management Console > Agents.

5. Führen Sie diesen Befehl aus, um die private Agentengruppe zu stoppen und deren Container zu entfernen:

   docker compose down -d
   

Mehrere Agenten mit helm und kubernetes

Jitterbit bietet ein Helm-Chart, das Sie verwenden können, um einen Cluster von Agenten mit Kubernetes auszuführen.

1. Starten Sie einen Kubernetes-Cluster.

   Tipp

   Wählen Sie in Docker Desktop Einstellungen > Kubernetes > Kubernetes aktivieren.

2. Führen Sie diesen Befehl aus, um Ihren Harmony-Benutzernamen und Ihr Passwort zu verschlüsseln:

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

   Tipp

   Sie können die gleiche Ausgabe aus den vorherigen Beispielen verwenden.

3. Erstellen Sie eine Datei values.yaml, die Folgendes enthält, wobei die Werte gemäß der Tabelle unten ersetzt werden:

   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

   Zeile	Wert	Ersetzen durch
   9	REGION	Ihre Harmony-Kontoregion (na-east, emea-west oder apac-southeast).
   10	GROUP_ID	Die ID-Nummer der Agentengruppe.
   11	ENCRYPTED_USERNAME	Die erste Zeile der Ausgabe aus Schritt 2.
   12	ENCRYPTED_PASSWORD	Die zweite Zeile der Ausgabe aus Schritt 2.

   Vorsicht

   Diese Konfiguration legt fest, dass Kubernetes mindestens 3 und höchstens 5 Agenten ausführen soll, wenn der Horizontal Pod Autoscaler aktiv ist, oder 4 Agenten, wenn dies nicht der Fall ist. Da jeder Docker-Privatagent ungefähr 0,25 CPU-Kerne und 2 GB Speicher benötigt, sollten Sie überprüfen, ob die Spezifikationen Ihres Hosts diese Anzahl von Agenten unterstützen können. Sie können auch ein resources-Element hinzufügen, um die Grenzen der Ressourcennutzung festzulegen. Weitere Details finden Sie im Beispiel value.yml-Datei von Jitterbit.

4. Führen Sie diese Befehle aus, um das Helm-Chart-Repository hinzuzufügen und zu aktualisieren:

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

5. Führen Sie diesen Befehl aus, um den privaten Agenten-Cluster zu starten:

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

   Tipp

   Führen Sie kubectl -n default get pods --watch aus, um den Clusterstatus zu überwachen, oder kubectl exec -it private-agent-group-0 -- curl localhost:46912/axis/v1/cdk/internal/members, um die Mitglieder des Clusters des lauschernden Dienstes aufzulisten.

6. Führen Sie diesen Befehl aus, um den Cluster zu stoppen und die Container zu entfernen:

   helm uninstall private-agent-group
   

Upgrade

Um einen Docker-Agenten zu aktualisieren, ziehen Sie die neueste Version:

docker pull jitterbit/agent:latest

Umgebungsvariablen

Die folgenden Umgebungsvariablen werden vom Docker-Image des Jitterbit-Privatagenten erkannt:

Ports

Beim Betrieb als Container können die folgenden Ports freigegeben werden:

Gesundheitsprüfungsdienst

Um den Status eines privaten Agents zu sehen, mappen Sie Port 3000 im Container auf einen lokalen Port und senden dann eine HTTP GET-Anfrage an localhost auf dem gemappten Port. Dies kann mit der -p/--publish-Option in docker run-Befehlen oder durch Setzen des ports-Schlüssels in docker compose erfolgen:

docker run -p 3000:3000 <andere Optionen> jitterbit/agent

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

Um den Dienst aufzurufen, verwenden Sie einen Webbrowser oder curl, um eine Anfrage an Port 3000 zu stellen:

curl -i localhost:3000

Die Antwort ist im JSON-Format, mit Feldern, die den Gesamtstatus des privaten Agents (als true oder false) und den Status einzelner Dienste anzeigen:

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

Die HTTP-Antwortcodes sind wie folgt:

Fehlersuche-Ressourcen

Diese Abschnitte auf der Fehlerbehebungsseite können bei der Fehlersuche von privaten Agents, die auf Docker laufen, hilfreich sein:

• Jitterbit privater Agent läuft nicht oder ist gestoppt oder nicht erreichbar.

• Jitterbit privater Agent zeigt unterschiedliche Versionen oder IPs an.

• Verbindungs-, Websocket- und I/O-Fehler bei Jitterbit privaten Agents, die Azure-VMs verwenden.

• Docker-Fehlerbehebung.