Jitterbit private agents auf Docker

Einführung

Die Beispiele auf dieser Seite zeigen dir, wie du einen oder mehrere containerisierte private agents mit Jitterbit's Docker Hub Image ausführst. Der Abschnitt Health Check Service erklärt, wie du den Health Check Service auf einem laufenden Container verwendest, und der Abschnitt Troubleshooting-Ressourcen enthält Links zu häufigen Problemen und deren Lösungen.

Die folgenden Beispiele zeigen, wie du einen einzelnen Agent ausführst:

• Schnellstart

• Manuelle Registrierung mit Umgebungsvariablen

• Automatische Registrierung mit Umgebungsvariablen

• Automatische Registrierung mit register.json-Datei

Die folgenden Beispiele zeigen, wie du mehrere Agents ausführst:

• Mehrere Agents mit Docker Compose

• Mehrere Agents mit Helm und Kubernetes

Voraussetzungen

Du benötigst Folgendes für alle Beispiele auf dieser Seite:

• Docker

• Dein Harmony-Kontoname und Passwort.

• Dein Harmony-Organisationsname.

Zusätzlich benötigst du Folgendes, um die Beispiele mit mehreren Agents auszuführen:

• Docker Compose

• Helm

• Kubernetes

Schnellstart

Dieses Beispiel verwendet den jitterbit-config-Befehl, um die Registrierungsinformationen des Agents abzufragen, den jitterbit-Befehl, um den Agent zu starten, und tail -F, um die Agent-Protokolldatei zu warten und anzuzeigen.

1. Wähle Management Console > Agents aus dem Harmony Portal-Menü, dann füge eine private Agent-Gruppe hinzu, oder notiere dir den Namen und die ID einer vorhandenen.

2. Führe in einem Terminal diesen Befehl aus und antworte auf die Eingabeaufforderungen:

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

3. Um den Status deines Agents zu überprüfen, aktualisiere die Seite Management Console > Agents.

4. Drücke im Terminal Control+C, um den Agent zu stoppen, oder verwende den docker container stop-Befehl.

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

Manuelle Registrierung mit Umgebungsvariablen

Im Schnellstart-Beispiel musst du die Registrierungsinformationen des Agents bei Aufforderung eingeben. In diesem Beispiel werden diese Informationen mit Umgebungsvariablen bereitgestellt.

1. Füge einen Agent zu deiner Agent-Gruppe hinzu und notiere dir seinen Namen.

2. Erstelle eine Datei mit folgendem Inhalt, wobei die Werte gemäß der Tabelle unten gesetzt werden:

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

   Variable	Wertbeschreibung
   HARMONY_ORIGIN	Die Login-URL für dein Harmony-Konto, https://REGION.jitterbit.com, wobei REGION einer von na-east, emea-west oder apac-southeast ist.
   HARMONY_USERNAME	Dein Harmony-Kontoname.
   HARMONY_PASSWORD	Dein Harmony-Kontopasswort.
   HARMONY_ORG_NAME	Dein Harmony-Organisationsname.
   HARMONY_AGENT_GROUP_NAME	Der Agent-Gruppennamen und Umgebungsname, getrennt durch einen Unterstrich.
   HARMONY_AGENT_NAME	Der Agent-Name.

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

1. Führen Sie in einem Terminal diesen Befehl aus, um den Agent zu starten. Ersetzen Sie FILE durch den Namen der in Schritt 2 erstellten Datei:

   docker run --env-file FILE jitterbit/agent
   

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

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

4. (Optional) Löschen Sie den Agent über die Management Console. (Auf diese Weise gestartete Agenten werden beim Stoppen nicht automatisch entfernt.)

Automatische Registrierung mit Umgebungsvariablen

Das manuelle Registrierungsbeispiel hat zwei Nachteile: Sie müssen einen Agent manuell in der Management Console hinzufügen, und Ihre Harmony-Anmeldedaten sind für jeden sichtbar, der Zugriff auf das System hat.

Dieses Beispiel vermeidet beide Probleme. Es verwendet automatische Registrierung, um einen Agent automatisch zu Harmony hinzuzufügen. Die erforderlichen Registrierungswerte werden mithilfe von Umgebungsvariablen an den Container übergeben (die meisten davon haben das Präfix AUTO_REGISTER). 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 Anmeldedaten zu verschlüsseln. 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. Kopieren Sie die Werte für den nächsten Schritt (verwenden Sie die erste Zeile für AUTO_REGISTER_ENCRYPTED_USERNAME und die zweite Zeile für AUTO_REGISTER_ENCRYPTED_PASSWORD).

   3. Erstellen Sie eine Datei mit folgendem Inhalt und ersetzen Sie die Werte gemäß der Tabelle unten:

      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-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 Login-URL für Ihr Harmony-Konto: https://REGION.jitterbit.com, wobei REGION einer der folgenden Werte ist: na-east, emea-west oder apac-southeast.
   AUTO_REGISTER_AGENT_GROUP_ID	Die ID-Nummer der Agent-Gruppe.
   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ählen Sie Management Console > Access Tokens aus dem Harmony Portal-Menü und erstellen Sie ein Zugriffstoken. Wählen Sie die Umgebung, der Ihre private Agent-Gruppe zugeordnet ist, und setzen Sie den Umfang auf Agent Registration.

2. Kopieren Sie das Token zum Festlegen des Werts von AUTO_REGISTER_TOKEN im nächsten Schritt.

3. Erstellen Sie eine Datei mit folgendem Inhalt, wobei Sie die Werte gemäß der nachstehenden Tabelle ersetzen:

   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=
   

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

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

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

   Tipp

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

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

3. Um den Agent zu stoppen, verwenden Sie die Management Console, um ihn drain stop durchzuführen.

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

Automatische Registrierung mit 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/Passwort

   1. Führen Sie in einem Terminal den folgenden jitterbit-utils-Befehl aus, um Ihre Anmeldedaten zu verschlüsseln. 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 mit folgendem Inhalt, wobei Sie die Werte (hervorgehoben) gemäß der nachstehenden Tabelle festlegen:

      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 Login-URL für Ihr Harmony-Konto, https://REGION.jitterbit.com, wobei REGION einer der folgenden Werte ist: na-east, emea-west oder apac-southeast.
      agentGroupId	Die Agent-Gruppen-ID-Nummer.
      username	Die erste Zeile der Ausgabe von jitterbit-utils -e.
      password	Die zweite Zeile der Ausgabe von jitterbit-utils -e.

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

1. Führen Sie diesen Befehl aus, um den containerisierten privaten Agent zu starten:

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

   Tipp

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

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

3. Um den Agent zu stoppen, verwenden Sie die Management Console, um ihn drain stop durchzuführen.

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

Mehrere Agenten mit docker compose

In diesem Beispiel werden drei private Agenten mit identischen Konfigurationen in einer Agent-Gruppe ausgeführt.

1. Erstellen Sie eine Umgebungsvariablendatei wie oben gezeigt.

2. Erstellen Sie eine Datei docker-compose.yml mit folgendem Inhalt:

   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 in Schritt 1 erstellten Umgebungsvariablendatei.

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

   docker compose up -d
   

   Tipp

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

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

5. Führen Sie diesen Befehl aus, um die private Agent-Gruppe zu stoppen und ihre Container zu entfernen:

   docker compose down -d
   

Mehrere Agents mit helm und kubernetes

Jitterbit stellt ein Helm-Chart bereit, mit dem Sie einen Cluster von Agents mit Kubernetes ausführen können.

1. Starten Sie einen Kubernetes-Cluster.

   Tipp

   Wählen Sie in Docker Desktop Settings > Kubernetes > Enable Kubernetes aus.

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 vorherigen Beispielen verwenden.

3. Erstellen Sie eine Datei values.yaml mit folgendem Inhalt und ersetzen Sie die Werte gemäß der folgenden Tabelle:

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

   nameOverride: private-agent-group image: repository: jitterbit/agent tag: "latest" 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
   10	REGION	Ihre Harmony-Kontoregion (na-east, emea-west oder apac-southeast).
   11	GROUP_ID	Die Agent-Gruppen-ID-Nummer.
   12	ENCRYPTED_USERNAME	Die erste Zeile der Ausgabe aus Schritt 2.
   13	ENCRYPTED_PASSWORD	Die zweite Zeile der Ausgabe aus Schritt 2.

   Hinweis

   Wenn eine bestimmte Agent-Version erforderlich ist, ersetzen Sie das Tag "latest" in Zeile 5 durch ein Versions-Tag aus der Tags-Seite des Images. Beispiel: "12.5".

   Vorsicht

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

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 Agent-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 Cluster-Status zu überwachen, oder kubectl exec -it private-agent-group-0 -- curl localhost:46912/axis/v1/cdk/internal/members, um die Mitglieder des Listening-Service-Clusters 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-Agent zu aktualisieren, rufen Sie die neueste Version ab:

docker pull jitterbit/agent:latest

Umgebungsvariablen

Die folgenden Umgebungsvariablen werden vom Jitterbit Private Agent Docker-Image erkannt:

Ports

Beim Ausführen als Container können die folgenden Ports verfügbar gemacht werden:

Health-Check-Service

Um den Status eines privaten Agenten anzuzeigen, ordnen Sie Port 3000 im Container einem lokalen Port zu und senden Sie dann eine HTTP GET-Anfrage an localhost auf dem zugeordneten Port. Dies kann mithilfe der -p/--publish-Option in docker run-Befehlen oder durch Festlegen des ports-Schlüssels in docker compose-Befehlen erfolgen:

docker run -p 3000:3000 <other options> jitterbit/agent

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

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

curl -i localhost:3000

Die Antwort liegt im JSON-Format vor und enthält Felder, die den Gesamtstatus des privaten Agenten und den Status einzelner Services anzeigen (als true oder false):

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 lauten wie folgt:

Ressourcen zur Fehlerbehebung

Diese Abschnitte auf der Seite zur Fehlerbehebung können bei der Fehlerbehebung für private Agenten hilfreich sein, die auf Docker ausgeführt werden:

• Agent offline oder nicht erreichbar

• Agent zeigt unterschiedliche Versionen oder IP-Adressen an

• Verbindungs-, Websocket- und E/A-Fehler bei Jitterbit-Privatagenten mit Azure-VMs

• Docker-Fehlerbehebung

• Datadog-Agent kann nach Docker-Installation nicht gestartet werden