Upgrade MinIO AIStor on Kubernetes with Private Registry

Upgrade MinIO AIStor Helm clusters that use a private container registry but have internet access to helm.min.io for chart updates.

If your cluster uses public registries or is in an airgapped environment, see:

• Upgrade with Public Registries
• Upgrade in Airgapped Environment

Overview

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

When you use a private registry, copy the container images to that registry before you deploy the chart updates.

The AIStor Operator upgrades an object store one pod at a time, so the cluster keeps serving requests for the whole upgrade. Each pod finishes the requests it is already handling before it stops, up to the number of seconds set in rollingTimeoutSeconds, which defaults to 600. A request still running when that period expires is cut off, so raise the value if your workload has requests longer than ten minutes.

Clients connected to a pod that restarts do reconnect, and a load balancer sends them to a pod that is still running. Most S3 SDKs retry failed operations, so applications generally do not surface an error.

Upgrading to or from a release earlier than RELEASE.2025-12-20T04-58-37Z replaces every pod at once instead, which stops the cluster until the pods come back.

For how this compares with restarting every node at once, and how to choose between them on Linux, see Choose a restart mode.

Prerequisites

Complete all standard upgrade prerequisites, then prepare the following for your private registry environment:

• Verify you have network access to helm.min.io and quay.io
• Verify you have credentials and push access to your private container registry
• Ensure your Kubernetes cluster has pull access configured for your private registry
• Verify that image pull secrets exist in the aistor namespace with valid credentials:

  kubectl get secret -n aistor private-repo-pull-secret

  If the secret does not exist or credentials have changed, recreate it before upgrading

Step 1. Copy operator image to private registry

Before upgrading the operator chart, copy the new operator image to your private registry.

1. Copy the operator image.

   Use skopeo or a similar tool to copy the image:

   skopeo copy --override-os linux --override-arch amd64 \
     docker://quay.io/minio/aistor/operator:RELEASE.2025-XX-XXT00-00-00Z \
     docker://PRIVATE_REGISTRY/aistor/operator:RELEASE.2025-XX-XXT00-00-00Z

   Replace:

   • RELEASE.2025-XX-XXT00-00-00Z with your target operator version
   • PRIVATE_REGISTRY with your registry hostname

Step 2: Upgrade the operator chart

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 with your private registry configuration:

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

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

   Ensure your aistor-operator-values.yaml file contains the repositories configuration pointing to your private registry. For example:

   repositories:
     aistor:
       hostname: PRIVATE_REGISTRY
       pathPrefix: aistor/
       imagePullSecrets:
       - name: private-repo-pull-secret
     minio:
       hostname: PRIVATE_REGISTRY
       pathPrefix: minio/
       imagePullSecrets:
       - name: private-repo-pull-secret

   Replace PRIVATE_REGISTRY with the hostname of your private container registry (for example, registry.example.com or registry.example.com:5000).

   If you need to override specific image versions, add an images section:

   images:
     operator:
       repository: aistor
       image: operator:RELEASE.2025-XX-XXT00-00-00Z

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

Step 3: Copy object store images to private registry

Before upgrading the object store chart, copy the required images to your private registry.

1. Copy the core object store images.

   Copy the main MinIO AIStor images:

   skopeo copy --override-os linux --override-arch amd64 \
     docker://quay.io/minio/aistor/minio:RELEASE.2025-XX-XXT00-00-00Z \
     docker://PRIVATE_REGISTRY/aistor/minio:RELEASE.2025-XX-XXT00-00-00Z
   
   skopeo copy --override-os linux --override-arch amd64 \
     docker://quay.io/minio/aistor/minio-sidecar:RELEASE.2025-XX-XXT00-00-00Z \
     docker://PRIVATE_REGISTRY/aistor/minio-sidecar:RELEASE.2025-XX-XXT00-00-00Z

   Replace:

   • RELEASE.2025-XX-XXT00-00-00Z with your target version
   • PRIVATE_REGISTRY with your registry hostname

2. Copy optional images.

   If you use additional features, copy those images as well:

   # KES (Key Encryption Service)
   skopeo copy --override-os linux --override-arch amd64 \
     docker://quay.io/minio/aistor/kes:RELEASE.2025-XX-XXT00-00-00Z \
     docker://PRIVATE_REGISTRY/aistor/kes:RELEASE.2025-XX-XXT00-00-00Z
   
   # MinIO Client (mc)
   skopeo copy --override-os linux --override-arch amd64 \
     docker://quay.io/minio/aistor/mc:RELEASE.2025-XX-XXT00-00-00Z \
     docker://PRIVATE_REGISTRY/aistor/mc:RELEASE.2025-XX-XXT00-00-00Z
   
   # WARP (benchmarking tool)
   skopeo copy --override-os linux --override-arch amd64 \
     docker://quay.io/minio/aistor/warp:RELEASE.2025-XX-XXT00-00-00Z \
     docker://PRIVATE_REGISTRY/aistor/warp:RELEASE.2025-XX-XXT00-00-00Z

Step 4: Upgrade the object store chart

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

objectStore:
  name: primary-object-store
  pools:
  - name: pool-0
    servers: 8
    volumesPerServer: 8
    size: 2Ti
  services:
    minio:
      serviceType: NodePort
      nodePort: 31000

objectStore:
  image:
    repository: PRIVATE_REGISTRY/aistor/minio
    tag: RELEASE.2025-XX-XXT00-00-00Z

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.

   Starting with RELEASE.2026-04-11T03-20-12Z, the cluster leader automatically advances the cluster to the latest API version after a rolling upgrade that changes the API version. By default, 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.

   Starting with RELEASE.2026-07-24T16-43-31Z, you can delay the bump. Set MINIO_API_BUMP_BAKE_TIME on all nodes to a duration, for example 1h, to configure a bake time. The cluster then holds the previous API version for that long after it is fully upgraded. The bump commits once all nodes have stayed online on the newer release for that duration. The bake time applies only while every node is online. If a node drops out, the cluster commits the bump once the remaining quorum has held the newer release for one hour, however long a bake time you configured, so a longer rollback window depends on keeping every node online for it. During the bake time, the cluster keeps writing data in the previous version’s format, so downgrading the server binary remains safe. The default is 0, which commits the bump immediately. Features that require the new API version stay inactive until the bump commits, so a longer bake time also delays their availability.

   When upgrading to a release earlier than RELEASE.2026-04-11T03-20-12Z, 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.

   To keep a bounded rollback window, set MINIO_API_BUMP_BAKE_TIME to a duration on all nodes before upgrading. For recovery steps when a node fails to start due to an API version mismatch, see API version startup errors.

Upgrade only the object store image

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. Copy the new image.

   Copy the new image version to your private registry:

   skopeo copy --override-os linux --override-arch amd64 \
     docker://quay.io/minio/aistor/minio:RELEASE.2026-09-19T17-05-25Z \
     docker://PRIVATE_REGISTRY/aistor/minio:RELEASE.2026-09-19T17-05-25Z

   Replace the tag with your target release version and PRIVATE_REGISTRY with your registry hostname.

2. Update the values file.

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

   objectStore:
     image:
       repository: PRIVATE_REGISTRY/aistor/minio
       tag: RELEASE.2026-09-19T17-05-25Z

3. 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

4. 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. Confirm they reference your private registry with the new tag.

5. Bump the API version.

   Starting with RELEASE.2026-04-11T03-20-12Z, the cluster leader automatically advances the cluster to the latest API version after a rolling upgrade that changes the API version. By default, 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.

   Starting with RELEASE.2026-07-24T16-43-31Z, you can delay the bump. Set MINIO_API_BUMP_BAKE_TIME on all nodes to a duration, for example 1h, to configure a bake time. The cluster then holds the previous API version for that long after it is fully upgraded. The bump commits once all nodes have stayed online on the newer release for that duration. The bake time applies only while every node is online. If a node drops out, the cluster commits the bump once the remaining quorum has held the newer release for one hour, however long a bake time you configured, so a longer rollback window depends on keeping every node online for it. During the bake time, the cluster keeps writing data in the previous version’s format, so downgrading the server binary remains safe. The default is 0, which commits the bump immediately. Features that require the new API version stay inactive until the bump commits, so a longer bake time also delays their availability.

   When upgrading to a release earlier than RELEASE.2026-04-11T03-20-12Z, 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.

   To keep a bounded rollback window, set MINIO_API_BUMP_BAKE_TIME to a duration on all nodes before upgrading. For recovery steps when a node fails to start due to an API version mismatch, see API version startup errors.