MinIO Plugin

The Minio official plugin from the iXsystems catalog is a High-performance object (S3) storage suite, natively available on TrueNAS CORE.

This tutorial describes how to install the Minio plugin on TrueNAS and also how to migrate data from the deprecated S3 built-in service to the Minio plugin.

Create a dataset to use for Minio Plugin storage. This tutorial uses /mnt/tank/minio.

MinIO manages files as objects. These objects cannot mix with other dataset files.

In order to migrate data from an existing S3 service deployment running on TrueNAS CORE, the new destination dataset must have available storage capacity at least equal to the existing S3 service configuration. You can migrate data to a different networked device with enough storage capacity, however transfer rates might be slower depending on network configuration.

For better performance, total pool capacity should not exceed 80%. For example, if the original S3 dataset is 25TB and the destination dataset is created in the same pool, the total pool capacity should be at least 62.5TB (25TB for each dataset plus 20% overhead).

Edit permissions for the new dataset. Set User as minio and Group as wheel.

Go to the Plugins screen. If you have not previously configured plugins on the system, follow the initial setup instructions in Managing Plugins.

Select the Minio plugin from the iXsystems collection. Click INSTALL.

Enter a name for the plugin in Jail Name and adjust the networking settings as needed. You can use the default Network Address Translation (NAT), enable DHCP, or manually define IP addresses.

If migrating data from an existing S3 service deployment, ensure ports for the Minio plugin are different from the existing service.

Click Save to install. A dialog confirms when the installation completes and shows post-install notes, including the MINIO_ACCESS_KEY and MINIO_SECRET_KEY used to access the MinIO UI.

MINIO_ACCESS_KEY and MINIO_SECRET_KEY are deprecated. MinIO now utilizes MINIO_ROOT_USER and MINIO_ROOT_PASSWORD arguments and their values. When logging into the MinIO UI, enter the MINIO_ACCESS_KEY/​MINIO_ROOT_USER in Username and the MINIO_SECRET_KEY/​MINIO_ROOT_PASSWORD in Password.

Do not use these credentials to configure client applications for S3 data access. Instead, create key pairs from the MinIO UI Access Keys screen. Write down the generated key values or save them in a secure location as the Secret Key only displays one time, at creation.

You can view the post-install notes later by expanding the entry for the installed plugin in Plugins and clicking Post Install Notes.

The Plugins screen shows the installed plugin.

Click chevron_right to expand the Minio plugin details and management options.

Click  STOP to stop the jail before making any changes.

Click device_hub MOUNT POINTS and follow the instructions in Setting Up Jail Storage to mount the destination dataset you created in First Steps.

Click play_arrow START to restart the plugin and then click settings MANAGE to go to the MinIO Console and log in.

After completing initial installation of the Minio plugin, users with an existing S3 service deployment need to migrate S3 data from the previous service deployment to the new plugin. Migrating from the built-in S3 service to the Minio plugin could result in an extended data migration window and potential disruptions to S3 data access.

TrueNAS Enterprise

Beginning in CORE 13.0-U6, Enterprise customers with the S3 service running or enabled are prevented from upgrading to the next major version.

TrueNAS Enterprise customers are strongly encouraged to contact iXsystems Support for assistance with the migration process.

Contacting Support expand

Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.

Contact Method	Contact Options
Web	https://support.ixsystems.com
Email	support@ixsystems.com
Telephone	Monday - Friday, 6:00AM to 6:00PM Pacific Standard Time: US-only toll-free: 1-855-473-7449 option 2 Local and international: 1-408-943-4100 option 2
Telephone	After Hours (24x7 Gold Level Support only): US-only toll-free: 1-855-499-5131 International: 1-408-878-3140 (international calling rates apply)

Users with the S3 service enabled must upgrade CORE to version 13.0-U6 and complete the migration process before upgrading to a later major version.

This process uses MinIO credentials that might already exist. If existing credentials are inaccessible, review any solutions configured with MinIO credentials before generating new MinIO key pairs. Reconfiguring MinIO key pairs for some applications requires full redeployment of the target application, which can lead to service disruptions and data loss.

The secret key portion of a MinIO key pair cannot be viewed after initial creation. If you do not have access to the configured secret key, access the MinIO UI through the existing to generate a new key pair. Record or save the new access key and secret key in a secure location.

Reconfigure or redeploy any connected solutions to replace the previous (now defunct) key pair with the new access and secret keys before proceeding with migration.

The migration path involves installing a MinIO Client (MC) release with the required feature and function support to migrate the S3 service deployment.

Next configure the Minio plugin deployment and then migrate data from the MinIO S3 service deployment to it.

After migrating data, you can either create an archive of the TrueNAS S3 service or delete it.

After installing the MinIO Plugin, confirm the plugin starts. Then stop the MinIO plugin.

Log in to the TrueNAS CORE shell using SSH.

Copy the hidden folder minio.sys from /mnt/tank/iocage/jails/minio-jail/root/var/db/minio to the dataset created in First Steps, where minio-jail is the jail that houses the installed plugin. Enter the command cp -rp /mnt/tank/iocage/jails/minio-jail/root/var/db/minio/.minio.sys /mnt/tank/minio with the configured dataset and jail paths.

Delete the .minio.sys folder from /mnt/tank/iocage/jails/minio-jail/root/var/db/minio.

Go to Plugins, locate the MinIO plugin row, and click chevron_right to expand it. Click Mount Points to create a new mount point. Enter or click to select the new dataset, with the .minio.sys folder present, in Source. Enter or click to select the plugin jail in Destination.

The MinIO Client (MC) is a command line tool with support for both filesystems and S3-compatible cloud storage services. Install MC to facilitate data the data migration. Versions are available for Windows, Linux, and Mac.

This tutorial uses the Windows Subsystem for Linux (WSL), but any standard Linux distribution follows the same process. Users should be familiar with WSL or the standard Linux CLI interface.

Install MinIO client software version between RELEASE.2022-06-26T18-51-48Z and RELEASE.2022-10-29T10-09-23Z. Newer or older versions do not work properly.

To install the most recent compatible version of MC, enter:

curl https://dl.min.io/client/mc/release/linux-amd64/archive/mc.RELEASE.2022-10-29T10-09-23Z \
  --create-dirs \
  -o $HOME/minio-binaries/mc

chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/

After installation completes, enter mc --version to confirm the compatible MC version is installed.

Due to incompatibility between versions, MC is unable to export configuration data from the S3 service. Manually transfer configured settings to the Minio plugin to enable data migration.

1. Configure the network ports for the Minio plugin if you have not done so.

   a. Go to Jails and locate the jail matching the name entered in Jail Name during installation of the Minio plugin.

   

   b. Click chevron_right to expand details and management options.

   c. Click  STOP to stop the jail before making any changes.

   d. Click edit EDIT to open the Jails / Edit screen. Then click chevron_right to expand Network Properties.

   

   e. Edit the Host Port Number values to use any currently unused ports. Do not use the Minio plugin default ports 9000 and 9001. You must use different ports than the S3 service, which has the same default ports. Before selecting port numbers, refer to Default Ports. Record the ports used for the Minio plugin.

   f. Click Save

2. Mount the new dataset created in the First Steps section as the destination dataset on the Minio Plugin. Do not use the S3 service dataset.

   a. Go to Plugins and locate the installed Minio plugin or go to Jails and locate the jail matching the jail name entered during installation of the Minio plugin.

   b. Click chevron_right to expand MinIO details and management options.

   c. Click device_hub MOUNT POINTS and ensure configured mount point matches the destination dataset you created in First Steps. If needed, follow the instructions in Setting Up Jail Storage to mount the destination dataset.

3. Use the MinIO Console to recreate the configuration settings from the S3 service MinIO deployment in the Minio plugin deployment.

   a. Go to the MinIO web UI portal for the S3 service deployment and note existing configuration settings including users, groups, access keys, and all other MinIO settings.

   b. Go to Plugins and locate the installed Minio plugin or go to Jails and locate the jail matching the Jail Name entered during installation of the Minio plugin.

   c. Click chevron_right to expand MinIO details and management options.

   d. Click play_arrow START to start the plugin (if needed) and then click settings MANAGE to go to the MinIO Console and log in.

   e. Configure MinIO settings in the new deployment to match those of the existing deployment.

4. Use the MinIO Console to manually recreate data buckets from the existing S3 service deployment in the Minio Plugin, including rules, versioning, quotas, and locks. Bucket names do not need to be identical for this process, but your workflow can benefit from using identical names.

After installing and configuring the Minio plugin and installing the MinIO Client (MC), begin migrating data.

1. From the Linux or WSL command line, enter the command mc alias set NEWALIAS PATH ACCESSKEY SECRETKEY for both the origin MinIO service deployment and the destination Minio plugin deployment.

   

2. Enter mc mirror --preserve --watch SOURCE/BUCKET TARGET/BUCKET to begin copying data to the Minio plugin deployment.

   

   The mc mirror operation with the --watch flag does not end when the transfer completes, as it continually looks for new files added to the source. The transfer rate also does not reach 0, as it is an average throughout the operation.

   Verify the transfer completed successfully by comparing bucket size and items through the web UI of each deployment. Usage size may vary slightly due to rounding differences between versions, but the total number of objects should be the same.

   

   Use CTRL+C to end the mc mirror operation.

3. Go to Services and toggle the RUNNING S3 service to STOPPED.

4. (Optional) Edit the Minio plugin to reflect the configured port numbers matching existing MinIO clients using the process in Configuring the Minio Plugin for Migration, step one.

5. Configure access keys and secret keys for the Minio plugin deployment with any services using MinIO as a data storage target. Monitor and verify that the new deployment is operating properly.

6. (Optional) Delete the original dataset from the S3 service deployment. If storage capacity allows, we suggest retaining an archive of the original dataset, at least until you have confirmed that the plugin deployment is fully functional. After confirming full functionality, delete the original dataset from the S3 Service deployment.