Migrate from Gateway or Filesystem Mode
Background
The MinIO Gateway and the related filesystem mode entered a feature freeze in July 2020. In February 2022, MinIO announced the deprecation of the MinIO Gateway. Along with the deprecation announcement, MinIO also announced that the feature would be removed in six months time.
As of https://github.com/minio/minio/releases/tag/RELEASE.2022-10-29T06-21-33Z, the MinIO Gateway and the related filesystem mode code have been removed. Deployments still using the standalone or filesystem MinIO modes that upgrade to MinIO Server https://github.com/minio/minio/releases/tag/RELEASE.2022-10-29T06-21-33Z or later receive an error when attempting to start MinIO.
Overview
To upgrade to a https://github.com/minio/minio/releases/tag/RELEASE.2022-10-29T06-21-33Z or later, those who were using the standalone or filesystem deployment modes must create a new Single-Node Single-Drive deployment and migrate settings and content to the new deployment.
This document outlines the steps required to successfully launch and migrate to a new deployment.
Important
Standalone/file system mode continues to work on any release up to and including MinIO Server RELEASE.2022-10-24T18-35-07Z. To continue using a standalone deployment, install that MinIO Server release with MinIO Client RELEASE.2022-10-29T10-09-23Z or any earlier release with its corresponding MinIO Client. Note that the version of the MinIO Client should be newer and as close as possible to the version of the MinIO server.
Procedure
Note
You can set MinIO configuration settings in environment variables and using mc admin config set
.
Depending on your current deployment setup, you may need to retrieve the values for both.
This procedure does not cover migrating environment variables due to the variety of configuration methods.
You can examine any runtime settings using env | grep MINIO_
or, for deployments using MinIO’s systemd service, check the contents of /etc/default/minio
.
Create a new Single-Node Single-Drive MinIO deployment
Refer to the documentation for step-by-step instructions for launching a new SNSD deployment.
The location of the deployment can be any empty folder on the storage medium of your choice. A new folder on the same drive can work for the new deployment as long as the existing deployment is not on the root of a drive. If the existing standalone system points to the root of the drive, you must use a separate drive for the new deployment.
Set the port to a custom point different than the existing standalone deployment.
Add an alias for the new deployment with
mc alias set
with the new MinIO Client from the previous stepmc alias set NEWALIAS PATH ACCESSKEY SECRETKEY
Use the new MinIO Client.
Replace
NEWALIAS
with the alias to create for the deployment.Replace
PATH
with the IP address or hostname and port for the new deployment.Replace
ACCESSKEY
andSECRETKEY
with the credentials you used when creating the new deployment.
Export the existing deployment’s configurations
Use the
mc admin config export
export command with the existing MinIO Client to retrieve the configurations defined for the existing standalone MinIO deployment.mc admin config export ALIAS > config.txt
Use the existing MinIO Client.
Replace
ALIAS
with the alias used for the existing standalone deployment you are retrieving values from.
Import configurations from existing standalone deployment to new deployment with the new MinIO Client
mc admin config import ALIAS < config.txt
Use the new MinIO Client.
Replace
ALIAS
with the alias for the new deployment.
Restart the server for the new deployment with the new MinIO Client
mc admin service restart ALIAS
Use the new MinIO Client.
Replace
ALIAS
with the alias for the new deployment.
Export bucket metadata from existing standalone deployment with the existing MinIO Client
The following command exports bucket metadata from the existing deployment to a
.zip
file.The data includes:
bucket targets
lifecycle rules
notifications
quotas
locks
versioning
The export includes the bucket metadata only. No objects export from the existing deployment with this command.
mc admin cluster bucket export ALIAS
Use the existing MinIO Client.
Replace
ALIAS
with the alias for your existing deployment.
This command creates a
cluster-metadata.zip
file with metadata for each bucket.Import bucket metadata to the new deployment with the new MinIO Client
The following command reads the contents of the exported bucket
.zip
file and creates buckets on the new deployment with the same configurations.mc admin cluster bucket import ALIAS cluster-metadata.zip
Use the new MinIO Client.
Replace
ALIAS
with the alias for the new deployment.
The command creates buckets on the new deployment with the same configurations as provided by the metadata in the .zip file from the existing deployment.
(Optional) Duplicate tiers from existing standalone deployment to new deployment with the existing MinIO Client
Use
mc ilm tier ls
with the--json
flag to retrieve a list of the tiers that exist on the standalone deployment.mc ilm tier ls ALIAS --json
Use the existing MinIO Client.
Replace
ALIAS
with the alias for the existing standalone deployment.
Use the list to recreate the tiers on the new deployment.
Export IAM settings from the existing standalone deployment to new deployment with the existing MinIO Client
If you are using an external identity and access management provider, recreate those settings in the new deployment along with all associated policies.
Use the following command to export IAM settings from the existing deployment. This command exports:
Groups and group mappings
STS users and STS user mappings
Policies
Users and user mappings
mc admin cluster iam export ALIAS
Use the existing MinIO Client.
Replace
ALIAS
with the alias for your existing deployment.
This command creates a
ALIAS-iam-info.zip
file with IAM data.Import the IAM settings to the new deployment with the new MinIO Client:
Use the exported file to create the IAM setting on the new deployment.
mc admin cluster iam import ALIAS alias-iam-info.zip
Use the new MinIO Client.
Replace
ALIAS
with the alias for the new deployment.Replace the name of the zip file with the name for the existing deployment’s file.
Use
mc mirror
with the--preserve
and--watch
flags on the standalone deployment to move objects to the new SNSD deployment with the existing MinIO Clientmc mirror --preserve --watch SOURCE/BUCKET TARGET/BUCKET
Use the existing MinIO Client.
Replace
SOURCE/BUCKET
with the alias and a bucket for the existing standalone deployment.Replace
TARGET/BUCKET
with the alias and corresponding bucket for the new deployment.
Stop writes to the standalone deployment from any S3 or POSIX client
Wait for
mc mirror
to complete for all buckets for any remaining operationsStop the server for both deployments
Restart the new MinIO deployment with the ports used for the previous standalone deployment
Refer to step four in the deploy SNSD documentation.
Ensure you apply all environment variables and runtime configuration settings, and validate the behavior.