Upgrade from MinIO Community Edition on Kubernetes

Use the steps in this document to upgrade a Helm-based cluster on Kubernetes using the MinIO Community Operator and Object Store Tenants to AIStor.

Upgrading from MinIO Community Edition to AIStor is permanent and cannot be reversed.

For airgapped environments or private registries, see the Airgapped environments procedure.

Verify the following requirements have been met before doing the upgrade:

1. Review the Before you begin section prior to starting the upgrade procedure.

2. This procedure is tested against Operator and Tenant installations using the MinIO Operator version 6.x.x or 7.x.x series. If you are using 5.x.x or earlier, reach out on SUBNET for further guidance or upgrade to one of the tested charts before upgrading.

3. Upgrade requires that your Kubernetes user have at least cluster-admin permissions.

   AIStor uses the ObjectStore resource where MinIO uses Tenant.

   Note that the new CRD is only available after installing the AIStor operator.

4. Use helm version to verify that you are running a supported Helm version (v3.17 or later).

   If not, upgrade Helm to a supported version before completing the procedure.

Add the AIStor Helm Repository to your local Helm configuration:

helm repo add minio https://helm.min.io

The repository contains the following charts for upgrade:

The repository also includes older charts for legacy support. This table lists only the current charts.

Refer to the operator values.yaml reference for a description of all possible options. You can run the following command to see the default values of the chart:

helm show values minio/aistor-operator

If you are fine with the default settings, then continue to downloading the AIStor license.

Do not copy the entire content and make changes. Create a new aistor-operator-values.yaml file that only contains values different from the default.

AIStor needs a license to run. Download the license from SUBNET or request a free tier license from the MinIO Pricing page.

Install the AIStor operator with your license. Replace LICENSE_HERE with your license value (beginning with eyJ...):

helm install --create-namespace --take-ownership -n aistor aistor \
     minio/aistor-operator --set license="LICENSE_HERE"

helm install --create-namespace --take-ownership -n aistor aistor \
     minio/aistor-operator --set license="LICENSE_HERE" \
     -f aistor-operator-values.yaml

helm install --create-namespace --take-ownership -n aistor aistor \
     minio/aistor-operator --set license="LICENSE_HERE"

helm install --create-namespace --take-ownership -n aistor aistor \
     minio/aistor-operator --set license="LICENSE_HERE" \
     -f aistor-operator-values.yaml

helm install --create-namespace --take-ownership -n aistor aistor \
     minio/aistor-operator --set license="LICENSE_HERE" \
     --set global.forceOpenShift=true

The AIStor operator installs to the aistor namespace.

Check if all Pods in the aistor namespace are running:

kubectl get all -n aistor

The output should show running pods similar to the following:

NAME                                         READY   STATUS    RESTARTS   AGE
pod/adminjob-operator-cfc97d9f-hjbp5         1/1     Running   0          4m16s
pod/object-store-operator-78c9f84b85-kmwlv   1/1     Running   0          4m16s

NAME                            TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/object-store-operator   ClusterIP   10.43.210.230   <none>        4221/TCP   4m16s

NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/adminjob-operator       1/1     1            1           4m16s
deployment.apps/object-store-operator   1/1     1            1           4m16s

NAME                                               DESIRED   CURRENT   READY   AGE
replicaset.apps/adminjob-operator-cfc97d9f         1         1         1       4m16s
replicaset.apps/object-store-operator-78c9f84b85   1         1         1       4m16s

If you encounter PolicyBinding ownership errors during installation, upgrade your Helm version to 3.17 or later. If you cannot update Helm, see PolicyBinding ownership errors in the troubleshooting guide.

The MinIO Operator uses a Tenant resource to manage an object-store. AIStor uses an ObjectStore resource that is compatible with but distinct from a Tenant. This procedure uses a MinIO-provided upgrade tool to convert a Tenant to an object store.

Run the following commands and save the output in a safe place:

kubectl get tenant -n $NAMESPACE $TENANT -o yaml > tenant-backup.yaml
kubectl get secrets -n $NAMESPACE -o yaml >> tenant-backup.yaml

Creating the object store using the Helm chart requires a custom aistor-objectstore-values.yaml. MinIO provides an upgrade tool that helps create this file, based on your current tenant configuration. Run the following command to generate the objectstore-values.yaml:

docker run --pull=always --rm -v ~/.kube/config:/root/.kube/config  \
       quay.io/minio/aistor/operator-migration:latest generate-helm \
           --namespace $NAMESPACE > aistor-objectstore-values.yaml

The upgrade tool needs to be able to connect to the Kubernetes cluster. Ensure the current Kubernetes context is set to the proper cluster.

If you have access to SUBNET, create a ticket and upload both the tenant-backup.yaml and the aistor-objectstore-values.yaml files. Experts at MinIO can check if the generated file is correct and ready to proceed with the next step.

The upgrade tool attempts to perform checks on manually created resources (not managed by the MinIO operator) and propose updates. For example, manually created services that may access AIStor need to be updated. The upgrade tool creates TODO items in the generated values file.

All users should review the file to review and understand all the remarks in this file.

If you encounter issues running the upgrade tool, see Upgrade tool cannot connect to cluster in the troubleshooting guide.

Delete the old Tenant resource using one of the methods below.

Deleting the Tenant disables the object store and introduces downtime. After deleting the Tenant resource, the StatefulSets, Services, and other resources will be deleted, but Persistent Volume Claims remain and will be used by the AIStor Object Store.

The object store will not be available until it is recreated using the AIStor ObjectStore resource. Always run this procedure on a staging environment to ensure you can detect and fix issues before deploying to production.

helm ls -n $NAMESPACE

helm uninstall -n $NAMESPACE RELEASE_NAME

kubectl -n $NAMESPACE delete tenant $TENANT

Use the following command to recreate the deleted tenant as an AIStor Object Store:

helm install -n $NAMESPACE $TENANT minio/aistor-objectstore -f aistor-objectstore-values.yaml --take-ownership

Use --take-ownership to make sure it can recreate existing secrets.

Check if the object store is up and running again.

kubectl -n $NAMESPACE get objectstore

The output should show Initialized.

Check that the object store is accessible, such as with mc admin info.

If the object store fails to reach Initialized status, see Object store fails to initialize after upgrade in the troubleshooting guide.

You can upgrade between OperatorHub and Helm installations using either a Helm-based approach or an OLM-based approach.

To upgrade using Helm, follow the standard upgrade procedure documented above on this page. This replaces the OperatorHub-managed operator with the Helm-managed AIStor operator, then converts Tenants to ObjectStores.

If you prefer to continue using OperatorHub/OLM instead of Helm, follow these steps:

1. Install the AIStor Operator through OperatorHub (see installation documentation)

2. Convert the Tenant resource to an ObjectStore resource using the upgrade tool

   The upgrade tool’s Tenant-to-ObjectStore conversion feature requires PR #1272 to be merged. Until then, you’ll need to manually convert the Tenant YAML to ObjectStore format.

3. Delete the existing Tenant resource (see Uninstall the old tenant section above)

4. Deploy the new ObjectStore resource

5. Verify installation (see Verify the new AIStor Object Store is running section above)

6. Uninstall the previous MinIO operator through OperatorHub

Regardless of which upgrade approach you use, be aware that the default sub-path for Helm is set to data (pods mount /export0/data), while OperatorHub installations do not set this field (data is in /export0).

When upgrading from one system to another, the object-store may appear empty or IAM may seem to be reset. This is because it is fetching data from the incorrect directory.

Although root credentials will work, IAM will seem to be reset too. When upgrading from OperatorHub to Helm, you must explicitly set the subPath to ''.

For detailed guidance on this issue, see OperatorHub to Helm subpath issues in the troubleshooting guide.