Daten von Redis zu einer Key Value Store-Instanz migrieren

In diesem Tutorial lernen Sie, wie Sie Daten von einer bestehenden STACKIT Redis-Instanz zu einer Ziel-Key Value Store-Instanz migrieren.

Anforderungen

• Valkey CLI / Redis CLI: (CLI-Client für Datenbankverbindungen)
• gunzip: (Kommandozeilen-Werkzeug zum Entpacken von Dateien)
• openssl: (Toolkit für SSL- und TLS-Protokolle zur sicheren Netzwerkkommunikation)
• CF CLI Version 7: (CLI für Cloud Foundry zur Vereinfachung der Anwendungs- und Space-Verwaltung)

Vor der Migration

Tools installieren

Um eine reibungslose Migration zu gewährleisten, installieren Sie zunächst die in den Anforderungen aufgeführten Tools. Wir empfehlen, die offizielle Dokumentation des jeweiligen Tools für die Installation zu konsultieren. Je nach Betriebssystem können Sie Paketmanager wie apt für Linux, homebrew für macOS oder choco (Chocolatey) für Windows nutzen, um den Installationsprozess zu vereinfachen.

Überprüfen Sie nach der Installation die Funktionsfähigkeit jedes Tools, indem Sie einen Versionsbefehl aufrufen (z. B. valkey-cli -v).

Quelldatenbank isolieren

Es wird dringend empfohlen, die Quell-Redis-Instanz vor Beginn der Migration zu isolieren. Dies verhindert potenzielle Dateninkonsistenzen, die entstehen können, wenn die Datenbank während der Migration gleichzeitig neue Daten empfängt.

Das Ziel besteht darin, Client-Verbindungen zu unterbinden, um sicherzustellen, dass während des Migrationsprozesses keine zusätzlichen Daten in die Quellinstanz geschrieben werden. Dies erreichen Sie, indem Sie alle Anwendungen von Ihrer Quell-Redis-Instanz trennen (Unbind/Disconnect).

Backup der Quelldatenbank erstellen

Wir empfehlen dringend, eine manuelle Sicherung Ihrer Quelldatenbank als Ausfallsicherung für den Fall eines unerwarteten Datenverlusts auszulösen. Dieses Backup muss sicher aufbewahrt werden, bis die Konsistenz der Zieldatenbank nach der Migration bestätigt wurde.

1. Öffnen Sie das Service Dashboard, um manuell eine Sicherung Ihrer Quell-Redis-Instanz auszulösen. Stellen Sie sicher, dass Sie ein Verschlüsselungspasswort festgelegt und sicher gespeichert haben.

2. Laden Sie die neueste Sicherung aus dem Redis Service Dashboard herunter und bewahren Sie sie sicher auf.

Weitere Details finden Sie in der Sicherungsdokumentation für Ihre Quellinstanz.

Ziel-Key Value Store-Datenbank in STACKIT erstellen

Erstellen Sie eine leere Key Value Store-Instanz, die als Ziel für die Datenmigration dient.

Erstellen Sie eine Zielinstanz mit denselben oder höheren Kapazitäten (RAM/Speicher/Knoten) wie Ihre Quellinstanz, um sicherzustellen, dass sie den Datensatz verarbeiten kann.

Fügen Sie erst dann Daten in die Zielinstanz ein, wenn die Migration und die Konsistenzprüfungen vollständig abgeschlossen sind.

Anmeldedaten erstellen

Erstellen Sie Anmeldedaten für Ihre Ziel-Key Value Store-Datenbank über das STACKIT Portal oder mit dem CLI-Befehl stackit key-value-store credentials create. Wenn Sie die Cloud Foundry-Laufzeitumgebung nutzen, können Sie diese über die CF CLI generieren.

Datenbank-Verbindungszeichenfolgen

STACKIT Portal

1. Navigieren Sie zu Key Value Store im STACKIT Portal.
2. Wählen Sie Ihre Instanz aus und gehen Sie zur Übersicht.
3. Wählen Sie in der Seitenleiste Anmeldeinformationen.
4. Klicken Sie auf den Eintrag des Dienstschlüssels, den Sie anzeigen möchten, um Ihre Verbindungszeichenfolgen abzurufen.

Cloud Foundry CLI

1. Wählen Sie Ihre gewünschte Organisation und Ihren Space aus:

   cf target -o [ihr-organisationsname] -s [ihr-spacename]

2. Listen Sie die Dienste auf, um Ihre Ziel-Key Value Store-Instanz (appcloud-keyvalue8) zu finden:

   cf services

3. Erstellen Sie einen Dienstschlüssel für Ihren Datendienst und zeigen Sie ihn an:

   cf create-service-key [ihr-key-value-instanzname] [ihr-schlüsselname]
   cf service-key [ihr-key-value-instanzname] [ihr-schlüsselname]

Formatieren Sie die erhaltenen Dienstschlüssel in Datenbank-Verbindungszeichenfolgen um, falls sie nicht bereits im URI-Format bereitgestellt werden

Format der Verbindungszeichenfolge: rediss://[benutzername]:[passwort]@[hosts-fqdn]:[port]

Verwenden Sie sowohl für die Quell- als auch für die Zieldatenbank immer den exakten Wert von host aus Ihren Anmeldedaten.

Backend-Host für die Migration abrufen

Dieser Schritt ist nur erforderlich, wenn Sie zu einem öffentlich erreichbaren STACKIT Key Value Store Datendienst migrieren, der über das Portal erstellt wurde.

Der Befehl MIGRATE erfordert eine direkte TCP-Verbindung von der Quell- zur Zieldatenbank. Die Verwendung öffentlich erreichbarer Frontend-Hosts (zum Beispiel kvd297348-main-3.data.eu01.onstackit.cloud) als Ziel führt dazu, dass die Migration fehlschlägt. Stattdessen müssen Sie den Backend-Host für die Zieldatenbank verwenden.

Sie müssen keinen Cloud Foundry Runtime Service bestellen, um diesen Schritt auszuführen; Sie müssen sich lediglich an der CF CLI anmelden, um die interne Route zu extrahieren.

1. Melden Sie sich mit der CF CLI an. Lesen Sie Interaktion mit Cloud Foundry für detaillierte Anweisungen.
2. Wählen Sie Ihre Cloud Foundry-Organisation aus. Eine typische Organisation folgt dem Namensschema: stackit_portal_prod_[portal_projektname]_id.

   cf target -o stackit_portal_prod_mein_cloud_4eFgBq5P

3. Listen Sie Ihre Datendienst-Instanzen mit cf services auf, um Ihre Zieldatenbank anhand des Namens zu identifizieren. Die korrekte Backend-Instanz enthält -internal als Namenssuffix.
4. Erstellen Sie einen Dienstschlüssel für das interne Backend:

   cf create-service-key [ziel-instanzname-internal] [ihr-schlüsselname]

5. Zeigen Sie den Dienstschlüssel an und speichern Sie die JSON-Ausgabe, da der hier angegebene Host Ihre tatsächliche Backend-Route ist:

   cf service-key [ziel-instanzname-internal] [ihr-schlüsselname]

Umgang mit TLS-Zertifikaten

Je nachdem, wo Ihre Instanzen gehostet werden, benötigen Sie ein spezifisches CA-Zertifikat (Certificate Authority), um während der Migration Ihre sichere TLS-Verbindung aufzubauen.

Öffentlich erreichbare Dienste (STACKIT Portal)

Wenn Ihre Instanz öffentliche Zertifikate nutzt, die von SwissSign ausgestellt wurden:

• Öffentliche Projekte: Moderne Betriebssysteme vertrauen SwissSign von Haus aus. In der Regel können Sie sich verbinden, indem Sie das Flag --tls verwenden. Wenn Ihr System diesem nicht vertraut, laden Sie die SwissSign Root- und Intermediate-CAs aus dem SwissSign-Repositoryherunter und übergeben Sie diese über das Flag --cacert.
• Interne Projekte (Schwarz): Unternehmensgeräte vertrauen den internen Netzwerkzertifikaten standardmäßig.

Cloud Foundry-Laufzeitumgebung

Wenn Ihre Datenbank innerhalb der Cloud Foundry-Laufzeitumgebung läuft, verwendet sie eine private Zertifikatsstelle (Private CA). Sie müssen dieses Zertifikat aus Ihrem Dienstschlüssel extrahieren, um eine Verbindung herzustellen. Suchen Sie das Feld cacrt in der JSON-Ausgabe, ersetzen Sie die \n-Zeichen durch tatsächliche Zeilenumbrüche und speichern Sie die Ausgabe in einer Datei namens cf_ca.pem. Übergeben Sie diese mit --cacert /pfad/zu/cf_ca.pem.

Migrationsprozess

Hauptstrategie: Migration über den Befehl MIGRATE

Die Hauptstrategie zur Migration des gesamten Datensatzes von der Quelle zum Ziel basiert auf dem Befehl MIGRATE. Über die CLI verbinden wir uns mit der bestehenden Instanz und leiten die Schlüssel direkt an die Zielinstanz weiter.

Basierend auf internen Tests dauert die Migration von 1 GB durchschnittlich etwa 50 Sekunden, dies hängt jedoch von der Netzwerklatenz und der Struktur des Datensatzes ab. Planen Sie den Migrationsprozess entsprechend.

Wenn Ihre Quelldatenbank Schlüssel mit Namen enthält, die Sonderzeichen (zum Beispiel Zeilenumbrüche) aufweisen, kann dieser spezifische CLI-Pipe-Migrationsprozess fehlschlagen. Verwenden Sie in diesem Fall die unten stehende alternative Skript-Strategie.

Da Key Value Store einen Benutzernamen und ein Passwort erfordert, verwendet der Zielbefehl AUTH2. Führen Sie den folgenden Befehl aus und ersetzen Sie die Platzhalter durch Ihre tatsächlichen Werte:

valkey-cli -u "[quell-db-verbindungszeichenfolge]" -n [db-nr] \
--tls --sni [quell-frontend-hosts-fqdn] \
--cacert [/pfad/zu/ca-zertifikat.pem] --raw KEYS '*' | \
xargs valkey-cli -u "[quell-db-verbindungszeichenfolge]" -n [db-nr] \
--tls --sni [quell-frontend-hosts-fqdn] --cacert [/pfad/zu/ca-zertifikat.pem] \
MIGRATE [ziel-backend-hosts-fqdn] [ziel-backend-port] "" [db-nr] [timeout] \
COPY AUTH2 [ziel-benutzername] [ziel-passwort] KEYS > migration-output-checker.txt

Erklärung des Befehls

• Quell-CLI: Wir verbinden uns mit der Quelle (-u "[quell-db-verbindungszeichenfolge]") und verwenden --raw KEYS '*', um eine Rohliste aller Schlüssel auszugeben.
• xargs: Nimmt die Liste der Schlüssel von der Quelle entgegen und übergibt sie an den nächsten Befehl.
• Ziel-CLI (MIGRATE): Wir verbinden uns erneut mit der Quelle, lösen jedoch den Befehl MIGRATE aus, der direkt auf das Ziel-Backend verweist ([ziel-backend-hosts-fqdn]).
• COPY AUTH2: Da das Ziel eine Key Value Store-Instanz ist, müssen wir AUTH2 gefolgt vom [benutzername] und [passwort] des Ziels übergeben.

Alternative Strategie: Migration per Skript

Falls die Funktion MIGRATE aufgrund von Sonderzeichen in den Schlüsseln fehlschlägt, können Sie das Python-Skript copy_redis.py verwenden, um alle Schlüssel von der Quell- in die Zieldatenbank zu kopieren und zu überprüfen: copy_redis.zip. Folgen Sie den Anweisungen in der Datei README innerhalb der ZIP-Datei.

Migration über einen Cloud Foundry SSH-Tunnel

Um Daten in einen Cloud Foundry Runtime Key Value Store Datendienst zu migrieren, ist ein SSH-Forward-Tunnel erforderlich, um sicher auf das interne Backend zuzugreifen.

1. Binden Sie die Anwendung an den Zieldienst:

   cf bind-service [ihr-cf-app-name] [ihr-key-value-service-instanzname]

2. Starten Sie die Anwendung neu (Restage):

   cf restage [ihr-cf-app-name]

3. Erstellen Sie den SSH-Tunnel:

   cf ssh [ihr-cf-app-name] -L 6379:[ziel-backend-host]:[ziel-backend-port]

4. Führen Sie die Migration aus: Bei geöffnetem Tunnel in einem ersten Terminal können Sie den Migrationsbefehl in einem zweiten Terminal ausführen und dabei localhost:6379 als Ziel für den Befehl MIGRATE verwenden.

Auf Migrationsfehler prüfen

Die Datei migration-output-checker.txt enthält die Ausgabe des Befehls MIGRATE. Überprüfen Sie den erfolgreichen Ablauf der Migration anhand des Dateiinhalts:

cat migration-output-checker.txt | grep --invert-match "OK"

Die Ausgabe dieses Befehls muss leer sein. Ist sie das nicht, wird eine Fehlermeldung ausgegeben, die detailliert beschreibt, was schiefgegangen ist.

Fehlermeldung	Mögliche Ursache	Fehlerbehebung
NOKEY	Der Schlüssel existiert nicht in der Quellinstanz.	Überprüfen Sie, ob der erste Teil des Befehls (--raw KEYS '*') ausgeführt wurde.
IOERR error or timeout	Ein Kommunikationsproblem zwischen den Instanzen.	Stellen Sie sicher, dass Sie für die Migration den richtigen Ziel-Backend-Host (nicht den Frontend/Exposed Host) verwendet haben.
ERR invalid password oder WRONGPASS	Authentifizierung am Ziel fehlgeschlagen.	Stellen Sie sicher, dass Sie AUTH2 mit dem korrekten Benutzernamen und Passwort für die Ziel-Key Value Store-Instanz verwenden.

Datenbankkonsistenz prüfen

Überprüfen Sie die Datenbankkonsistenz zwischen der ursprünglichen Quelldatenbank und der Zieldatenbank, um sicherzustellen, dass alle Daten migriert wurden.

Daten zwischen den Instanzen vergleichen

Führen Sie den Befehl INFO KEYSPACE auf beiden Hosts aus. Die Anzahl der Schlüssel (keys) und Ablaufwerte (expires) muss identisch sein.

Auf der Quelldatenbank:

valkey-cli -u "[quell-db-verbindungszeichenfolge]" --tls --sni [quell-frontend-hosts-fqdn] --cacert [/pfad/zu/ca_zertifikat.pem] INFO KEYSPACE

Auf der Zieldatenbank:

valkey-cli -u "[ziel-db-verbindungszeichenfolge]" --tls --sni [ziel-frontend-hosts-fqdn] --cacert [/pfad/zu/ca_zertifikat.pem] INFO KEYSPACE

Vergleichen Sie als Nächstes die Speichernutzung. Die Werte sollten identisch sein (geringe Abweichungen durch Engine-Overhead sind zulässig).

valkey-cli -u "[db-verbindungszeichenfolge]" --tls INFO MEMORY | grep "used_memory:\|used_memory_human"

Schlüssel zwischen den Instanzen vergleichen

In diesem Schritt werden die wörtlichen Schlüsselnamen beider Instanzen exportiert und verglichen.

Rufen Sie alle Quellschlüssel ab und sortieren Sie diese:

valkey-cli -u "[quell-db-verbindungszeichenfolge]" --tls --raw KEYS '*' > source.txt && sort --parallel=2 -uo source-sorted.txt source.txt

Rufen Sie alle Zielschlüssel ab und sortieren Sie diese:

valkey-cli -u "[ziel-db-verbindungszeichenfolge]" --tls --raw KEYS '*' > target.txt && sort --parallel=2 -uo target-sorted.txt target.txt

Stellen Sie sicher, dass beide Dateien nicht leer sind, und vergleichen Sie diese anschließend:

diff source-sorted.txt target-sorted.txt

Die Ausgabe muss vollständig leer sein, was bedeutet, dass keine Unterschiede zwischen den Datensätzen bestehen.

Ressourcen (Assets)

Laden Sie das Python-Migrationsskript herunter: copy_redis.zip.