Skip to content

Commit d81df6e

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #299053 from khdownie/kendownie-glusterfs
GlusterFS to Azure Files migration guide
2 parents 18bd0e5 + f3fe021 commit d81df6e

File tree

2 files changed

+301
-0
lines changed

2 files changed

+301
-0
lines changed

‎articles/storage/files/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,8 @@
7777
href: ../common/storage-use-azcopy-files.md?toc=/azure/storage/files/toc.json
7878
- name: Configure, optimize, and troubleshoot AzCopy
7979
href: ../common/storage-use-azcopy-configure.md?toc=/azure/storage/files/toc.json
80+
- name: Migrate GlusterFS to Azure Files
81+
href: glusterfs-migration-guide.md
8082
- name: Authentication and authorization
8183
items:
8284
- name: Overview of identity-based authentication

‎articles/storage/files/glusterfs-migration-guide.md

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
---
2+
title: GlusterFS to Azure Files migration guide
3+
description: Red Hat Gluster Storage (based on GlusterFS) has reached the end of its support lifecycle. Use this guide to migrate GlusterFS volumes to Azure Files.
4+
author: khdownie
5+
ms.service: azure-file-storage
6+
ms.topic: how-to
7+
ms.date: 05/19/2025
8+
ms.author: kendownie
9+
---
10+
11+
# Migrate GlusterFS volumes to Azure Files
12+
13+
This article provides guidance on migrating data from GlusterFS volumes to Azure Files, Microsoft's fully managed file service in the cloud. Azure Files offers both SMB (Server Message Block) and NFS (Network File System) protocols, making it suitable for both Windows and Linux workloads.
14+
15+
## GlusterFS end-of-life considerations
16+
17+
Red Hat Gluster Storage (based on GlusterFS) has reached the end of its support lifecycle. Red Hat officially announced end of life for this product with the following schedule.
18+
19+
- End of full support: November 2020
20+
- End of maintenance support: November 2021
21+
- End of extended life phase: June 2024
22+
- Formal end of life: December 2024
23+
24+
Organizations using GlusterFS should migrate to supported alternatives, such as Azure Files, to ensure continued support and security updates.
25+
26+
## Client requirements for Azure Files
27+
28+
Before migrating from GlusterFS to Azure Files, ensure your client systems meet the necessary requirements for connecting to Azure file shares using either SMB or NFS protocols.
29+
30+
# [Windows](#tab/windows)
31+
32+
### SMB requirements
33+
34+
Windows clients connecting to Azure Files via SMB should meet the following requirements:
35+
36+
- Windows 7 or Windows Server 2008 R2 or newer
37+
- SMB 2.1 protocol support (minimum)
38+
- SMB 3.0 protocol support for encryption features
39+
- SMB 3.1.1 protocol support for best security and performance
40+
41+
> [!IMPORTANT]
42+
> We strongly recommend using SMB 3.1.1 protocol for Azure Files access. SMB 3.0 and 2.0 should only be used for legacy clients, and you must plan an OS upgrade to mitigate unpatched security vulnerabilities.
43+
44+
For a complete list of requirements and setup instructions, see [Use an Azure file share with Windows](storage-how-to-use-files-windows.md#prerequisites).
45+
46+
### NFS requirements
47+
48+
Azure Files supports NFSv4.1, but Windows doesn't include a compatible NFSv4.1 client. To use NFS shares on Windows:
49+
50+
1. Install Windows Subsystem for Linux (WSL):
51+
- For Windows client: Follow the [WSL installation guide](/windows/wsl/install)
52+
- For Windows Server: Follow the [WSL on Windows Server installation guide](/windows/wsl/install-on-server)
53+
54+
1. Mount the NFS share from within a Linux distribution running on WSL.
55+
56+
# [Linux](#tab/linux)
57+
58+
### SMB requirements
59+
60+
Linux clients connecting via SMB should have:
61+
62+
- A compatible Linux distribution with SMB support
63+
- The `cifs-utils` package installed
64+
- SMB 3.0 protocol support (minimum)
65+
- SMB 3.1.1 protocol support (recommended)
66+
67+
> [!IMPORTANT]
68+
> We strongly recommend using SMB 3.1.1 protocol for Azure Files access. SMB 3.0 and 2.0 should only be used for legacy clients, and you must plan an OS upgrade to mitigate unpatched security vulnerabilities.
69+
70+
For specific distribution support and configuration steps, see [Mount SMB Azure file shares on Linux clients](storage-how-to-use-files-linux.md#prerequisites).
71+
72+
### NFS requirements
73+
74+
Linux clients connecting via NFS should have:
75+
76+
- NFSv4.1 client support
77+
- A compatible Linux distribution
78+
- Proper network configuration for NFS traffic
79+
80+
For NFS mount requirements and configuration steps, see [Mount an NFS share](storage-files-how-to-mount-nfs-shares.md).
81+
82+
---
83+
84+
## Migration tools
85+
86+
For Windows clients, we recommend using Robocopy.
87+
88+
For Linux clients, use rsync or fpsync, which allows you to parallelize rsync file operations. See [Using fpsync vs. rsync](storage-files-migration-nfs.md#using-fpsync-vs-rsync).
89+
90+
# [Windows](#tab/windows)
91+
92+
### For Windows clients: Robocopy
93+
94+
Robocopy is a built-in Windows command-line tool designed for copying SMB file shares.
95+
96+
#### Basic Robocopy syntax for migration
97+
98+
```powershell
99+
robocopy <GlusterFS_Source> <AzureFiles_Destination> /MIR /Z /MT:8 /W:1 /R:3 /LOG:migration_log.txt
100+
```
101+
102+
**Parameters:**
103+
- `/MIR`: Mirrors directory structure (includes subdirectories)
104+
- `/Z`: Enables restart mode for interrupted copies
105+
- `/MT:8`: Uses 8 threads for multi-threaded copying
106+
- `/W:1`: Wait time between retries (1 second)
107+
- `/R:3`: Number of retries on failed copies
108+
- `/LOG`: Creates a detailed log file
109+
110+
# [Linux](#tab/linux)
111+
112+
### For Linux clients: rsync
113+
114+
rsync is a fast, versatile file copy tool available on Linux systems.
115+
116+
#### Basic rsync syntax for migration
117+
118+
```bash
119+
rsync -avz --progress --stats --delete <GlusterFS_Source>/ <AzureFiles_Destination>/
120+
```
121+
122+
**Parameters:**
123+
- `-a`: Archive mode (preserves permissions, timestamps, etc.)
124+
- `-v`: Verbose output
125+
- `-z`: Compresses data during transfer
126+
- `--progress`: Shows progress during transfer
127+
- `--stats`: Provides transfer statistics
128+
- `--delete`: Removes files from destination that don't exist in source
129+
130+
---
131+
132+
## Step-by-step migration procedure
133+
134+
### Step 1: Assessment and planning
135+
136+
1. Inventory your GlusterFS volumes, noting:
137+
- Total data size
138+
- Number of files and directories
139+
- Access patterns and performance requirements
140+
- Client operating systems
141+
142+
1. Select the appropriate protocol. In most cases, you'll want to use SMB for Windows workloads and NFS for Linux workloads.
143+
144+
1. Select HDD or SSD, and size your Azure file shares appropriately:
145+
- Standard (HDD): Up to 100 TiB
146+
- Premium (SSD): Up to 100 TiB with higher performance
147+
148+
### Step 2: Prepare Azure environment
149+
150+
1. [Create a storage account](../common/storage-account-create.md) in the appropriate Azure region.
151+
- Choose the right performance tier (Standard or Premium) based on your needs. Premium is required for NFS file shares.
152+
153+
1. Configure networking. See [Azure Files networking considerations](storage-files-networking-overview.md).
154+
- SMB: Configure firewall and private endpoints as needed. See [Configure Azure Storage firewalls](../common/storage-network-security.md) and [Configure network endpoints for accessing Azure file shares](storage-files-networking-endpoints.md).
155+
- NFS: Configure network security and private endpoints. See [Mount NFS Azure file shares on Linux](storage-files-how-to-mount-nfs-shares.md).
156+
157+
1. Create Azure file shares with appropriate protocols.
158+
159+
### Step 3: Mount Azure file share
160+
161+
Before migrating the data, you must mount the Azure file share(s).
162+
163+
# [Windows](#tab/windows)
164+
165+
#### For Windows clients (SMB):
166+
167+
This article shows how to mount the Azure file share using NTLMv2 authentication (storage account key). In non-administrative scenarios, using [identity-based authentication](storage-files-active-directory-overview.md) is preferred for security reasons.
168+
169+
You can find your storage account key in the [Azure portal](https://portal.azure.com/) by navigating to the storage account and selecting **Security + networking** > **Access keys**, or you can use the `Get-AzStorageAccountKey` PowerShell cmdlet.
170+
171+
To mount the file share, run the following command. Be sure to replace `<storage-account-name>`, `<share-name>`, and `<storage-account-key>` with your actual values.
172+
173+
```powershell
174+
net use Z: \\<storage-account-name>.file.core.windows.net\<share-name> /u:AZURE\<storage-account-name> <storage-account-key>
175+
```
176+
177+
# [Linux](#tab/linux)
178+
179+
#### For Linux clients (NFS):
180+
181+
To mount the file share, run the following command. Be sure to replace `<storage-account-name>`, `<share-name>`, and `<mount-point>` with your actual values.
182+
183+
```bash
184+
sudo mount -t nfs <storage-account-name>.file.core.windows.net:/<storage-account-name>/<share-name> <mount-point> -o vers=4.1,sec=sys
185+
```
186+
---
187+
188+
### Step 4: Perform data migration
189+
190+
After you've mounted the Azure file share, you can perform the data migration.
191+
192+
# [Windows](#tab/windows)
193+
194+
#### For Windows workloads using Robocopy:
195+
196+
Open a command prompt or PowerShell window with administrator privileges, and run the following command:
197+
198+
```powershell
199+
robocopy X:\GlusterFSData Z:\AzureFilesData /MIR /Z /MT:8 /W:1 /R:3 /LOG:C:\migration_log.txt
200+
```
201+
202+
# [Linux](#tab/linux)
203+
204+
#### For Linux workloads using rsync:
205+
206+
Execute the following command:
207+
208+
```bash
209+
rsync -avz --progress --stats --delete /mnt/glusterfs/ /mnt/azurefiles/
210+
```
211+
212+
For large datasets, consider using the `--exclude` parameter to perform the migration in phases.
213+
214+
---
215+
216+
### Step 5: Verify that migration succeeded
217+
218+
1. Compare file counts and sizes:
219+
- On Windows: Use `Get-ChildItem -Recurse | Measure-Object`
220+
- On Linux: Use `find . -type f | wc -l` and `du -sh`
221+
222+
1. Validate user/group permissions and access rights.
223+
224+
1. Perform application-specific tests.
225+
226+
### Step 6: Cutover
227+
228+
1. Redirect applications to use Azure Files endpoints.
229+
1. Update mount points in fstab (Linux) or mapped drives (Windows).
230+
1. Update documentation and monitoring tools.
231+
1. Decommission GlusterFS volumes after successful validation.
232+
233+
## Optimize performance
234+
235+
Follow these recommendations to optimize performance when migrating from GlusterFS to Azure Files. For detailed performance tuning, see [Azure Files scalability and performance targets](storage-files-scale-targets.md) and [Understand and optimize Azure file share performance](understand-performance.md).
236+
237+
> [!NOTE]
238+
> Check virtual machine (VM) size to ensure that VM network bandwidth isn't a bottleneck when your file shares are correctly sized for required throughput and IOPS. Different VM SKUs have different network bandwidth limits that can constrain overall file share performance. Select VM sizes that provide sufficient network throughput for your workload requirements. For more information, see [Azure virtual machine sizes](/azure/virtual-machines/sizes).
239+
240+
# [Windows](#tab/windows)
241+
242+
### Optimize SMB performance
243+
244+
- Enable [SMB Multichannel](smb-performance.md#smb-multichannel) for higher throughput with multiple connections.
245+
- Use SSD file shares and [Metadata caching](smb-performance.md#metadata-caching-for-ssd-file-shares) for performance-critical workloads.
246+
- Configure appropriate client-side caching.
247+
- Follow [Azure Files performance recommendations](smb-performance.md) for SMB file shares.
248+
249+
# [Linux](#tab/linux)
250+
251+
### Optimize NFS performance
252+
253+
- Always use Premium (SSD) file shares for NFS workloads (required).
254+
- Provision sufficient capacity based on your [throughput requirements](understand-performance.md).
255+
- Optimize client-side settings like read/write buffer sizes.
256+
- Use nconnect, a client-side mount option that allows you to use multiple TCP connections between the client and your NFS file share. We recommend the optimal setting of `nconnect=4`.
257+
- Consider network latency between your clients and Azure.
258+
- Follow [Azure Files performance recommendations](nfs-performance.md) for NFS file shares.
259+
260+
---
261+
262+
## Troubleshooting
263+
264+
Follow these instructions to troubleshoot common migration issues.
265+
266+
# [Windows](#tab/windows)
267+
268+
### Common issues with Robocopy
269+
270+
- **Error 5 (Access denied)**: Verify permissions on source and destination.
271+
- **Error 67 (Network name not found)**: Check network connectivity and share name.
272+
- **Error 1314 (Not enough quota)**: Increase Azure Files quota or free space.
273+
274+
# [Linux](#tab/linux)
275+
276+
### Common issues with rsync
277+
278+
- **Permission denied**: Check file permissions and mount options.
279+
- **Connection timeout**: Verify network connectivity and firewall settings.
280+
- **Partial transfer**: Use `--partial` flag to resume interrupted transfers.
281+
- **No such file or directory**: Verify that the file path and directory exist.
282+
283+
---
284+
285+
## Migration support
286+
287+
For issues related to Azure Files, contact Azure Support through the [Azure portal](https://portal.azure.com).
288+
289+
For GlusterFS migration assistance, consider engaging Microsoft Consulting Services.
290+
291+
## See also
292+
293+
- [Use RoboCopy to migrate to SMB Azure file shares](storage-files-migration-robocopy.md)
294+
- [Migrate to NFS Azure file shares](storage-files-migration-nfs.md)
295+
- [Robocopy documentation](/windows-server/administration/windows-commands/robocopy)
296+
- [rsync manual](https://linux.die.net/man/1/rsync)
297+
- [Using fpsync to parallelize rsync file operations](https://www.fpart.org/fpsync/)
298+
- [Azure Files scale targets](storage-files-scale-targets.md)
299+
- [Troubleshoot Azure Files](/troubleshoot/azure/azure-storage/files/connectivity/files-troubleshoot)

0 commit comments

Comments
 (0)