Migration der Profil-Backups in den Nested-Modus

Dieser Artikel richtet sich an Plattform-Administratoren und Entwickler. Er beschreibt die Migration eines Clusters in den Nested-Modus des Profil-Backup-Handlers. Er erklärt außerdem die Auswirkungen dieser Umstellung im Betrieb.

Die Plattform stellt die Ablage der Profil-Backups auf eine verschachtelte Verzeichnisstruktur um. Der Nested-Modus verteilt die Backup-Dateien auf 100 Unterverzeichnisse pro Bucket. Parallele Schreibvorgänge laufen dadurch deutlich schneller. Ein Fallback-Mechanismus hält Jobs aus der alten Struktur weiterhin lesbar. Sie aktivieren den Modus über eine JVM-Systemeigenschaft. Eine manuelle Datenmigration ist nicht erforderlich.

Hintergrund: Verzeichnissperren bei gemeinsam genutztem Backup-Speicher

Die Verzeichnisstruktur für Profil-Backups wurde überarbeitet. Die bisherige Struktur legt alle Backup-Dateien direkt im Profil-Verzeichnis ab. Optional erfolgt eine Aufteilung in 50.000er-Buckets.

Als Übergang führt die Plattform einen Fallback-Modus ein. Neue Jobs schreibt die Plattform in der neuen, verschachtelten Struktur. Bestehende Jobs in der alten Struktur bleiben über den Fallback-Mechanismus weiterhin lesbar.

 HINWEIS:

In Hochverfügbarkeits- und Load-Balancing-Umgebungen liegt das Backup-Root-Verzeichnis auf einem gemeinsam genutzten Cloud-Dateisystem, zum Beispiel AWS EFS. Mehrere Cluster-Knoten schreiben dort gleichzeitig. Netzwerk-Dateisysteme serialisieren Änderungen an Verzeichniseinträgen. Jeder Schreib-, Umbenennungs- oder Löschvorgang blockiert das gesamte Verzeichnis kurzzeitig. Bei vielen parallelen Threads entsteht dadurch eine Verzeichnissperren-Konkurrenz. Die alte Struktur skaliert deshalb kaum über einen einzelnen Thread hinaus.

Die neue Struktur verteilt die Dateien auf 100 Unterverzeichnisse. Das Unterverzeichnis ergibt sich aus Jobnummer % 100. Parallele Schreibvorgänge landen dadurch in unterschiedlichen Unterverzeichnissen. Sie konkurrieren nicht mehr um dieselbe Sperre. Benchmarks mit ProfileBackupHandlerPerfMain zeigen bei 50 Threads einen bis zu 8,5-fachen Durchsatz gegenüber der alten Struktur.

Lobster empfiehlt die Migration für alle HA- und Load-Balancing-Umgebungen mit gemeinsam genutztem Backup-Root und hoher paralleler Schreiblast. Einzelplatz-Installationen auf lokalem Speicher sind von diesem Problem nicht betroffen.

Verzeichnisstrukturen im Vergleich

Bisherige Struktur (Legacy)

Das Bucketing aktivieren Sie auf zwei Wegen. Entweder setzen Sie die JVM-Systemeigenschaft hub.datawizard.subdirs. Oder Sie setzen MultipleBackupSubDirs in ./etc/startup.xml. Sind beide Werte gesetzt und widersprechen sich, gilt der Wert aus der startup.xml.

ENV-Dateien liegen immer neben den Job-Dateien: ENV_<jobnr>. Die Bucket-Berechnung erfolgt in 50.000er-Schritten: Jobs 1 bis 50.000 landen in Bucket 50000, Jobs 50.001 bis 100.000 in Bucket 100000, und so weiter.

Neue Struktur (Nested)

Die neue Struktur ist immer zwei Ebenen tief. Das Unterverzeichnis ergibt sich aus dem Rest der Division der Jobnummer durch 100.

.../datawizard/backup/
  └── <profil-id>/
      └── 50000/
          ├── 00/
          │   ├── ENV_25000    (25000 % 100 = 0)
          │   └── Job_25000
          └── 08/
              ├── ENV_25008
              └── Job_25008

Direkt nach der Migration existieren beide Strukturen parallel: ältere Jobs in der bisherigen Struktur, neue Jobs in der Nested-Struktur.

Folgende Ordner liegen direkt unter dem Backup-Root und gehören zu keinem Profil. Beide Strukturen ignorieren sie: commonqueue, ci, oftp, queue, reference, rules, suspend, temp, tmp, unknown, payload, unresolved.

Betriebsmodi über die JVM-Systemeigenschaft

Sie wählen die Implementierung beim Plattform-Start über die JVM-Systemeigenschaft profile.backup.handler.implementation.

 HINWEIS:

Bei den Werten wird zwischen Groß-/Kleinschreibung nicht unterschieden. Ein unbekannter, leerer oder ungültiger Wert führt immer zum Fallback auf legacy. Verwenden Sie ausschließlich legacy oder nested.

Bei einem ungültigen Wert protokolliert die Plattform beim Start einen Setup-Fehler in services/error.log:

SYSTEM:DATAWIZARD:SETUP Unknown value for -Dprofile.backup.handler.implementation='<wert>' — falling back to 'legacy'. Valid values: legacy, nested, nested_only

Diese Meldung weist auf eine Fehlkonfiguration hin. Korrigieren Sie den Wert, bevor Sie das System produktiv betreiben.

Verhalten des Fallback-Handlers

Der Fallback-Handler überprüft jeden Job auf seine Struktur. Das Ergebnis speichert er im Arbeitsspeicher, um wiederholte Dateisystemzugriffe zu vermeiden. Payload-Datei und ENV-Datei eines Jobs liest die Plattform immer aus derselben Struktur.

• Schreiben: Neue Jobs schreibt die Plattform ausschließlich in die neue Struktur. Ein fehlgeschlagener Schreibvorgang wird als Fehler gemeldet.

• Lesen: Die Plattform prüft zuerst die neue Struktur. Findet sie den Job dort nicht, greift sie auf die alte Struktur zurück.

• Löschen: Ein rekursiver Löschvorgang entfernt Dateien aus beiden Strukturen, da sie im selben Profil-Verzeichnis liegen.

Migration durchführen

Voraussetzungen

• Das Backup-Root-Verzeichnis ist beschreibbar. Die Plattform legt die Unterverzeichnisse der neuen Struktur beim ersten Schreibvorgang automatisch an.

• Bestehende Dateien der alten Struktur bleiben unverändert. Eine manuelle Migration ist nicht erforderlich.

Vorgehen

1. Öffnen Sie ./bin/platform.json und fügen Sie den Parameter im Array jvmArgs hinzu: -Dprofile.backup.handler.implementation=nested. Nutzen Sie noch keinen Application Wrapper, setzen Sie den Parameter stattdessen in ./etc/wrapper.conf, ./bin/hub.bat oder ./bin/execute.sh, je nach Startmechanismus. Details finden Sie unter Lobster Application Wrapper.

2. Starten Sie die Plattform neu.

3. Ab diesem Zeitpunkt speichert die Plattform alle neuen Jobs in der Nested-Struktur.

Migration überwachen

Sie können den Fortschritt der Migration über Insight-Daten beobachten. Das Attribut fallbackRatio gibt den Anteil der Jobs an, die noch aus der alten Struktur stammen.

<profileBackupFilesStorageMode mode="nested" fallbackRatio="0.0" />

Im Legacy-Modus zeigt die Plattform stattdessen:

<profileBackupFilesStorageMode mode="legacy" />

Notfall: Rückkehr zum Legacy-Modus

In Ausnahmefällen können Sie den Backup-Handler wieder auf den Legacy-Modus zurückstellen, müssen dabei jedoch die Auswirkungen auf bereits neu gespeicherte Jobs beachten.

 WICHTIG: 

Jobs, die bereits in der Nested-Struktur gespeichert wurden, sind nach einer Rückkehr zu legacy für die Plattform nicht mehr erreichbar. Die Dateien bleiben auf dem Datenträger erhalten. Der Legacy-Handler kennt die neue Verzeichnisstruktur aber nicht.

Eine Rückkehr zu legacy ist nur sicher, wenn seit der Umstellung keine neuen Jobs verarbeitet wurden. Stellen Sie andernfalls sicher, dass betroffene Jobs vorher in der alten Struktur verfügbar sind, oder akzeptieren Sie den Datenverlust.

Setzen Sie den Parameter an derselben Stelle wie beim Umstieg auf den Nested-Modus (siehe Migration durchführen), doch dieses Mal mit dem Wert legacy:

-Dprofile.backup.handler.implementation=legacy

Auswirkungen auf den Betrieb im Überblick

Die folgende Übersicht zeigt die wichtigsten Unterschiede zwischen dem bisherigen Legacy-Verhalten und dem neuen Fallback-Modus.