Agent-Registrierung für private Jitterbit-Agenten

Einführung

Bevor ein privater Agent Integrationsprojektvorgänge verarbeiten kann, muss er sich bei einem Harmony-Server registrieren. Die erforderlichen Informationen umfassen die Harmony-Server-URL für die Region deiner Organisation, deine Harmony-Kontoanmeldedaten, den Namen der Agentgruppe für private Agenten, der der Agent beitreten soll, und den Namen des Agenten selbst. Um den Namen eines privaten Agenten zu erhalten, musst du zunächst einen über die Seite Agents der Management Console hinzufügen. Anschließend kannst du ihn als eines der erforderlichen Registrierungsinformationen während des Installationsschritts unter Windows (mit manueller Eingabe in das Installationsprogramm), des Konfigurationsschritts unter Linux (mit manueller Eingabe oder Parametern für jitterbit-config) oder beim Starten eines Docker-Containers (mit Umgebungsvariablen) angeben. Dieser Registrierungsansatz wird als manuelle Registrierung bezeichnet.

Wenn du containerisierte private Agenten automatisch bereitstellen und entfernen möchtest (beispielsweise mit Kubernetes), musst du die Funktion Auto-Registrierung für private Jitterbit-Agenten verwenden. Damit musst du keinen Agent über die Seite Agents der Management Console hinzufügen. Das System fügt einen privaten Agent automatisch zu einer benannten Agentgruppe hinzu, generiert einen Agentennamen und registriert ihn dann. Das System kann den privaten Agent optional auch deregistrieren und aus der Agentgruppe entfernen, wenn der Agent stoppt. (Es gibt einen Nachteil: Du kannst keinen Proxy mit automatischer Registrierung verwenden.)

Funktionsweise

Dieser Abschnitt bietet einen Überblick über die Schlüsselkonzepte und Einstellungen, die steuern, wie sich ein Agent registriert und deregistriert, und wie er sich nach einem Neustart verhält.

Die Datei credentials.txt

Wenn sich ein privater Agent zum ersten Mal bei Harmony registriert, erstellt er die Datei JITTERBIT_HOME/Resources/credentials.txt. Diese Datei enthält die verschlüsselten Anmeldedaten des Agenten und wird verwendet, um sich nach einem Neustart bei Harmony zu authentifizieren und erneut zu verbinden. Sie muss beibehalten werden, damit der Agent neu gestartet werden kann.

Agent-Verhalten beim Neustart

Der Parameter deregisterAgentOnDrainstop der Datei register.json steuert, was geschieht, wenn ein privater Agent stoppt oder neu gestartet wird. (Dieser Parameter kann in automatisierten Umgebungen auch als Umgebungsvariable übergeben werden.) Die zulässigen Werte sind true und false. Jeder Wert hat das folgende Verhalten:

• deregisterAgentOnDrainstop=false: Dies ist der Standardwert. Damit wird ein Agent nicht aus Harmony entfernt, wenn er stoppt, sondern bleibt in einem Stopped-Status aufgelistet.

  Beim Neustart des Agenten verwendet dieser seine vorhandene Datei credentials.txt, um sich erneut bei Harmony zu authentifizieren und den Betrieb fortzusetzen. Dies ist der empfohlene Ansatz für die meisten Anwendungsfälle, besonders wenn Agenten über geplante oder ungeplante Neustarts hinweg bestehen bleiben müssen.

• deregisterAgentOnDrainstop=true: Damit deregistriert sich der Agent aktiv selbst bei Harmony, wenn er stoppt, und wird aus der Agentenliste der Agentgruppe in der Management Console entfernt.

  Ab Docker-Agent-Version 12.4 deregistriert das Neustarten des Containers den vorhandenen Agent automatisch und registriert einen neuen, ohne dass eine manuelle Bereinigung erforderlich ist. Dies macht diese Konfiguration gut geeignet für Umgebungen mit automatischer Skalierung, in denen Agenten als austauschbar betrachtet werden und häufig erstellt und gelöscht werden. Beachte, dass das Neustarten des Jitterbit-Agent-Prozesses in einem laufenden Container (ohne Neustart des Containers selbst) immer noch dazu führt, dass sich der Agent deregistriert und aus Harmony entfernt wird, aber keine neue Registrierung auslöst. Zum Wiederherstellen musst du den Container neu starten.

  Bei Docker-Agenten mit früheren Versionen und bei Linux-Agenten bleibt credentials.txt nach der Deregistrierung bestehen und verursacht Authentifizierungsfehler beim Neustart. Zum Wiederherstellen musst du die veraltete Datei credentials.txt manuell entfernen, was eine neue Registrierung beim nächsten Start erzwingt.

Registrierungsmethoden

Es gibt zwei Mechanismen zum Registrieren eines privaten Agenten:

• Manuell: Bei dieser Methode fügen Sie zunächst einen Agenten in der Management Console hinzu, um einen Agenteneintrag zu erstellen. Anschließend geben Sie die Details des Agenten während des Installationsvorgangs (unter Windows und Linux) oder mit Umgebungsvariablen (für Docker) an.

• Automatisch: Dieser Ansatz wird hauptsächlich für containerisierte Agenten mit Plattformen wie Docker und Kubernetes verwendet. Er ermöglicht es einem Agenten, sich automatisch in Harmony zu erstellen und zu registrieren. Er verwendet eine register.json-Konfigurationsdatei oder Umgebungsvariablen, um die erforderlichen Informationen bereitzustellen. Dieser Ansatz ist ideal für automatisierte, automatisch skalierbare Bereitstellungen.

Manuelle Registrierung

Führen Sie diese Schritte aus, um einen Agenten manuell zu registrieren:

1. Gehen Sie zu Management Console > Agents.

2. Fügen Sie eine private Agentgruppe hinzu, oder identifizieren Sie eine vorhandene, und fügen Sie dann einen neuen privaten Agenten hinzu.

3. Geben Sie die Registrierungsinformationen an. Der Zeitpunkt hängt vom Agenten-Host-Typ ab:

   WindowsLinuxDocker

   Während der Installation werden Sie in der Benutzeroberfläche aufgefordert, auszuwählen, welcher Agentgruppe Sie beitreten möchten und welcher Agent registriert werden soll.

   Während der Konfiguration werden Sie vom jitterbit-config-Befehl aufgefordert, auszuwählen, welcher Agentgruppe Sie beitreten möchten und welcher Agent registriert werden soll. (Alternativ können diese Werte als Parameter für jitterbit-config bereitgestellt werden.)

   Verwenden Sie beim Ausführen des Containers die Umgebungsvariablen unten.

Manuelle Registrierung eines privaten Docker-Agenten mit Umgebungsvariablen

Um die manuelle Registrierung mit containerisierten privaten Agenten zu verwenden, legen Sie Werte für die folgenden Umgebungsvariablen fest und übergeben Sie sie an den Container:

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

Automatische Registrierung

Bei der automatischen Registrierung gibt es zwei Möglichkeiten, Registrierungsinformationen bereitzustellen: in einer register.json-Datei oder als Umgebungsvariablen.

Registrieren Sie einen privaten Docker-Agenten mit der register.json-Datei

Führen Sie diese Schritte aus, um einen privaten Docker-Agenten automatisch mit einer register.json-Datei zu registrieren:

1. Erstellen Sie ein Verzeichnis und eine Datei conf/register.json mit folgendem Inhalt, wobei die Werte gemäß der Tabelle unten festgelegt werden:

   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
   }
   

   Parameter	Wertbeschreibung
   cloudUrl	Die Login-URL für dein Harmony-Konto, https://REGION.jitterbit.com, wobei REGION einer der folgenden Werte ist: na-east, emea-west oder apac-southeast.
   agentGroupId	Die ID-Nummer der privaten Agent-Gruppe.
   username	Dein verschlüsselter Harmony-Kontoname.
   password	Dein verschlüsseltes Harmony-Kontokennwort.
   agentNamePrefix	Ein Präfix für den automatisch generierten Namen des privaten Agenten.

   Beispiel conf/register.json

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

2. Starten Sie den Docker-Private-Agent mit dem conf-Verzeichnis, das im /conf-Verzeichnis des Containers bereitgestellt wird. (Siehe Automatische Registrierung mit register.json-Datei für ein Beispiel.)

   Beispiel

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

Es muss entweder eine credentials.txt-Datei oder eine register.json-Datei verwendet werden. Der Private Agent startet nicht, wenn das conf-Verzeichnis beide Dateien enthält. Die register.json-Datei wird in eine credentials.txt-Datei konvertiert und anschließend gelöscht. Bei Docker Agent Version 12.4 oder später wird der Container beim Neustart mit aktiviertem deregisterAgentOnDrainstop=true automatisch deregistriert und ein neuer Agent registriert. Bei früheren Docker-Versionen bleibt credentials.txt nach der Deregistrierung bestehen und muss manuell gelöscht werden, bevor der Agent neu gestartet werden kann.

Um die register.json-Datei auf nicht containerisierten Linux-Private-Agents zu verwenden, löschen Sie die Datei /opt/jitterbit/Resources/credentials.txt, erstellen Sie eine /opt/jitterbit/Resources/register.json-Datei wie oben gezeigt, und starten Sie den Agent neu.

Docker-Private-Agent mit Umgebungsvariablen registrieren

Um einen Docker-Private-Agent automatisch mit Umgebungsvariablen zu registrieren, führen Sie diese Schritte aus:

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

   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=
   

   Variable	Wertbeschreibung
   HARMONY_ORIGIN	Die Login-URL für dein 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 privaten Agent-Gruppe.
   AUTO_REGISTER_ENCRYPTED_USERNAME	Dein verschlüsselter Harmony-Kontoname.
   AUTO_REGISTER_ENCRYPTED_PASSWORD	Dein verschlüsseltes Harmony-Kontokennwort.

   Example

   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. Starten Sie den Docker Private Agent und übergeben Sie die Umgebungsvariablendatei mit der Option --env-file für docker run:

   Example

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

   Tipp

   Alternativ können Sie die Option -e/--env verwenden, um Umgebungsvariablen einzeln festzulegen.

Vergleich von register.json-Parametern und Umgebungsvariablen

Die folgende Tabelle vergleicht die Parameter in der Datei register.json mit ihren entsprechenden Umgebungsvariablen: