Upgrade

This section documents best practices and tutorials for updating the MinIO AIStor server on Linux and Kubernetes infrastructure to a newer release.

Every upgrade ends with the nodes restarting on the new version. Nodes keep serving requests until they restart, so how the cluster restarts decides what your applications see.

All nodes stop and start at the same time. This is the default on Linux, and it is the mode MinIO recommends.

The restart typically completes in under 3 seconds. S3 clients reconnect on their own when it does, which is ordinary HTTP behavior, so applications generally do not notice the upgrade. Most S3 SDKs also retry failed operations.

Finishing quickly is the point. The sooner every node runs the new version, the shorter the window in which the cluster runs mixed versions, and the sooner you can confirm the upgrade succeeded. Prefer this mode unless you have a specific reason not to.

Nodes restart in sequence, one at a time or in batches drawn from different fault domains, meaning groups of nodes that can fail together. Each batch must report healthy before the next one starts.

What this buys you is that the cluster is never fully down. Capacity drops by one batch at a time instead of falling to zero, so requests to the rest of the cluster keep succeeding for the whole upgrade. Choose this mode when a total interruption is unacceptable even for a few seconds, or when your clients cannot retry.

It does not spare every client a reconnection. A load balancer routes new requests to the nodes that are still up, but it cannot move a connection that is already open, so clients attached to the restarting node reconnect and land on a healthy node. A rolling restart also takes considerably longer than a simultaneous restart, and it requires a load balancer.

On Linux, pass --rolling to either mc admin update or mc admin service restart.

On Kubernetes, the AIStor Operator performs a rolling restart without being asked, and gives each pod 600 seconds to drain. Change that period with rollingTimeoutSeconds in the ObjectStore specification.

Draining is the wait before a node stops, during which it finishes the requests it is already handling. The period is a ceiling, not a promise: when it expires the node closes whatever is still open, so a request that runs longer than the period is cut off. Size the period for your longest normal request, such as a large multipart upload.

Put a load balancer in front of the cluster and point it at the /minio/health/ready endpoint on each node. Configure it to treat any response other than 200 OK as not ready, so it stops sending new requests to a node that is about to restart and resumes once the node reports healthy again.

Do not key the check on a response header instead. A node about to restart answers 503 Service Unavailable with no X-Minio-Server-Status header, but a deployment running on an expired license sets license-readonly on its 503 as well, so the header does not reliably distinguish the two.

Point your mc alias at the load balancer rather than at a single node, because an alias that names one node loses its connection when that node restarts.

Without a load balancer, every client keeps trying the node that is restarting instead of being sent to a healthy one, which removes the availability a rolling restart exists to provide.

Both restart modes leave the cluster running two versions at once, a rolling restart for longer than a simultaneous one. This is expected and the cluster operates normally throughout.

What ends the window is the API version bump. By default the cluster leader advances the API version as soon as every node is online and supports the newer one, or after one hour if a node stays absent. Once the bump commits, downgrading the server binary is no longer safe, so it is the point of no return for the upgrade.

To hold that point open deliberately, see Retain a rollback window with a bake time.

Use the following commands to back up your cluster settings before starting the decommissioning process:

• mc admin cluster bucket export
• mc admin cluster iam export
• mc admin config export

You can use these snapshots to restore bucket, IAM, and cluster settings to recover from user or process errors as necessary.

The Release Notes page provides a reference for identifying the changes applied in each release. Review the associated release notes between your current MinIO AIStor version and the newer release so you have a complete view of any changes.

Pay particular attention to any releases that are not backwards compatible. You cannot trivially downgrade from any such release.

Each release also publishes SBOM and dependency artifacts. Compare CycloneDX or SPDX SBOMs between your current and target versions to identify dependency changes and review any newly introduced components before upgrading.

MinIO AIStor uses a testing and validation suite as part of all releases. However, no testing suite can account for unique combinations and permutations of hardware, software, and workloads of your production environment.

You should always validate any MinIO AIStor upgrades in a lower environment (Dev/QA/Staging) before applying those upgrades to Production clusters, or any other environment containing critical data. Performing updates to production environments without first validating in lower environments is done at your own risk.

For MinIO AIStor clusters that are significantly behind latest stable (6+ months), consider using MinIO SUBNET for additional support and guidance during the upgrade procedure.

For clusters on Windows or macOS, you can upgrade the Server at any time by performing a binary replacement on the server and restarting the process.

For clusters in a container such as Podman or Docker, use the relevant pull command to retrieve the latest image and restart your container process. If you have pinned to a specific container image, replace that image with the latest release RELEASE.2026-04-11T03-20-12Z

System maintenance operations such hardware, firmware, or OS upgrades may require minutes or hours to complete during which all software running on that host is unavailable. For upgrade procedures that require longer periods of downtime, use a rolling upgrade pattern at the host level to take one or more systems offline at a time. MinIO AIStor erasure coding supports availability if one or more nodes require downtime during system maintenance.

The number of hosts you can safely take offline depends on the erasure code stripe and parity used for deploying the cluster. For example, consider a cluster with 8 servers and 8 drives each with a stripe size of 8 and parity of 3. As per the erasure code calculator, the cluster can tolerate up to 3 server failures while maintaining read and write quorum. Taking 2 nodes down at a time ensures a buffer of 1 additional node which could fail incidentally while maintaining cluster operations.

Certain architectures, such as rack-aware clusters, may support taking a larger number of hosts down for maintenance at once. Consult with MinIO support using SUBNET before conducting maintenance operations for additional oversight and guidance.

MinIO AIStor supports downgrading to previous versions, except where explicitly stated otherwise. Any features, improvements, or APIs not supported in the previous versions become unavailable upon downgrade. Take precautions to coordinate with any client applications before committing to a downgrade operation.

A fully upgraded cluster bumps the API version immediately once all nodes are online and support the newer version, which leaves no window to roll back after a clean upgrade. Set MINIO_API_BUMP_BAKE_TIME to a duration, for example 1h, on every node to hold the previous API version for that long after the cluster is fully upgraded before committing the bump.

During the bake time, the cluster continues to write data in the previous version’s format, so downgrading the server binary remains safe. This mirrors the bake time of a blue/green deployment: the older release stays recoverable until the window elapses, after which the bump commits automatically and the switch becomes permanent.

The default is 0, which bumps immediately. Because new API-version features stay inactive until the bump commits, a longer bake time also delays their availability. To wait out the bake time, keep all nodes online on the newer release for the configured duration; the cluster commits the bump on its own once the window passes.

The bake time applies only while every node is online. While a node is absent, the cluster applies its one-hour tolerance for absent nodes instead of the bake time, and commits the bump once the cluster has held that state for an hour. The clock restarts whenever the versions the nodes report change, including a node going offline or coming back, so the hour is measured from the last such change rather than from the end of the upgrade.

A bake time longer than an hour therefore does not survive an absent node: the rollback window closes after that hour. If you need a rollback window that does not depend on every node staying online, set MINIO_API_AUTO_BUMP=off before upgrading and bump the version yourself with mc admin update ALIAS --bump-api when you are ready.

MinIO AIStor supports upgrading a cluster from the open-source MinIO on Linux, Kubernetes, or airgapped environments. Upgrade procedures guide you through replacing the server binary, adding the license, updating Custom Resource Definitions, and restarting the cluster on MinIO AIStor.

For detailed procedures, see Upgrade from open-source MinIO.

On Linux, follow Upgrade MinIO AIStor on Linux.

On Kubernetes, the procedure depends on how images reach the cluster:

• Public registries for a cluster that pulls from the internet.
• Private registry for a cluster that pulls from your own registry.
• Airgapped for a cluster with no route to either.
• Helm if you deployed with the Helm chart.

Moving from open-source MinIO rather than upgrading AIStor is a separate procedure with its own downtime considerations. See Upgrade from open-source MinIO.