Upgrade MinIO AIStor on Kubernetes with Public Registries

This page describes how to upgrade MinIO AIStor Helm clusters that use public registries and have direct internet access to helm.min.io and quay.io.

If your cluster uses a private container registry or is in an airgapped environment, see:

• Upgrade with Private Registry
• Upgrade in Airgapped Environment

MinIO AIStor Helm upgrades involve updating two components:

1. Operator Chart - Controls CustomResourceDefinitions and core operator resources
2. Object Store Chart - Deploys and manages the MinIO AIStor instances

You can upgrade both components together or independently. This page covers the complete upgrade workflow for standard clusters with internet access.

All MinIO AIStor software supports non-disruptive upgrades with zero downtime. In optimal environments, cluster-wide upgrades typically complete in under 500 milliseconds with large clusters (1000+ nodes) completing in less than 5 seconds.

S3 SDKs and applications typically implement retry mechanisms that mitigate the impact of any reduced availability.

Complete all standard upgrade prerequisites, then verify you have network access to helm.min.io and quay.io.

The operator chart provides the core resources for deploying MinIO AIStor onto Kubernetes.

1. Verify the existing installation.

   Check the health and status of the operator:

   kubectl get all -n aistor
   

2. Update and upgrade the operator.

   Update the Helm repository:

   helm repo update minio
   

   Upgrade the operator chart:

   helm upgrade -n aistor aistor minio/aistor-operator \
     --set license="eyJhbGciOiJFUzM4NCIsInR..."
   

   Replace the license value with your decoded JWT token from SUBNET.

3. Validate the installation by running the following command:

   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
   

The object store chart deploys and manages your MinIO AIStor instances.

1. Verify the existing installation.

   Check the health and status of your object store:

   kubectl get all -n OBJECT-STORE-NAMESPACE
   

   Replace OBJECT-STORE-NAMESPACE with your object store’s namespace.

2. Update the Helm repository.

   Update the Helm repository to get the latest chart version:

   helm repo update minio
   

3. Upgrade the object store chart.

   Use helm upgrade to deploy the updated chart:

   helm upgrade -n OBJECT-STORE-NAMESPACE OBJECT-STORE-NAME minio/aistor-objectstore \
     -f aistor-objectstore-values.yaml
   

   Replace:

   • OBJECT-STORE-NAMESPACE with your object store’s namespace
   • OBJECT-STORE-NAME with your object store’s Helm release name
   • aistor-objectstore-values.yaml with the path to your values file

1. Validate the object store upgrade.

   Confirm the object store pods are running with the new version:

   kubectl get all -n OBJECT-STORE-NAMESPACE
   

   Check the pods are ready and the cluster is healthy.

2. Bump the API version.

   After a rolling upgrade that changes the API version, the cluster leader automatically advances the cluster to the latest API version. The bump happens immediately once all nodes are online and support the latest version. If some nodes are temporarily absent, the cluster tolerates their absence for up to one hour before committing the bump.

   Automatic bumping is enabled by default. To disable it and manage the API version manually, set MINIO_API_AUTO_BUMP=off on the server before upgrading. When automatic bumping is disabled, run the following command once all nodes are running the new version:

   mc admin update ALIAS --bump-api
      

   Replace ALIAS with the alias of the MinIO AIStor deployment.

   This command is a one-time operation per upgrade and does not restart the cluster. It ensures all nodes in the cluster agree on the same API version after the binary update.

   An API version bump is irreversible

   Bumping the API version is a one-way operation. Once the version is bumped, whether automatically or with mc admin update ALIAS --bump-api, you cannot roll it back, and downgrading the server binary is only possible if the API version has never been bumped. Running an older binary after a bump fails to start with an unsupported API version error.

   If you need to retain the ability to downgrade, set MINIO_API_AUTO_BUMP=off before upgrading so the version is not bumped automatically. For recovery steps when a node fails to start due to an API version mismatch, see API version startup errors.

If you want to update only the MinIO AIStor binary version without upgrading the chart itself, you can specify a new image tag. This approach keeps your existing chart version but updates the running software.

1. Update the values file.

   Edit your aistor-objectstore-values.yaml file and update the image tag:

   objectStore:
     image:
       repository: quay.io/minio/aistor/minio
       tag: RELEASE.2025-05-30T11-03-39Z
   

   Replace the tag with your target release version.

2. Deploy the image update.

   Apply the updated configuration:

   helm upgrade -n OBJECT-STORE-NAMESPACE OBJECT-STORE-NAME minio/aistor-objectstore \
     -f aistor-objectstore-values.yaml
   

3. Validate the cluster.

   Verify the pods are running with the new image:

   kubectl get pods -n OBJECT-STORE-NAMESPACE -o jsonpath='{.items[*].spec.containers[?(@.name=="minio")].image}'
   

   This command displays the image versions running in your pods.

4. Bump the API version.

   After a rolling upgrade that changes the API version, the cluster leader automatically advances the cluster to the latest API version. The bump happens immediately once all nodes are online and support the latest version. If some nodes are temporarily absent, the cluster tolerates their absence for up to one hour before committing the bump.

   Automatic bumping is enabled by default. To disable it and manage the API version manually, set MINIO_API_AUTO_BUMP=off on the server before upgrading. When automatic bumping is disabled, run the following command once all nodes are running the new version:

   mc admin update ALIAS --bump-api
      

   Replace ALIAS with the alias of the MinIO AIStor deployment.

   This command is a one-time operation per upgrade and does not restart the cluster. It ensures all nodes in the cluster agree on the same API version after the binary update.

   An API version bump is irreversible

   Bumping the API version is a one-way operation. Once the version is bumped, whether automatically or with mc admin update ALIAS --bump-api, you cannot roll it back, and downgrading the server binary is only possible if the API version has never been bumped. Running an older binary after a bump fails to start with an unsupported API version error.

   If you need to retain the ability to downgrade, set MINIO_API_AUTO_BUMP=off before upgrading so the version is not bumped automatically. For recovery steps when a node fails to start due to an API version mismatch, see API version startup errors.