Upgrade von ADOGRC 13.6 oder 14.4 auf ADOGRC 15.0

Dieses Kapitel beschreibt, wie Sie eine bestehende ADOGRC-Installation von 13.6 oder 14.4 auf 15.0 aktualisieren.

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

Zur Vereinfachung des Migrationsprozesses stellt ADOGRC 15.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 ADOGRC-Dienste.

2. Sichern der deploymentspezifischen Konfigurationsdateien.

3. Aktualisieren der Datenbank mithilfe von aupgrade_product.

4. Bereitstellen von ADOGRC 15.0 in Kubernetes mithilfe der gesicherten Konfiguration.

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

Voraussetzungen

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

• Sie verwenden ADOGRC 13.6 oder 14.4.

• 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 die BOC OCI Registry hat.

• Sie verfügen über die erforderlichen Zugangsdaten für den Datenbankserver und über gültige Zugangsdaten für die BOC 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 ADOGRC 15.0.

• Sie kennen das Passwort des ADOGRC-Benutzers Admin.

Anwendungsbibliothek für ADOGRC 15.0

Sie können sofort loslegen, wenn Sie die Standardbibliothek verwenden, die mit ADOGRC ausgeliefert wird (die ADOGRC Standard Anwendungsbibliothek). Benutzerdefinierte Metamodelländerungen, die auf der Seite Eigenschaften in der ADOGRC 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 ADOGRC-Kundenbetreuer.

Info

Dieses Migrationsverfahren richtet sich an Systemadministratoren mit Zugriff auf die bestehende ADOGRC-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 ADOGRC 13.6 oder 14.4 verwendet werden.

Dienste stoppen

Beenden Sie alle laufenden ADOGRC-Dienste (Applikations-Server und Web-Server) und stellen Sie sicher, dass keine Benutzer mehr in ADOGRC 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 ADOGRC Applikations-Server (Service-Name z.B. "ADOGRC14.0-ADONIS17.0Service") 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 ADOGRC-Installation.

Frühere Versionen von ADOGRC speicherten deploymentspezifische Einstellungen in verschiedenen Konfigurationsdateien. In ADOGRC 15.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 ADOGRC 15.0-Bereitstellung benötigt.

ADOGRC Applikations-Server Konfiguration

• <ADONIS 13.x/14.x Applikations-Server>/conf/server.conf (enthält den Datenbanknamen, und Ports für Applikations-Server oder aworker-Prozesse).

• <ADONIS 13.x/14.x Applikations-Server>/conf/adoxx.conf (optional, wenn der Standardwert von Parametern geändert wurde)

• <ADONIS 13.x/14.x Applikations-Server>/conf/log.conf (optional, wenn der Standardwert von Parametern geändert wurde)

Apache Tomcat Konfiguration

• (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 ADOGRC 15.0-Bereitstellung.

Datenbank aktualisieren

Damit Sie Ihre bestehende Datenbank weiterhin mit ADOGRC 15.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 ADOGRC 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.

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 ADOGRC 15.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 ADOGRC Standard Anwendungsbibliothek) verwenden, sind keine weiteren Vorbereitungen erforderlich. Die Bibliotheksdatei ist bereits im Applikations-Server-Image von ADOGRC 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 ADOGRC-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 ADOGRC Standard 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 ADOGRC-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 BOC OCI Container Registry

Um sich an der BOC OCI Container Registry anmelden zu können, benötigen Sie die Zugangsdaten, welche Sie von Ihrem ADOGRC-Kundenbetreuer erhalten haben. Für den Zugriff auf das Image für den temporären Container zum Upgrade der Datenbank ist ein Login erforderlich.

Der einfachste Weg ist über folgenden Standard Docker-Befehl: docker login <boc-registry>. Sie werden nacheinander aufgefordert Ihre Access ID ("Benutzername") und Ihr Access Token ("Passwort") einzugeben.

Achtung

Dieser Befehl speichert die Zugangsdaten im Klartext in der Docker Konfigurationsdatei (Standard: ~/.docker/config.json). Falls Sie die Datenbank für ein neues Deployment ADOGRC erstellt haben, können Sie diese Datei verwenden für die Anmeldung von Helm an der BOC OCI Registry und das Erstellen eines ImagePullSecret. Bitte stellen Sie aber 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..

Datenbank-Upgrade durchführen

Nachdem Sie das Arbeitsverzeichnis, die Anwendungsbibliothek und die Datei config.json 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:/opt/data/config \
  <boc-registry> \
  --srcProductVersion "<16.x|17.x>" \
  --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 ADOGRC. 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

ADOGRC 15.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.

• <boc-registry>: Die BOC OCI Registry, von welcher Docker das Container Image herunterladen kann.

Die datenbankspezifischen Befehlsparameter sind:

• --srcProductVersion: Geben Sie die vollständige Version Ihrer bestehenden ADOGRC-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. ADOGRC 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 Datenbankadministrators: Das Passwort des Datenbankadministrators, dessen Benutzername mit --dbUser angegeben wurde.

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

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 ADOGRC 13.6 oder 14.4 verwendet werden.

ADOGRC 15.0 bereitstellen

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

Hinweis

Stellen Sie ADOGRC 15.0 gemäß den Anweisungen in ADOGRC 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 ADOGRC-Versionen auf die Umgebungsvariablen von ADOGRC 15.0 mappen.

Bisherige Installation entfernen

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

• Deinstallieren Sie den Applikations-Server von ADOGRC 13.6 oder 14.4 vom Windows-Server. Dies können Sie über die Systemsteuerung erledigen.

• Entfernen Sie die Webapplikation von ADOGRC 13.6 oder 14.4 aus Apache Tomcat.