Milvus 3.0 Upgrade From 2.x: What Breaks, What Is Opt-In

The guides for all five deployment shapes (cluster on Helm, cluster on the Operator, standalone on Helm, standalone on the Operator, standalone on Docker Compose) describe the same operation: change the image, leave everything else alone. What varies is what "everything else" includes. Five conditions gate the procedure.

Start by writing down what you have: the chart version you must not change is a value you read out of Helm, not your repository.

# Cluster, Helm path.
helm get values <release-name> \
  --namespace <namespace> \
  --all > milvus-values-before-upgrade.yaml

kubectl get pods --namespace <namespace>

# Read the CHART column, strip the 'milvus-' prefix, and use the rest as <current-chart-version>.
helm list --namespace <namespace>

The upgrade pins the chart to that captured value and changes only the tag. --reset-then-reuse-values keeps your existing values while the override lands on top.

# Prerequisite per the docs: Helm 3.14.0 or later.
# Keep the chart version you already have. Change only the image tag.
helm upgrade <release-name> zilliztech/milvus \
  --namespace <namespace> \
  --version <current-chart-version> \
  --set image.all.tag="v3.0.1" \
  --reset-then-reuse-values \
  --wait \
  --timeout 30m

# The standalone page is identical except for --timeout 20m.

The Operator path carries a trap of its own. Apply the complete Milvus custom resource, not an image-only merge patch, because the Operator can default omitted zero-replica component fields and re-enable a component the existing 2.6.x deployment had disabled. That is how a cluster running MixCoord with IndexNode at zero replicas acquires an IndexNode during a tag change.

# Back up the live CR first.
kubectl get milvus <instance-name> \
  --namespace <namespace> \
  --output yaml > milvus-before-upgrade.yaml

# Apply the COMPLETE CR, never an image-only merge patch. Excerpt showing the fields to confirm:
# apiVersion: milvus.io/v1beta1
# kind: Milvus
# metadata:
#   name: <instance-name>
#   namespace: <namespace>
# spec:
#   components:
#     image: milvusdb/milvus:v3.0.1
#     indexNode:
#       replicas: 0

kubectl apply --filename milvus.yaml

kubectl get milvus <instance-name> \
  --namespace <namespace> \
  --output jsonpath='{.status.status}{"\t"}{.status.currentImage}{"\n"}'

Standalone Docker Compose follows the same rule: copy the file aside, change only the image on the standalone service to milvusdb/milvus:v3.0.1, then docker compose pull standalone and docker compose up --detach standalone.

Pick v3.0.1 as the target rather than 3.0.0. Beyond the Storage V3 and index fixes below, 3.0.1 fixed unauthenticated access through streaming gRPC calls on the external proxy port, which is the kind of version-floor argument we work through in self-hosted vector database security hardening.

The two paragraphs that decide this upgrade live in different documents.

The 3.0.0 release note, under compatibility and behavior notes, states that "2.6 to 3.0 compatibility and rollback are guaranteed" and that "a 3.0 deployment can be rolled back to 2.6. However, once you enable or use features that change the serialized data format (for example Storage V3), rollback is no longer possible."

All five upgrade guides carry an identical paragraph: "This procedure does not validate a downgrade or rollback by changing the Milvus image back to 2.6.x. After v3.0.x writes data, an image-only rollback can fail to read the updated state. If the upgrade fails, stop writes and use a recovery plan that restores the pre-upgrade metadata and persistent data backups. Validate the recovery plan in a non-production environment first."

They are not contradictory, and the distinction is the safety argument. The release note is a claim about the format: 2.6 can read what an unmodified 3.0 deployment wrote. The guide is a claim about the operation, which nobody validated. A format guarantee does not make an untested procedure safe, so plan against the guide.

The 3.0.1 notes show the gap is not theoretical. One fix reads: "Fixed rebuilt or compacted nested HYBRID indexes with high-cardinality data becoming unreadable after rollback to an older version." That is the guides' failure mode, patched in the first patch release.

The second trap is circular. The 3.0.0 release note lists Snapshot among the features that depend on Storage V3, so taking a 3.0 Snapshot as pre-upgrade insurance is the act that closes the rollback door. Two vendor sources disagree: the "features that require Storage V3" table on the architecture page lists four entries (the Vortex file format, TEXT fields, Function-generated vector fields and External collections) without Snapshot, and the snapshots user guide never mentions Storage V3 or useLoonFFI. Take the stricter reading. Your insurance is an external backup of metadata and persistent data, which is what every upgrade guide asks for.

Storage V3, internally called Loon, is manifest-based columnar storage on object storage, and it ships off: common.storage.useLoonFFI: false on line 1086 of the config at tag v3.0.1, with common.storage.enableGrowingSourceFlush: false beneath it and dataNode.storage.format: parquet on line 949 offering vortex as the alternative. The architecture page carries a beta marker for Milvus 3.0.x.

Two statements on that page decide whether to touch it at all. "Enable Storage V3 to use features that depend on it, rather than as a general performance optimization." And: "Once Milvus writes data in Storage V3, downgrading to a Milvus version that cannot read Storage V3 is not supported. Disabling Storage V3 later does not immediately convert all existing Storage V3 data or restore compatibility with the older version."

The mechanism behind the second changes how you plan the change window: "After common.storage.useLoonFFI takes effect, new writes and compaction output use Storage V3. Existing data remains in its current layout until eligible data is rewritten by background compaction. Milvus can read both layouts during this transition." So the door never slams. It closes segment by segment on compaction's schedule, which makes your rollback position a window narrowing at a rate nobody has published. That is the same background machinery whose limits we mapped for deletion in vector database GDPR erasure and HNSW soft deletes.

Enablement itself is three lines, plus the two compaction switches the page asks for when you add a Function and its generated vector field to an existing collection.

# Source: the Storage V3 architecture page.
# This is the one-way door. Read the rollback section of this post before applying it.
common:
  storage:
    useLoonFFI: true

# Only if you will add a Function and its generated vector field to an EXISTING collection:
dataCoord:
  compaction:
    bumpSchemaVersion:
      enabled: true
    storageVersion:
      enabled: true

One of those keys deserves a warning. dataCoord.compaction.storageVersion.enabled is described as enabled by default on the architecture page, and a grep of configs/milvus.yaml at tag v3.0.1 finds no storageVersion key in the file. It is documented behaviour you cannot confirm from the shipped defaults.

For a Helm deployment every key above travels the same route: chart milvus-5.0.27's values.yaml describes extraConfigFiles.user.yaml as merging into milvus.yaml at top priority over the image and chart defaults. The first value to send through it is not true but an explicit false. The release note says Storage V3 will be enabled by default in a later release, and the pin stops a future image or chart bump deciding that for you.

# Chart 5.0.27 values.yaml: this config merges into milvus.yaml and is top priority
# over the image and chart defaults. Pin the flag rather than inheriting a default.
extraConfigFiles:
  user.yaml: |+
    common:
      storage:
        useLoonFFI: false

The 3.0.0 release note states: "New index versions are opt-in for now. Newly introduced index algorithms require manually raising the target index version (dataCoord.targetVecIndexVersion to 10, dataCoord.targetScalarIndexVersion to 4) before they take effect; a later release will enable them by default."

Here is what the server ships.

Two of those five keys are the ones you are told to change, and they are the two with no entry in the reference. A search across the English documentation set finds targetVecIndexVersion and targetScalarIndexVersion exactly once, on the release notes page. The DataCoord reference documents dataCoord.autoUpgradeSegmentIndex and says nothing about either target, so the release note is the specification.

The comment block shipped above the keys explains why raising them can change nothing. It states that if forceRebuildSegmentIndex is enabled the vector index will be rebuilt to align with targetVecIndexVersion, and that if it is not enabled the newly created vector index aligns with whichever is newer of the index engine's version and targetVecIndexVersion. The scalar comment block is the same shape. Raising the target is a decision about new builds; rebuilding what you already have is a second, larger decision.

# Shipped defaults in configs/milvus.yaml at tag v3.0.1:
#   dataCoord.targetVecIndexVersion: 8
#   dataCoord.targetScalarIndexVersion: -1
#   dataCoord.autoUpgradeSegmentIndex: false
#   dataCoord.forceRebuildSegmentIndex: false
#   dataCoord.forceRebuildScalarSegmentIndex: false
#
# Values the 3.0.0 release note tells you to set. Neither key has an entry in the
# configuration reference, so treat the release note as the only specification.
dataCoord:
  targetVecIndexVersion: 10
  targetScalarIndexVersion: 4

One more reason to be on the patch release: v3.0.1 fixed interim indexes ignoring the configured target index version, so on 3.0.0 a correctly raised target could still be ignored.

The awkward part is observability. No documented API, CLI command or metric reports the index version in use on a segment, so you cannot confirm the change by reading a value back. Behaviour is the only observable: build one new index on staging with the target raised, leave a comparable segment untouched, and compare search latency, recall and index size. That is the evidence for or against forceRebuildSegmentIndex across the collection.

The 3.0.0 release note says "GPU images move to CUDA 12.9 and no longer preserve Ubuntu 20.04 GPU compatibility," and read alone it sounds like a consequence of upgrading to 3.0. The GPU Dockerfile at each tag says otherwise.

The move from 11.8.0 to 12.9.1 happened in Milvus 2.6.19, released 26 June 2026. A cluster on 2.6.19 or later sees no CUDA change at the 3.0 boundary. Only a cluster on 2.6.18 or earlier meets it during the jump, which argues for taking a recent 2.6 patch first and treating the driver and container toolkit work as its own change. The CPU image at v3.0.1 is built on ubuntu:jammy-20240530.

The Ubuntu 20.04 half of that release note is a vendor statement the build tree does not corroborate: build/docker/milvus/gpu/ still contains both an ubuntu20.04 and an ubuntu22.04 directory at v2.6.23 and at v3.0.1, and no ubuntu20.04-suffixed milvusdb/milvus tag is published. If your GPU hosts run 20.04, pull the image and run it rather than trusting either source.

Resist filling the gap with a driver floor. The one vendor page that names a number, the GPU prerequisites page, was last committed in June 2024, lists six supported compute capabilities (6.0, 7.0, 7.5, 8.0, 8.6 and 9.0) and recommends drivers of version 545 and above. It predates the CUDA 12.9.1 base image by two years, so it is not a 3.0 requirement, and a number reasoned from CUDA minor version compatibility is a guess wearing a citation.

A major version upgrade is justified by what it unlocks. Three of the additions in 3.0 carry documented limits sharp enough to change whether they unlock anything for you.

Five limits are named for Milvus 3.0.0 specifically. A TEXT field cannot be a primary field, partition key or clustering key. TEXT fields do not support default values. They are not supported in external collections. You cannot create a scalar index on one. And a BM25 or MinHash Function that uses a TEXT field as input must be defined when the collection is created: add_function_field and AlterCollectionSchema cannot add it later, even if the collection is empty. Get that Function wrong at creation time and the fix is a new collection.

# Source: the sparse inverted index user guide.
from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="sparse_vector",
    index_type="SPARSE_INVERTED_INDEX",
    index_name="sparse_ip_index",
    metric_type="IP",
    params={"inverted_index_algo": "SINDI"},
)

client.create_index(
    collection_name="your_collection_name",
    index_params=index_params,
)

# Valid inverted_index_algo values: DAAT_MAXSCORE, DAAT_WAND, TAAT_NAIVE,
# BLOCK_MAX_MAXSCORE, BLOCK_MAX_WAND, SINDI.

The rehearsal is a dry run of the restore, with the upgrade in the middle. Restore your most recent backup into an isolated cluster, run the image-only upgrade there, then practise going back under time pressure. The backup mechanics, including how the backup version window constrains you, are in why a snapshot restore returns an empty collection.

Capture four things before the change window opens: the full Helm values or the live custom resource, the chart version and pod inventory, an external backup of metadata and persistent data, and a retrieval baseline. Verification after the swap is mechanical.

helm history <release-name> --namespace <namespace>

kubectl get pods --namespace <namespace>

kubectl get pods --namespace <namespace> \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{range .spec.containers[*]}{.image}{" "}{end}{"\n"}{end}'

Do not skip the retrieval baseline, and do not let it be QPS alone. An index version change moves recall, and recall moves hardest under metadata filters; the harness is in filtered vector search and recall collapse under selectivity. Record filtered and unfiltered recall on a fixed query set before the upgrade so the number after it means something.

For Storage V3 the observables are object storage bytes and compaction task counts on the staging copy. Nothing published quantifies how long the transition takes or how much capacity the rewrite needs at peak, so watch both from the moment useLoonFFI goes true: that curve is your shrinking rollback window.

Client SDKs get a test, not an assumption. Nothing in the 3.0.0 body, the 3.0.1 body, the five upgrade guides or the pymilvus 3.0.1 release notes states whether 2.x client calls are source-compatible with a 3.0 server, in either direction. Point your pinned client at the 3.0.1 staging cluster and run your real call set. One adjacent fix shows why: Milvus 2.6.23 fixed Milvus 2.6 accepting the unsupported Text data type, so a newer client could express a schema the server could not support.

The 2.6 line is still shipping patches: 2.6.23 was published on 28 August 2026. Staying is a maintained position, not a frozen one. Six signals decide it.

None of those rows is about which engine to run. If the real question is whether Milvus is the right store at your scale, we ran those numbers in vector search cost per QPS at a billion vectors.

One note for anyone building fresh. The Helm procedure was validated with Chart 5.0.22 and tells you to keep whatever chart version you already have, which sidesteps the question for an in-place upgrade. Chart milvus-5.0.27, published 3 September 2026, carries appVersion: "3.0.1" and an image tag of v3.0.1, and is the newest chart available. A new install on it sits outside what the guide validated, which makes the rehearsal more important rather than less.

Whichever way that table points, the same first day applies. Restore your most recent Milvus backup into an isolated staging cluster and run the image-only upgrade to v3.0.1 against that copy, with common.storage.useLoonFFI pinned explicitly to false through extraConfigFiles.user.yaml. Then restore the same backup again, on the clock, and confirm you can get back to the 2.6 patch you started from using an external artifact rather than an image tag. Record filtered and unfiltered recall either side, and run your pinned SDK's real call set. That turns every uncertainty in this post into a measurement on your data. The wider retrieval architecture around these decisions is mapped in our RAG systems pillar.