Fix: Minio refuses to start with mounted ZFS sub filesystems

Summary

The website provides a solution for Minio server issues related to starting up with mounted ZFS sub filesystems by using UnionFS.

Abstract

The article addresses a specific problem encountered by Minio users who have set up sub filesystems within a ZFS pool, which prevents Minio from starting properly. The issue is exemplified by several GitHub threads discussing the problem. The proposed workaround involves using UnionFS to create a union of the Minio data directory and its sub filesystems. The solution includes steps to install UnionFS-Fuse, create a mount point, ensure the integrity of the mount point, mount the Minio directory with read-write access, and finally, update the /etc/fstab file to make the mount persistent across reboots. The article concludes by reminding users to update their Minio configuration to reflect the new data directory path.

Opinions

The author has experienced the issue firsthand, suggesting a practical and tested solution.
The solution is presented as straightforward and easy, implying confidence in its efficacy.
The use of UnionFS is recommended without discussing potential drawbacks or alternatives, indicating a preference or belief in its reliability.
The article assumes a certain level of technical expertise from the reader, as the steps involve command-line operations and system configuration changes.

Fix: Minio refuses to start with mounted ZFS sub filesystems

Apparently this is an abstract image of two filesystems unioning together in a modern art style. I made it with DiffusionBee on Mac.

If you’re having the issues like this, or this, or this, you can work around it using UnionFS.

For me, I have a /home/minio folder, and I run an older version of minio in FS mode, on ZFS. When I moved to a new zpool, I setup sub filesystems for different projects in my minio fs, causing it not to start.

The fix is easy:

# assuming /home/minio is the location of your minio data and sub-filesystems
apt-get install unionfs-fuse

# make somewhere to mount the unionfs
mkdir /home/minio-unionfs

# stop anything actually writing in this folder if it's not yet mounted
chattr +i /home/minio-unionfs

# mount the /home/minio folder RW /home/minio-unionfs
unionfs-fuse /home/minio=RW /home/minio-unionfs

# make the mount survive reboots - add to /etc/fstab
echo "/home/minio=RW /home/minio-unionfs fuse.unionfs options   0       0" >> /etc/fstab

That is it. Just don’t forget to change your minio config for the data dir to /home/minio-unionfs.