Upgrade from MinIO Community Edition in Airgapped Environments

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

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

This procedure is for environments where:

• Kubernetes nodes do not have direct internet access
• Container images must be mirrored to a private registry
• Helm charts must be obtained through alternative means
• Network restrictions prevent direct downloads from public repositories

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

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

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

   AIStor uses the ObjectStore resource where MinIO uses Tenant.

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

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

4. You have access to both:

   • A system with internet access for downloading images and charts
   • Your private container registry for mirroring images

Complete these steps on a system with internet access.

Add the AIStor Helm Repository and download the chart:

helm repo add minio https://helm.min.io
helm repo update
helm pull minio/aistor-operator --version <VERSION>

Transfer the downloaded chart file to your airgapped environment.

The AIStor operator uses several container images that must be mirrored to your private registry.

1. Identify required images:

   helm template minio/aistor-operator | grep "image:" | sort -u
   

2. Use skopeo to copy images to your private registry:

   skopeo copy docker://SOURCE_IMAGE docker://registry.example.local/TARGET_IMAGE
   

   Replace SOURCE_IMAGE with the original image reference and TARGET_IMAGE with your private registry path.

Copy the upgrade tool container to your private registry:

skopeo copy docker://quay.io/minio/aistor/operator-migration:latest \
            docker://registry.example.local/aistor/operator-migration:latest

Complete these steps in your airgapped environment.

AIStor uses custom service registry configuration to simplify operations in airgapped environments. If you are using OpenShift, then you may also use the ImageDigestMirrorSet method. This document assumes the use of the AIStor service registry method.

Create a repositories.yaml file to configure custom registries:

repositories:
  aistor:
    hostname: registry.example.local
    pathPrefix: aistor/
    # imagePullSecrets:
    # - name: aistor-pull-secret-1
    # - name: aistor-pull-secret-2

Replace registry.example.local with your private registry hostname and adjust the pathPrefix values to match your registry structure.

If your private registry requires authentication, create image pull secrets:

kubectl create secret docker-registry aistor-pull-secret-1 \
  --docker-server=registry.example.local \
  --docker-username=USERNAME \
  --docker-password=PASSWORD \
  --docker-email=EMAIL \
  -n aistor

Uncomment and configure the imagePullSecrets section in repositories.yaml to reference these secrets.

Refer to the operator values.yaml reference for a description of all possible options.

Create an aistor-operator-values.yaml file with any custom 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 using the local chart and custom registry configuration. Replace LICENSE_HERE with your license value (beginning with eyJ...):

helm install --create-namespace --take-ownership -n aistor aistor \
     ./aistor-operator-<VERSION>.tgz \
     -f repositories.yaml --set license="LICENSE_HERE"

If you created a customization file (aistor-operator-values.yaml), add it to the command:

helm install --create-namespace --take-ownership -n aistor aistor \
     ./aistor-operator-<VERSION>.tgz \
     -f repositories.yaml --set license="LICENSE_HERE" \
     -f aistor-operator-values.yaml

The Helm chart uses the repositories.yaml values to update the AIStor clusters. Because these clusters are static, if you need to redeploy with changed settings, use the following command:

helm upgrade -n aistor aistor ./aistor-operator-<VERSION>.tgz \
             -f repositories.yaml --set license="LICENSE_HERE" \
             -f aistor-operator-values.yaml

Check the output of the Helm command for the list of images to mirror.

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.

Each operator uses a dedicated configuration map that holds the service configuration for each service. The Helm script installs these configuration maps. Use the following command to view them:

kubectl get configmap -n aistor -o yaml

Check if all Pods in the aistor namespace are running:

kubectl get pods -n aistor

All pods should be in the running state after some initialization.

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

Follow the tenant upgrade procedure from the standard Kubernetes upgrade guide, with the following modifications for airgapped environments.

When running the upgrade tool, use your private registry:

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

Replace registry.example.local with your private registry hostname.

When creating your aistor-objectstore-values.yaml file, ensure that:

• All image references point to your private registry.
• Image pull secrets are configured if required.
• The repository configuration matches your repositories.yaml settings.
• Use the downloaded charts instead of the MinIO Helm repository.

All other upgrade steps remain the same as the standard Kubernetes procedure.

If the object store fails to reach Initialized status, see Object store fails to initialize after upgrade in the troubleshooting guide. In airgapped environments, this is often caused by image pull errors due to missing or incorrectly configured private registry references.