Große File-Migration mit NFS und fpsync

Use Case

• Kategorie: Migration großer Dateibestände
• Ziel: STACKIT File Service
• Methode: Migrations-VM mit Quell- und Ziel-NFS-Mounts, synchronisiert mit fpsync

Netzwerk- und Architektur-Rahmenbedingungen (validiert)

• SFS hängt an der SNA: STACKIT File Storage ist mit einer STACKIT Network Area (SNA) verbunden, nutzt private Interconnection-Subnetze und erfordert SNA-Routing-Tabellen. Siehe File-Storage-Konzepte und SNA-Routing-Tabellen .
• Mount-Zugriff ist netzwerkbeschränkt: NFS-Mounts werden über Resource-Pool-IP-ACLs und Share-Export-Policies gesteuert; die IP des Migrations-Hosts muss explizit erlaubt sein. Siehe Resource Pools und Shares mounten .
• SNA ist regional: Privater SNA-Traffic ist regional; regionsübergreifender Traffic ist über das öffentliche Internet möglich. Siehe Network-Area-Konzepte .
• Anbietervergleich ist konsistent: Vergleichbare NFS-Dienste wie AWS-EFS-Mount-Targets sind by design ebenfalls privat (keine öffentliche IP auf Mount-Targets), dort ist also genauso ein privater Pfad erforderlich. Siehe AWS EFS network access .

Aus der STACKIT-DokuConcepts and terminology › InterconnectionStand der Quelle 22.04.2026 · übernommen 05.10.2026

Diesen Abschnitt gibt es nur auf Englisch.

A STACKIT File Storage is always connected to an STACKIT Network Area (SNA). Therefore, a dedicated subnet of the SNA-Network is reserved and used to interconnect the whole SNA with the STACKIT File Storage (routed per default). It can be restricted by policies, if required. STACKIT File Storage requires routing tables to be enabled in the STACKIT Network Area. More information on how to do so can be found in the routing tables docs.

When configuring the SNA, please ensure the following requirements are met:

• There are sufficient IP networks available within the SNA.
• The minimum size for any new subnet must be set to at least /29.
• For the SFS interconnection, at least one subnet with /28 and four subnets with /29 are required.

Was ist das?

Dieser Abschnitt wird mehrmals am Tag automatisch aus der STACKIT-Doku übernommen. Hier lässt er sich nicht ändern. Änderungen gehören in die STACKIT-Doku.

Verbindliche Voraussetzungen

• Platzierung des Migrations-Hosts: Die Migrations-VM läuft in einem SNA-Projekt und einer Region, die den Ziel-SFS-Share mounten kann.
• Dual-Mount-Machbarkeit: Quell- und Ziel-Exports können beide auf einer Migrations-VM gemountet werden.
• Privater L3-Pfad zur Quell-NFS: Die Migrations-VM erreicht den Quell-NFS-Endpunkt über privates Routing (gleiche private Domäne, Peering oder Site-to-Site-VPN).
• NFS-Policy-Abgleich: ACL-/Security-Policy erlaubt die benötigten Client-IP-Bereiche und NFS-Traffic in beide Richtungen.
• Netzwerk-Machbarkeit: Latenz und Durchsatz reichen für parallele Synchronisation aus.
• Berechtigungsmodell abgestimmt: UID/GID- und ACL-Übersetzungsregeln sind definiert.
• Konsistenzmodell definiert: Initial-Sync, Delta-Sync-Fenster und finaler Freeze sind vereinbart.

Nicht geeignet, wenn

• Kein privater Pfad existiert: Die Quell-NFS ist vom SNA-verbundenen Migrations-Host nicht über kontrollierte private Konnektivität erreichbar.
• Dual-NFS-Mount blockiert ist: Policy- oder Netzwerk-Einschränkungen verhindern gleichzeitige Mounts.
• Ein Protokoll-Mismatch vorliegt: Der Quell-Endpunkt bietet keinen kompatiblen NFS-Zugriff.

VPN-Machbarkeit

• VPN ist eine valide Option: Dieses Runbook funktioniert mit VPN, wenn das VPN das Quellnetz mit der zielseitigen SNA verbindet und die Routen korrekt propagiert werden.
• VPN-Scope ist Site-to-Site: STACKIT VPN ist für Site-to-Site-Verbindungen und SNA-basierte Projekte ausgelegt. Siehe STACKIT VPN Produktübersicht .
• Operative Readiness erforderlich: Tunnel-Stabilität, MTU-Verhalten und dauerhaften Durchsatz vor dem Cutover validieren.

Wann diese Variante wählen

• NFS+fpsync wählen, wenn: Ein Migrations-Host sowohl Quell-NFS als auch Ziel-SFS direkt mounten kann und schnelle iterative Delta-Zyklen benötigt werden.
• NFS+fpsync nicht wählen, wenn: Der Quellzugriff nicht NFS-kompatibel ist oder keine kontrollierte private Konnektivität zur Quelle aufgebaut werden kann.
• Alternative: Das rclone-Bridge-Runbook verwenden, wenn duales NFS-Mounting nicht machbar ist.

Platzierung der Migrations-VM und Trade-offs

• Bevorzugte Platzierung (STACKIT-Seite): Die Migrations-VM in STACKIT betreiben, angebunden an die SNA. Das hält den SFS-Schreibpfad privat und macht zielseitiges Routing und ACL-Kontrolle direkter.
• Alternative Platzierung (Quellseite): Einen Transfer-Host nur dann nahe der Quelle betreiben, wenn Quell-Einschränkungen es erfordern. Das erschwert den Dual-Mount-Betrieb zu SFS meist und verschiebt Komplexität oft in Relay-Muster.
• VPN-Implikation: Für die Quell-Erreichbarkeit ist Site-to-Site-VPN der bevorzugte Helfer. In dieser Topologie läuft der Quell-Traffic zur Migrations-VM durch den VPN-Tunnel.

Empfohlene Topologie: STACKIT-Migrations-VM mit Site-to-Site-VPN zur Quelle

Diese Topologie ist das primäre Muster für VPN-gestützte Dual-Mounts in diesem Runbook.

Alternative Topologie mit quellseitigem fpsync-Client und HAProxy-TCP-Proxy

Diese Variante nutzen, wenn der fpsync-Client auf der Quellseite bleiben soll und das NFS-Mounten auf dem STACKIT-Jump-Host selbst vermieden werden soll.

• Muster: HAProxy auf dem Jump-Host arbeitet als TCP-Pass-Through-Endpunkt für NFS-Traffic (tcp/2049) Richtung SFS.
• Ingress-Pfad: Der quellseitige Client erreicht HAProxy über die öffentliche IP des Jump-Hosts.
• Security-Controls auf dem Jump-Host: Security Group / ACL auf dem Jump-Host erlaubt eingehendes tcp/2049 nur von freigegebenen öffentlichen Quell-IP-Bereichen.
• Kein Ziel-Mount auf dem Jump-Host: Der Jump-Host leitet NFS-Sessions weiter und muss den SFS-Share nicht lokal mounten.
• Gemeinsames Client-Modell: Der quellseitige Migrations-Client kann Quell-NFS direkt und Ziel-NFS über den HAProxy-Endpunkt mounten und dann fpsync zwischen beiden Mount-Punkten laufen lassen.
• Policy-Voraussetzung: Die SFS-ACL-/Export-Policy muss den effektiven Client-Pfad und das Quell-IP-Modell dieses Setups erlauben.

Warum das nützlich sein kann

• Logging: HAProxy-TCP-Logs bieten einen zentralen Trace-Punkt für NFS-Session-Versuche, Verbindungsfehler und Backend-Verfügbarkeit.
• Timeout-Kontrolle: HAProxy-Timeout-Einstellungen (timeout connect, timeout client, timeout server) geben explizite Kontrolle über hängende oder langlaufende Verbindungen.
• Operative Leitplanken: Kontrolliertes Connection-Handling und klares Fehlverhalten lassen sich an einem einzigen Ingress-Punkt umsetzen.

Trade-offs und Risiken

• Zusätzlicher Hop: Fügt dem Datenpfad einen Netzwerk-Hop und eine zusätzliche Komponente hinzu.
• Proxy-Bottleneck-Risiko: Jump-Host-Sizing und HAProxy-Tuning werden durchsatzkritisch.
• Validierung der Service-Semantik: NFS über TCP-Proxying muss end-to-end im Ziel-Policy- und Support-Modell validiert werden.
• Hochverfügbarkeit nötig: Ohne HA-Design kann der Proxy-Host zum Single Point of Failure werden.

Variantenvergleich: VPN-Dual-Mount-VM vs. HAProxy-TCP-Proxy

Seitlich wischen, um die ganze Tabelle zu sehen

Kriterium	Variante A: STACKIT-Migrations-VM mit Dual-Mounts (VPN zur Quelle)	Variante B: Quell-Client + HAProxy-TCP-Proxy
Security-Oberfläche	Kleinere Laufzeitkette; weniger Zwischenkomponenten im Datenpfad.	Zusätzliche Proxy-Schicht zu härten und zu betreiben; zentrale Ingress-Kontrolle möglich.
Performance	Meist höheres Durchsatzpotenzial (direkter Dual-Mount, weniger Hops).	Zusätzlicher Hop und Proxy-Verarbeitung senken den Spitzendurchsatz in den meisten Umgebungen.
Stabilität	Weniger bewegliche Teile; hängt an VPN- und Migrations-VM-Stabilität.	Zusätzliche Fehlerdomäne (HAProxy-Host/-Service); braucht HA-Design für Robustheit.
Monitoring und Logging	Stützt sich primär auf Host-, NFS-Client- und Netzwerk-Metriken.	Starke zentrale TCP-Sichtbarkeit und Timeout-Beobachtung auf der Proxy-Schicht.
Timeout-Handling	Überwiegend OS-/NFS-Client-Verhalten auf der Migrations-VM.	Explizite Timeout-Kontrolle in HAProxy plus clientseitiges Timeout-Verhalten.
Operative Komplexität	Einfachere Basisarchitektur.	Mehr Komponenten zu konfigurieren, zu tunen und zu troubleshooten.

Gemeinsamer Zielzustand beider Varianten

Für beide Architekturen kann der effektive Migrationsfluss im selben fpsync-Modell enden:

• Der quellseitige oder STACKIT-seitige Client hat zwei NFS-Mount-Punkte (Quelle und Ziel).
• fpsync fährt iterative Sync-Zyklen zwischen diesen Mount-Punkten.
• Finales Freeze-Fenster und finaler Durchlauf bleiben im Prinzip identisch.

Operativer Ablauf auf der Migrations-VM

• Schritt 1 (Quell-Mount): Die Migrations-VM mountet den Quell-NFS-Export über den privaten Pfad der gewählten Topologie (für dieses Runbook: Site-to-Site-VPN-Tunnel zur Quelle).
• Schritt 2 (Ziel-Mount): Dieselbe Migrations-VM mountet den SFS-Zielpfad per NFSv4.1 (TCP 2049) über SNA-Routing-Tabellen.
• Schritt 3 (Sync-Zyklen): fpsync fährt iterative Delta-Zyklen zwischen beiden gemounteten Pfaden bis zum Cutover.
• Schritt 4 (finaler Durchlauf): Nach dem Quell-Freeze den finalen fpsync-Durchlauf fahren und Integritätschecks abschließen.

Durchsatz- und Parallelitäts-Tuning

• fpsync-Worker-Parallelität: Parallele Worker mit fpsync -n <parallelism> erhöhen und in kontrollierten Schritten tunen.
• Startpunkt und Skalierung: Mit moderater Parallelität starten, Durchsatz und Fehlerrate beobachten, dann erhöhen, bis der Zugewinn abflacht oder Retries steigen.
• NFS-Client-Tuning: Mount-Optionen wie rsize, wsize und nconnect (wo unterstützt) für Quell- und Ziel-Mounts validieren.
• Qualität des Netzwerkpfads: MTU, Paketverlust und Latenz über den Quellpfad (inklusive VPN) und den SNA-Zielpfad stabil halten.
• VM-Sizing: Sicherstellen, dass CPU, Arbeitsspeicher und NIC-Bandbreite der Migrations-VM für gleichzeitige Datei-Traversierung und Transfer ausreichen.
• Storage-seitige Limits: Quell-Export-Limits und SFS-seitiges Durchsatzverhalten prüfen, damit das Worker-Scaling keine service-seitigen Engpässe überschreitet.
• Workload-Profil-Split: Datasets mit großen und kleinen Dateien in dedizierten Testsets testen; kleine Dateien brauchen oft höhere Metadaten-Parallelität, nicht nur Bandbreite.
• Messdisziplin: Effektive MB/s, Dateien/s, Retransmits, Retries und Server-Last je Tuning-Schritt erfassen.

Umsetzungsvorlage

Phase 1: Migrations-VM vorbereiten

1. Migrations-VM härten und Logging konfigurieren.
2. Quell- und Ziel-NFS-Pfade mit verifizierten Optionen mounten.
3. Baseline-Lese-/Schreib-Proben fahren und Durchsatz dokumentieren.

Phase 2: Initial- und Delta-Sync

1. Initialen fpsync-Durchlauf fahren.
2. Transferstatistiken und Fehlerdateien erfassen.
3. Delta-Sync-Zyklen bis zum Cutover-Fenster einplanen.

Phase 3: Finaler Sync und Handover

1. Finalen Schreib-Freeze im Quell-Fenster aktivieren.
2. Finalen fpsync-Durchlauf fahren und Integritäts-Stichprobe verifizieren.
3. Gemounteten Zielpfad an den konsumierenden Workload übergeben.

Validierungscheckliste

• Dateiintegrität: Checksummen-Stichprobe und Anzahl-Verifikation abgeschlossen.
• Berechtigungsintegrität: ACL- und Ownership-Stichproben abgeschlossen.
• Performance-Nachweis: Effektiver Durchsatz und Gesamtdauer dokumentiert.
• Operatives Handover: Monitoring und Ownership bestätigt.