Zum Hauptinhalt springen
Version: 21.0

Upgrade von ADOIT 17.0 – 17.7 oder 18.0 – 18.2 oder 19.0 auf ADOIT 21.0

Dieses Kapitel beschreibt, wie Sie eine bestehende ADOIT-Installation von 17.0 – 17.7 oder 18.0 – 18.2 oder 19.0 auf 21.0 aktualisieren.

Der Upgrade-Prozess unterscheidet sich erheblich von früheren ADOIT-Versionen. In früheren Versionen wurde der Applikations-Server unter Windows betrieben, während der Web-Server auf verschiedenen Plattformen bereitgestellt werden konnte. Ab ADOIT 21.0 werden sowohl der Applikations-Server als auch der Web-Server als containerisierte Services in einer Kubernetes-Umgebung bereitgestellt.

Zur Vereinfachung des Migrationsprozesses stellt ADOIT 21.0 das Management-Tool aupgrade_product bereit. Dieses Werkzeug aktualisiert eine bestehende Datenbank auf die neue Version und führt automatisch die erforderlichen Migrationsschritte aus, einschließlich der Aktualisierung des Datenbankschemas, des Updates der Anwendungsbibliothek, der Ausführung von Migrationsskripten sowie der Sicherung und Wiederherstellung von Komponenteneinstellungen.

Der Migrationsprozess umfasst folgende grundlegenden Schritte:

  1. Stoppen der bestehenden ADOIT-Dienste.

  2. Sichern der deploymentspezifischen Konfigurationsdateien.

  3. Aktualisieren der Datenbank mithilfe von aupgrade_product.

  4. Bereitstellen von ADOIT 21.0 in Kubernetes mithilfe der gesicherten Konfiguration.

  5. Überprüfen der Bereitstellung und Entfernen der alten Installation.

Voraussetzungen​

Bevor Sie ADOIT auf die Version 21.0 aktualisieren, stellen Sie sicher, dass folgende Voraussetzungen erfüllt sind:

  • Sie verwenden ADOIT 17.0 – 17.7 oder 18.0 – 18.2 oder 19.0 .

  • Ihre Datenbank wird auf einer unterstützten Version von Microsoft SQL Server oder PostgreSQL betrieben.

  • Sie verfügen über Zugriff auf einen Linux-Rechner oder das Windows Subsystem for Linux (WSL), auf dem Docker Engine installiert ist und der Netzwerkzugriff auf den Datenbankserver sowie Ihre OCI Registry hat.

  • Sie verfügen über die erforderlichen Zugangsdaten für den Datenbankserver und über gültige Zugangsdaten für Ihre OCI Registry.

  • Sie verfügen über Zugriff auf eine Kubernetes-Umgebung sowie die erforderlichen Administrationswerkzeuge, einschließlich kubectl und helm.

  • Die Zielumgebung erfüllt die Hardware-/Software-Anforderungen für ADOIT 21.0.

  • Sie kennen das Passwort des ADOIT-Benutzers Admin.

Anwendungsbibliothek für ADOIT 21.0​

Sie können sofort loslegen, wenn Sie die Standardbibliothek verwenden, die mit ADOIT ausgeliefert wird (die ArchiMate-Anwendungsbibliothek). Benutzerdefinierte Metamodelländerungen, die auf der Seite Eigenschaften in der ADOIT Administration vorgenommen wurden, beeinflussen das Update nicht – diese Änderungen bleiben erhalten.

Falls Sie eine gecustomizte Anwendungsbibliothek verwenden, beschaffen Sie vor Beginn des Upgrades die entsprechende aktualisierte Version von Ihrem ADOIT-Kundenbetreuer.

Info

Dieses Migrationsverfahren richtet sich an Systemadministratoren mit Zugriff auf die bestehende ADOIT-Installation, die Datenbank und die Ziel-Kubernetes-Umgebung.

Achtung

Erstellen Sie vor Beginn der Migration eine vollständige Sicherung Ihrer Datenbank. Nach erfolgreichem Abschluss des Datenbank-Upgrades kann die aktualisierte Datenbank nicht mehr mit ADOIT 18.0 – 18.2 oder 19.0 verwendet werden.

Dienste stoppen​

Beenden Sie alle laufenden ADOIT-Dienste (Applikations-Server und Web-Server) und stellen Sie sicher, dass keine Benutzer mehr in ADOIT angemeldet sind.

So stoppen Sie die Dienste (in Windows):

  • Öffnen Sie Dienste. Drücken Sie <Windows> + < R>, um das Feld Ausführen zu öffnen, geben Sie services.msc ein, und klicken Sie dann OK.

  • Stoppen Sie den ADOIT Applikations-Server (Service-Name z.B. "ADOITServer18.1Service") und den Apache Tomcat Web-Server (Service-Name z. B. "Tomcat10").

Deploymentspezifische Konfiguration sichern​

Bevor Sie die Datenbank aktualisieren, sichern Sie die deploymentspezifischen Konfigurationsdateien Ihrer bestehenden ADOIT-Installation.

Frühere Versionen von ADOIT speicherten deploymentspezifische Einstellungen in verschiedenen Konfigurationsdateien. In ADOIT 21.0 werden diese Einstellungen nicht mehr in lokalen Konfigurationsdateien verwaltet. Stattdessen werden sie während der Bereitstellung als Konfigurationswerte bereitgestellt.

Die gesicherten Konfigurationsdateien werden daher später bei der Konfiguration der neuen ADOIT 21.0-Bereitstellung benötigt.

ADOIT Applikations-Server Konfiguration​

  • <ADOIT 17.x/18.x/19.0 Applikations-Server>/conf/server.conf (enthält den Datenbanknamen, und Ports für Applikations-Server oder aworker-Prozesse).

  • <ADOIT 17.x/18.x/19.0 Applikations-Server>/conf/adoxx.conf (optional, wenn der Standardwert von Parametern geändert wurde)

  • <ADOIT 17.x/18.x/19.0 Applikations-Server>/conf/log.conf (optional, wenn der Standardwert von Parametern geändert wurde)

Apache Tomcat Konfiguration​
  • <Tomcat>/webapps/ADOIT17|8|9_x/adoxx_web.properties (enthält die IP-Adresse des Applikations-Servers und die Definition der aworker-Prozesse)
Info

Ändern Sie die gesicherten Dateien nicht. Sie dienen später als Referenz für die Übertragung deploymentspezifischer Einstellungen auf die ADOIT 21.0-Bereitstellung.

Datenbank aktualisieren​

Damit Sie Ihre bestehende Datenbank weiterhin mit ADOIT 21.0 verwenden können, müssen Sie sie mit dem Management-Tool aupgrade_product aktualisieren. Das Tool wird in einem kurzlebigen Docker-Container ausgeführt, der das Applikations-Server-Image von ADOIT verwendet.

Während des Upgrades führt aupgrade_product automatisch alle erforderlichen Migrationsschritte aus. Dazu gehören die Aktualisierung des Datenbankschemas, die Aktualisierung der Anwendungsbibliothek, die Ausführung der erforderlichen Migrationsskripte sowie die Sicherung und Wiederherstellung von Komponenteneinstellungen.

Bevor Sie das Upgrade ausführen, bereiten Sie das Arbeitsverzeichnis vor, stellen Sie die erforderliche Anwendungsbibliothek bereit und erstellen Sie die Konfigurationsdateien, wie in den folgenden Abschnitten beschrieben.

Anmeldedaten für die OCI Registry​

ADOIT-Container-Images und Helm-Charts werden über die BOC OCI Registry bereitgestellt. Sie bekommen vom BOC Support die notwendigen Anmeldedaten:

  • Registry-URL: Die URL der BOC OCI Registry

  • Access Identifier: Kennung für den Zugriff auf das Repository mit den ADOIT-Container-Images und Helm-Charts

  • Access Token: Authentifizierungstoken für den Zugriff auf die ADOIT-Container-Images und Helm-Charts

Hinweis

Wie Sie Zugriff auf die BOC OCI Registry erhalten, erfahren Sie unter Zugang Container Registry für containerisierte Deployments.

Verwenden Sie diese Anmeldedaten, um die benötigten ADOIT-Container-Images und Helm-Charts aus der BOC OCI Registry abzurufen und in Ihrer eigenen OCI Registry bereitzustellen.

Achtung

Die BOC OCI Registry dient als Quelle für den Bezug von ADOIT-Container-Images und Helm-Charts und unterliegt Download-Beschränkungen. Die BOC Group empfiehlt daher dringend, eine eigene OCI Registry zu verwenden, beispielsweise in Form einer Pull-Through-Caching-Registry oder einer lokalen Mirror-Registry.

Sofern nicht anders angegeben, setzen alle in diesem Guide beschriebenen Vorgehensweisen voraus, dass die benötigten ADOIT-Container-Images und Helm-Charts in Ihrer OCI Registry verfügbar sind.

Arbeitsverzeichnis vorbereiten​

Erstellen Sie auf dem Linux-Rechner oder in der WSL-Umgebung, von der aus Sie das Datenbank-Upgrade durchführen, ein Arbeitsverzeichnis. Dieses Verzeichnis enthält die für das Upgrade erforderlichen Konfigurationsdateien sowie die während des Upgrades erzeugten Log-Dateien.

Das folgende Beispiel erstellt das Arbeitsverzeichnis /opt/data/config sowie ein Verzeichnis für die erzeugten Log-Dateien:

mkdir -p /opt/data/config
mkdir -p /opt/data/logs
Hinweis

Um die Beispiele einfach zu halten, haben wir uns entschieden /opt/data als Arbeitsverzeichnis zu verwenden. Dieses Verzeichnis ist üblicherweise frei und erlaubt eine klare Angabe von absoluten Pfaden im Gegensatz zu einem Verzeichnis im Benutzerverzeichnis. Selbstverständlich können Sie jedes andere Verzeichnis verwenden, stellen Sie nur sicher, dass Sie bei Pfaden, welche sich auf Dateien im Container beziehen, den Pfad aus Sicht des Containers angeben.

Anwendungsbibliothek vorbereiten​

Für das Datenbank-Upgrade ist eine Anwendungsbibliothek für ADOIT 21.0 erforderlich. Während des Upgrades aktualisiert aupgrade_product die Anwendungsbibliothek in der Datenbank mithilfe der angegebenen Bibliotheksdatei.

Verwendung der Standardbibliothek​

Wenn Sie die Standardbibliothek (= die ArchiMate-Anwendungsbibliothek) verwenden, sind keine weiteren Vorbereitungen erforderlich. Die Bibliotheksdatei ist bereits im Applikations-Server-Image von ADOIT enthalten und befindet sich unter /aserver/data/default.axl.

Verwendung einer gecustomizten Anwendungsbibliothek​

Wenn Sie eine gecustomizte Anwendungsbibliothek verwenden, kopieren Sie die Bibliotheksdatei, die Sie von Ihrem ADOIT-Kundenbetreuer erhalten haben, in das im vorherigen Abschnitt erstellte Verzeichnis /opt/data/config.

Hinweis

Die Beispiele in diesem Leitfaden gehen davon aus, dass sich eine gecustomizte Bibliotheksdatei unter /opt/data/config befindet.

config.json erstellen​

Die Datei config.json steuert die von aupgrade_product durchgeführten Upgrade-Vorgänge. Sie legt fest, ob das Datenbankschema aktualisiert wird, ob Komponenteneinstellungen beibehalten werden und welche Anwendungsbibliothek in die aktualisierte Datenbank importiert wird.

Erstellen Sie die Datei config.json im Verzeichnis /opt/data/config mit folgendem Inhalt:

{
  "skipDbScripts": false,
  "beforePreprocessingScripts": [],
  "preprocessingScripts": [],
  "metamodelScripts": [],
  "migrateCompSettings": true,
  "applicationLibrary": "<bibliotheks-datei-name>",
  "additionalComponentSettings": [],
  "postprocessingScripts": []
}

Die wichtigsten Konfigurationsparameter sind:

  • skipDbScripts: Belassen Sie diesen Wert auf false, damit das Datenbankschema aktualisiert wird.

  • migrateCompSettings: Belassen Sie diesen Wert auf true, damit die Komponenteneinstellungen vor dem Upgrade automatisch exportiert und anschließend wieder importiert werden. Dadurch bleiben Ihre Anpassungen an bibliotheksspezifischen Funktionen erhalten.

  • applicationLibrary: Geben Sie die Anwendungsbibliothek an, die für das Datenbank-Upgrade verwendet werden soll. Wenn Sie die die Standardbibliothek (= die ArchiMate-Anwendungsbibliothek) verwenden, geben Sie /aserver/data/default.axl an. Wenn Sie eine gecustomizte Anwendungsbibliothek verwenden, geben Sie deren Dateinamen im Verzeichnis /opt/data/config an, zum Beispiel custom.axl.

Hinweis

Sofern Sie von Ihrem ADOIT-Kundenbetreuer nicht anders angewiesen werden, belassen Sie alle übrigen Konfigurationsparameter unverändert.

Hinweis

Die Logs, welche im Laufe des Updates geschrieben werden, werden mit den Rechten eines Benutzers im Container geschrieben, welcher auf dem Host-Sytem nicht existiert. Es ist daher notwendig die Berechtigungen des Log Verzeichnisses auf dem Host so zu setzen, dass alle Schreibberechtigungen erhalten. Diese können Sie mit dem Befehlt chmod o+w /opt/data/logs hinzufügen. Löschen Sie nach dem abgeschlossenen Update alle Dateien und Verzeichnisse, welche für das Update verwendet wurden, um das System wieder in einen sauberen Zustand zu versetzen.

Anmelden an der OCI Registry​

Melden Sie sich an Ihrer OCI Registry an, um auf das Image für den temporären Container zum Upgrade der Datenbank zugreifen zu können.

Der einfachste Weg ist über folgenden Standard-Docker-Befehl: docker login <container-registry-url>. Folgen Sie den Anweisungen und geben Sie die von Ihrer OCI Registry benötigten Zugangsdaten ein.

Achtung

Standardmäßig speichert dieser Befehl die Zugangsdaten in der Docker-Konfigurationsdatei (Standard: ~/.docker/config.json). Falls Sie ADOIT gerade bereitstellen, können Sie diese Datei für die Anmeldung von Helm an der Container-Registry und das Erstellen eines ImagePullSecret verwenden. Bitte stellen Sie jedoch sicher, dass diese Datei anschließend sicher gelöscht wird.

Hinweis

Bitte verwenden Sie Zugangsdaten nicht als Parameter im Befehl; die Bash-Historie speichert eine Liste an zuletzt eingegebenen Befehlen und würde damit indirekt die Zugangsdaten im Klartext anzeigen, wenn man die History aufruft.

Zugangsdaten des Datenbankbenutzers vorbereiten​

In ADOIT 21.0 können Sie den Datenbankbenutzer ADOxx nicht mehr mit dem vordefinierten Standardpasswort verwenden. Wenn Ihre bestehende Datenbank dieses Passwort verwendet, ändern Sie das Passwort des Benutzers ADOxx, bevor Sie fortfahren.

Sie müssen außerdem eine verschlüsselte Zeichenfolge mit den Zugangsdaten des Datenbankbenutzers (ADOxx oder ein individueller Datenbankbenutzer) erstellen. Sie benötigen diese Zeichenfolge im nächsten Schritt, wenn Sie das Datenbank-Upgrade durchführen. Sie benötigen sie später auch, wenn Sie ADOIT 21.0 deployen.

Eine Anleitung finden Sie unter Zugangsdaten des Datenbankbenutzers vorbereiten.

Datenbank-Upgrade durchführen​

Nachdem Sie das Arbeitsverzeichnis, die Anwendungsbibliothek, die Datei config.json und die Zugangsdaten des Datenbankbenutzers vorbereitet haben, führen Sie den folgenden Befehl auf dem Linux-Rechner oder in der WSL-Umgebung aus, um das Datenbank-Upgrade zu starten.

docker run -it --rm \
  --entrypoint /aserver/aupgrade_product \
  -v /opt/data/logs:/aserver/logs \
  -v /opt/data/config:/aserver/config \
  -e ADOXX_DBMS_CREDENTIALS="<verschlüsselte-zugangsdaten>" \
  <fully-qualified-image-name> \
  --srcProductVersion "<17.x|18.x|19.0>" \
  --id "<datenbank-name>" \
  --dbInstance "<datenbank-server>" \
  --dbType "<SQLServer|PostgreSQL>" \
  --dbPort "<datenbank-port>" \
  --dbUser "<datenbank-admin-name>" \
  --configRootPath "/opt/data" \
  --configName "config"

Der Befehl startet einen kurzlebigen Docker-Container unter Verwendung des Applikations-Server-Images von ADOIT. Der Container führt aupgrade_product aus, aktualisiert die Datenbank und wird nach Abschluss des Vorgangs automatisch beendet.

Info

Für Microsoft SQL Server verwendet aupgrade_product standardmäßig verschlüsselte Datenbankverbindungen entsprechend dem Standardverhalten von Microsoft ODBC Driver 18 for SQL Server. Wenn Ihr SQL Server keine verschlüsselten Verbindungen verwendet, geben Sie zusätzlich --encrypt "optional" an. Wenn Ihr SQL Server verschlüsselte Verbindungen mit einem vom Client nicht als vertrauenswürdig eingestuften Serverzertifikat verwendet, müssen Sie gegebenenfalls zusätzlich --trustservercertificate "yes" angeben. Für PostgreSQL sind diese Parameter nicht erforderlich.

Falls der Befehl aufgrund eines SSL- oder Zertifikatsvalidierungsfehlers fehlschlägt, überprüfen Sie die SQL Server-Verschlüsselungseinstellungen und passen Sie diese Parameter entsprechend an.

Hinweis

ADOIT 21.0 unterstützt keine Windows-Authentifizierung mehr für Microsoft SQL Server-Datenbanken. Bitte verwenden Sie stattdessen die SQL Server-Authentifizierung.

Die wichtigsten Bestandteile des Befehls sind:

  • --entrypoint /aserver/aupgrade_product: Führt das Upgrade-Tool direkt aus, anstatt den Applikations-Server zu starten.

  • -v /opt/data/logs:/aserver/logs: Speichert die während des Upgrades erzeugten Log-Dateien im Verzeichnis /opt/data/logs auf dem Host-System.

  • -v /opt/data/config:/opt/data/config: Stellt die Upgrade-Konfiguration, einschließlich config.json und gegebenenfalls einer gecustomizten Anwendungsbibliothek, für aupgrade_product innerhalb des Containers bereit.

  • -e ADOXX_DBMS_CREDENTIALS="<verschlüsselte-zugangsdaten>": Übergibt die im vorherigen Abschnitt erstellte verschlüsselte Zeichenfolge mit den Zugangsdaten des Datenbankbenutzers an aupgrade_product.

  • <fully-qualified-image-name>: Gibt den vollständig qualifizierten Namen des Applikations-Server-Images in Ihrer OCI Registry an.

Die datenbankspezifischen Befehlsparameter sind:

  • --srcProductVersion: Geben Sie die vollständige Version Ihrer bestehenden ADOIT-Installation einschließlich Major- und Minor-Version an.

  • --id: Der Name der zu aktualisierenden Datenbank.

  • --dbInstance: Der Hostname Ihres Datenbank-Servers.

  • --dbType: Der Typ Ihres Datenbankverwaltungssystems. Unterstützte Werte sind PostgreSQL und SQLServer.

  • --dbPort: Bei Standardinstallationen müssen Sie den Datenbank-Port nicht explizit angeben. ADOIT verwendet automatisch den Standard-Port 5432 für PostgreSQL bzw. 1433 für SQL Server-Standardinstanzen. Geben Sie diesen Parameter nur an, wenn Ihr Datenbank-Server einen benutzerdefinierten Port oder eine benannte SQL Server-Instanz verwendet.

  • --dbUser: Der Benutzername eines Datenbankadministrators mit ausreichenden Berechtigungen zur Aktualisierung des Datenbankschemas.

  • --configRootPath: Das übergeordnete Verzeichnis des Verzeichnisses config, das die Datei config.json enthält. In den Beispielen dieses Leitfadens ist dieser Wert /opt/data.

  • --configName: Der Name des Verzeichnisses, in welchem die Konfigurationsdatei mit dem selben Namen liegt, in unserem Fall config.

Nach dem Ausführen des Befehls fordert aupgrade_product Sie zur interaktiven Eingabe der folgenden Passwörter auf:

  • Passwort des Benutzers Admin: Das Passwort des ADOIT-Benutzers Admin.

  • Passwort des Datenbankadministrators: Das Passwort des Datenbankadministrators, dessen Benutzername mit --dbUser angegeben wurde.

Während des Upgrades führt aupgrade_product folgende Schritte aus:

  1. Aktualisiert das Datenbankschema.

  2. Exportiert die vorhandenen Komponenteneinstellungen.

  3. Aktualisiert die Anwendungsbibliothek in der Datenbank.

  4. Führt die erforderlichen Migrationsskripte aus.

  5. Importiert die Komponenteneinstellungen erneut.

Info

Nach erfolgreichem Abschluss des Datenbank-Upgrades kann die aktualisierte Datenbank nicht mehr mit ADOIT 17.0 – 17.7 oder 18.0 – 18.2 oder 19.0 verwendet werden.

ADOIT 21.0 bereitstellen​

Nachdem Sie die Datenbank erfolgreich aktualisiert haben, stellen Sie ADOIT 21.0 in Ihrer Kubernetes-Umgebung bereit.

Hinweis

Stellen Sie ADOIT 21.0 gemäß den Anweisungen in ADOIT bereitstellen bereit.

Stellen Sie während der Bereitstellung die deploymentspezifische Konfiguration Ihrer bisherigen Installation mithilfe der im Abschnitt Deploymentspezifische Konfiguration sichern gesicherten Konfigurationswerte wieder her.

Hinweis

Im Kapitel Deploymentspezifische Konfiguration auf Umgebungsvariablen mappen erfahren Sie, wie die Konfigurationsparameter früherer ADOIT-Versionen auf die Umgebungsvariablen von ADOIT 21.0 mappen.

Bisherige Installation entfernen​

Nachdem Sie ADOIT 21.0 erfolgreich bereitgestellt haben und sichergestellt haben, dass das migrierte System wie erwartet funktioniert, können Sie die bisherige ADOIT-Installation entfernen.

  • Deinstallieren Sie den Applikations-Server von ADOIT 17.0 – 17.7 oder 18.0 – 18.2 oder 19.0 vom Windows-Server. Dies können Sie über die Systemsteuerung erledigen.

  • Entfernen Sie die Webapplikation von ADOIT 17.0 – 17.7 oder 18.0 – 18.2 oder 19.0 aus Apache Tomcat.