--- title: "Große File-Migration mit NFS und fpsync" description: Konkrete Vorlage für die Migration großer Dateibestände auf einen STACKIT File Storage Share per Migrations-VM mit dualen NFS-Mounts und fpsync-Deltas. sidebar: badge: text: "STACKIT" variant: success scfAsset: managed: false category: "runbook" external: false tags: ["design-and-mobilize", "use-cases", "replatform", "file-data", "file-service", "fpsync", "nfs"] maintainers: - user: "lukas.weberruss" role: true website: true source_url: "https://framework.stackit.cloud/de/migration/assetcontainer/stackit/runbook-file-migration-nfs-fpsync/" source_file: "docs/de/migration/assetcontainer/stackit/runbook-file-migration-nfs-fpsync.mdx" --- ## 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-Doku: [Concepts and terminology › Interconnection](https://docs.stackit.cloud/products/storage/file-storage/basics/concepts/#interconnection) (Stand der Quelle 22.04.2026, übernommen 05.10.2026) 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](https://docs.stackit.cloud/products/network/core-networking/network-area/basics/routing-tables/). 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. ## 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](/de/migration/assetcontainer/stackit/runbook-file-migration-rclone-bridge/) 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. ```d2 style.font-size: 22 direction: right Source: "Quellumgebung" { SourceNFS: "Quell-NFS-Export" { icon: ../../../../../../../../../libs/ui/figma-assets/architecture-symbols/src/lib/assets/networking/network.svg } } VPN: "Site-to-Site-VPN-Tunnel" { icon: ../../../../../../../../../libs/ui/figma-assets/architecture-symbols/src/lib/assets/networking/vpn.svg link: https://docs.stackit.cloud/products/network/connectivity-hybrid-multi-cloud/vpn/ } STACKIT: "STACKIT" { grid-columns: 2 MigVM: "Migrations-VM (fpsync)" { icon: ../../../../../../../../../libs/ui/figma-assets/architecture-symbols/src/lib/assets/computing/virtual-machine.svg link: https://docs.stackit.cloud/products/compute-engine/server/ } SNA: "SNA" { grid-columns: 2 RT: "Routing-Tabellen" SFS: "STACKIT File Storage Share" { icon: ../../../../../../../../../libs/ui/figma-assets/architecture-symbols/src/lib/assets/computing/file-storage.svg link: https://docs.stackit.cloud/products/storage/file-storage/ } } } Source.SourceNFS -> VPN: "NFS" VPN -> STACKIT.MigVM: "NFS im Tunnel" STACKIT.MigVM -> STACKIT.SNA.RT: "NFS über SNA" STACKIT.SNA.RT -> STACKIT.SNA.SFS: "gerouteter Pfad" # Invisible edges to stabilize center alignment of outer blocks. Source -> VPN: { style.opacity: 0 } VPN -> STACKIT: { style.opacity: 0 } ``` ## 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. ```d2 style.font-size: 22 direction: right Source: "Quellumgebung" { grid-columns: 2 Client: "Quell-Migrations-Client (fpsync)" { icon: ../../../../../../../../../libs/ui/figma-assets/architecture-symbols/src/lib/assets/computing/virtual-machine.svg } SourceNFS: "Quell-NFS-Export" { icon: ../../../../../../../../../libs/ui/figma-assets/architecture-symbols/src/lib/assets/networking/network.svg } } Internet: "Öffentlicher Internetpfad" { icon: ../../../../../../../../../libs/ui/figma-assets/architecture-symbols/src/lib/assets/networking/ip.svg } STACKIT: "STACKIT" { grid-columns: 2 Jump: "Jump-Host mit HAProxy (TCP, Public IP)" { icon: ../../../../../../../../../libs/ui/figma-assets/architecture-symbols/src/lib/assets/computing/virtual-machine.svg link: https://docs.stackit.cloud/products/compute-engine/server/ } SG: "Security Group / ACL\nErlaubt eingehendes tcp/2049\nvon freigegebenen Quell-IPs" SNA: "SNA" { grid-columns: 2 RT: "Routing-Tabellen" SFS: "STACKIT File Storage Share" { icon: ../../../../../../../../../libs/ui/figma-assets/architecture-symbols/src/lib/assets/computing/file-storage.svg link: https://docs.stackit.cloud/products/storage/file-storage/ } } } Source.Client -> Source.SourceNFS: "NFS-Mount" Source.Client -> Internet: "NFS zur Public IP des Jump-Hosts" Internet -> STACKIT.SG: "TCP 2049" STACKIT.SG -> STACKIT.Jump: "erlaubter Ingress" STACKIT.Jump -> STACKIT.SNA.RT: "weitergeleitetes NFS" STACKIT.SNA.RT -> STACKIT.SNA.SFS: "gerouteter Pfad" # Invisible edges to stabilize center alignment of outer blocks. Source -> Internet: { style.opacity: 0 } Internet -> STACKIT: { style.opacity: 0 } ``` ### 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 | 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 ` 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.