Compatibility Matrix for AIStore on ais-operator
May 28, 2026 · View on GitHub
WARNING: Upgrading the operator version from < v2.0 to any version v2.0 or later WILL cause an AIS cluster restart.
When possible, the operator maintains backwards compatibility for previous AIStore versions to allow upgrades, but each aisnode version requires a certain operator version. The following matrix shows the compatible versions of AIStore (aisnode) with ais-operator.
| AIStore Version | Required Operator Version | Compatibility Notes | Release Notes |
|---|---|---|---|
| v3.21 and below | v0.x | AIS, operator | |
| v3.22 | v1.0.0 | AIS, operator | |
| v3.23 | v1.1.0 | AIS, operator | |
| v3.24 | v1.4.1 | Operator > v1.4.x required to transition from AIS v3.23 to v3.24 | AIS, operator v1.4.0, operator v1.4.1 |
| v3.25 | v1.4.1 | Operator transitioning to init-managed config, see below | AIS, operator v1.5.0 |
| v3.26 | v1.6.0 (latest >v2.0 recommended) | Requires init container compatible with v3.26 | operator v1.6.0 |
| v3.27 | v1.6.0 | AIS,operator v2.2.0 | |
| v3.28 | v1.6.0 | Operator >= v2.3.0 NOT compatible with AIS < v3.28 (recommend upgrade to > v3.28 BEFORE operator > v2.3.0) | AIS |
| v4.1 | v2.8.0 | AIS ≥ v4.1 is NOT compatible with operator < v2.8.0 (upgrade operator to > v2.8.0 first); AIS now gates readiness on cluster join, requiring publishNotReadyAddresses: true on headless SVCs for peer discovery during startup | AIS, operator v2.8.0 |
| v4.2 | v2.8.0 | AIS, operator v2.14.0 | |
| v4.3-v4.6 | v2.8.0 | AIS, operator v2.19.0 |
NOTE: We recommend and support only the latest versions of AIStore and the AIS K8s Operator.
Operator v3.0.0
This major release drops support for several deprecated features. See the operator CHANGELOG.md for details.
Removed:
- StatsD support
- Deprecated options for TLS configuration
- Deprecated options for logSidecar
- Selection by deprecated pod labels
Pod Labels
Starting with operator version v2.1.1, the operator uses K8s-standard prefixed labels.
For releases deployed with prior versions, v3.0.0 drops support for pod selection based solely on the old app and component labels.
This will result in rollout and cleanup failures if a v3.0.0 operator tries to manage a statefulset deployed with a version prior to v2.1.1.
To check an existing cluster for compatibility with operator versions v3.0.0 and above, you can use the following to check for modern labels on AIS pods:
# Update as needed to match your cluster name and namespace
kubectl get pod -n ais -l 'app.kubernetes.io/component=proxy' \
-o jsonpath='{.items[0].metadata.labels.app\.kubernetes\.io/name}{"\n"}'
kubectl get pod -n ais -l 'app.kubernetes.io/component=target' \
-o jsonpath='{.items[0].metadata.labels.app\.kubernetes\.io/name}{"\n"}'
If both of these queries return the cluster name, then the operator can be safely upgraded.
If no label exists, first upgrade to an operator version >= v2.1.1, then apply any change to the spec to sync the modern label syntax to the K8s resources.
Init container compatibility
Starting with operator version 1.6.0, we have begun to move the generation of AIS config from the operator to the init container.
These init containers will now be versioned alongside aisnode and should be updated alongside aisnode and kept in sync.
Older clusters can be upgraded to an operator with version 1.6.0, however 1.6.0 can NOT deploy new clusters with an init container using the old versioning system.
As of version 2.0, support of any v1.* init container has been dropped and the init container version must match the aisnode version.
We recommend upgrading to the latest compatible init version directly after upgrading the operator to 1.6.0.
| Operator Version | Init Container Version | AISNode Version |
|---|---|---|
| 1.5.0 | v1.2.0, v3.25 | v3.25 |
| 1.6.0 | v3.25 | v3.25 |
| 1.6.0 | v3.26 | v3.26 |
| 2.0 or later | ... | ... |
Updating the AIS K8s Operator
The AIS Operator container image should generally be updated in sync with the rest of the manifest.
Follow the deployment steps with a new version to automatically update the existing deployment.
Updating the AIS version
Make sure to update the operator before updating the AIS deployment
Follow the AIS deployment guides for your deployment type to update the nodeImage.tag in the AIStore custom resource.