Skip to main content

Migrating Shared Disks to NFS

Overview​

Migration of Shared Disks to NFS is recommended for customers as soon as possible as the virtiofs implementation will be deprecated in the first half of 2026. More details will be shared via your customer success manager. Here are the steps involved in the migration process:

Step 1: Schedule a maintenance window​

In order to begin the migration of your Shared Disks to NFS, please contact support to schedule a maintenance window.

The migration process needs to be performed on a per-project basis. Once a project has begun migration, all newly created shared disks will only be available via NFS. Existing virtiofs mounts will continue to work without any disruptions.

Step 2: Install NFS drivers on all VMs in the project​

a. Use the following Python script to install the NFS driver on a VM.​

wget -O crusoe_shared_disks_nfs_setup.py https://github.com/crusoecloud/crusoe-nfs-support/raw/refs/heads/main/crusoe_shared_disks_nfs_setup.py
python3 crusoe_shared_disks_nfs_setup.py

On a Mac

brew install pssh

On Linux

sudo apt install pssh

c. Create a file named hosts.txt that includes the IP addresses of all VMs, one per line, on which this script needs to be applied. An example script would look like this​

ubuntu@<IP1>
ubuntu@<IP2>

d. Apply the script to multiple VMs at once:​

info

Info: Please ensure ssh connectivity is setup between the source and destination before running this command

Use pscp and pssh on a Mac

pscp -h hosts.txt crusoe_shared_disks_nfs_setup.py /home/ubuntu/crusoe_shared_disks_nfs_setup.py
pssh -t 0 -h hosts.txt "export DEBIAN_FRONTEND=noninteractive && python3 /home/ubuntu/crusoe_shared_disks_nfs_setup.py -y"

Use parallel-scp and parallel-ssh on Linux

parallel-scp -h hosts.txt crusoe_shared_disks_nfs_setup.py /home/ubuntu/crusoe_shared_disks_nfs_setup.py
parallel-ssh -t 0 -h hosts.txt "export DEBIAN_FRONTEND=noninteractive && python3 /home/ubuntu/crusoe_shared_disks_nfs_setup.py -y"

Step 3: Remount virtiofs mounts via NFS​

danger

Warning: The remount step will unmount and remount the disks. Please ensure that no I/O is running on the disks during this step. In case the I/O cannot be stopped on a VM, please exclude the VM in the hosts.txt file and perform the steps manually as described in unmounting a Shared Disk and mounting a NFS Shared Disk

a. Download the following Python script as crusoe_shared_disks_virtiofs_to_nfs.py on a VM.​

wget -O crusoe_shared_disks_virtiofs_to_nfs.py https://github.com/crusoecloud/crusoe-nfs-support/raw/refs/heads/main/crusoe_shared_disks_virtiofs_to_nfs.py

To apply this script to multiple VMs at once, it is recommended to use the pssh procedure. Install pssh, as shown in step 2b.

b. Obtain the list of disk names to disk IDs for your project. You will need your project's ID and the Crusoe CLI to run this command. See viewing Shared Disks for more details:​

crusoe storage disks list --project-id <PROJECT_ID> --format json | jq -r '[.[] | select(.type == "shared-volume")] | map("\(.name),\(.id)") | join("+")'

The output should look similar to this: disk-name-1,00000000-0000-0000-0000-000000000000+disk-name-2,00000000-0000-0000-0000-000000000000. Copy this to use in Step 3d in the place of <PASTE_DISK_TEXT_HERE>.

c. Next, create a file named hosts.txt that includes the IP addresses of all VMs, one per line, on which this script needs to be applied. An example script would look like this​

ubuntu@<IP1>
ubuntu@<IP2>

d. Apply the script to multiple VMs at once.​

Use pscp and pssh on a Mac

pscp -h hosts.txt crusoe_shared_disks_virtiofs_to_nfs.py /home/ubuntu/crusoe_shared_disks_virtiofs_to_nfs.py
pssh -t 0 -h hosts.txt "export DEBIAN_FRONTEND=noninteractive && python3 /home/ubuntu/crusoe_shared_disks_virtiofs_to_nfs.py -y --name-ids <PASTE_DISK_TEXT_HERE>"

Use parallel-scp and parallel-ssh on Linux

parallel-scp -h hosts.txt crusoe_shared_disks_virtiofs_to_nfs.py /home/ubuntu/crusoe_shared_disks_virtiofs_to_nfs.py
parallel-ssh -t 0 -h hosts.txt "export DEBIAN_FRONTEND=noninteractive && python3 /home/ubuntu/crusoe_shared_disks_virtiofs_to_nfs.py -y --name-ids <PASTE_DISK_TEXT_HERE>"

Step 4: Cleanup​

Once the remounting step is complete, the Crusoe Support team will run some cleanup scripts to complete the migration. Please update any fstab entries on the VMs to reflect the new mount options. See Mounting Shared Disks for details.

Known limitations​

  1. Customers should not create a new VPC network or VPC subnet during the migration process.
  2. Customers should not mount the NFS mount on the same directory as the existing virtiofs mount. This will cause issues with file consistency.
  3. Customers cannot use the 100.64.0.0-100.64.0.17 IP Address range for any other networking configurations such as VPN. Otherwise, mounting of the NFS shared disks will fail.

Mitigations​

In case there are any issues during the migration, there is an option to rollback.