Upgrade AIStor on Kubernetes with Private Registry

This page describes how to upgrade AIStor Helm deployments that use a private container registry but have internet access to helm.min.io for chart updates.

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

Overview

AIStor Helm upgrades involve updating two components:

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

When using a private registry, you must copy container images to your registry before deploying the chart updates. This page covers the complete upgrade workflow for private registry deployments.

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

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 AIStor Object Store onto Kubernetes.

Downgrades or rollbacks are not guaranteed due to potentially breaking changes in underlying resources like the AIStor CustomResourceDefinition.

  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-objectstore-operator \
  --set license="eyJhbGciOiJFUzM4NCIsInR..." \
  -f aistor-objectstore-operator-values.yaml

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

    Ensure your aistor-objectstore-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 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

# AI Hub (if using AI features)
skopeo copy --override-os linux --override-arch amd64 \
  docker://quay.io/minio/aistor/aihub:RELEASE.2025-XX-XXT00-00-00Z \
  docker://PRIVATE_REGISTRY/aistor/aihub:RELEASE.2025-XX-XXT00-00-00Z

# Prompt (if using AI features)
skopeo copy --override-os linux --override-arch amd64 \
  docker://quay.io/minio/aistor/prompt:RELEASE.2025-XX-XXT00-00-00Z \
  docker://PRIVATE_REGISTRY/aistor/prompt: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 AIStor Object Store instances.

Downgrades or rollbacks are not guaranteed due to potentially breaking changes in the AIStor Object Store.

  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

You must pass in your existing chart values file to ensure your customized settings are preserved during the upgrade.

Your values file should already contain the repositories configuration from your initial installation. The Helm chart automatically references images from these repositories. For example:

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

The operator uses the repositories configuration from the operator values file to determine where to pull images. If you need to override specific image versions in the object store deployment, you can add image overrides:

objectStore:
  image:
    repository: aistor  # References repositories.aistor
    image: minio:RELEASE.2025-XX-XXT00-00-00Z
  sidecar:
    image:
      repository: aistor  # References repositories.aistor
      image: minio-sidecar: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 deployment is healthy.

Upgrade only the object store image

If you want to update only the AIStor Object Store 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.2025-05-30T11-03-39Z \
  docker://PRIVATE_REGISTRY/aistor/minio:RELEASE.2025-05-30T11-03-39Z

    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.2025-05-30T11-03-39Z

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

    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.