Upgrade Milvus Cluster with Milvus Operator

This guide describes how to upgrade a Milvus 2.6.x cluster to v3.0.0 with Milvus Operator.

Prerequisites

• A Kubernetes cluster with a Milvus 2.6.x cluster managed by Milvus Operator
• kubectl access to the cluster
• The complete Milvus custom resource (CR) manifest used for the existing deployment
• The installation method and manifests used for the existing Milvus Operator
• A current backup of Milvus metadata and persistent data

Message Queue limitations: When upgrading to Milvus v3.0.0, you must maintain your current message queue choice. Switching between different message queue systems during the upgrade is not supported. Support for changing message queue systems will be available in future versions.

Upgrade process

Step 1: Back up the current Milvus CR

Save the current CR before changing the deployment:

kubectl get milvus <instance-name> \
  --namespace <namespace> \
  --output yaml > milvus-before-upgrade.yaml

Use the source manifest for your existing deployment as the upgrade manifest. Do not apply the exported backup file directly without first removing server-managed metadata and status fields.

Step 2: Confirm the Milvus Operator version

Check the image used by the installed Milvus Operator:

kubectl get deployments --all-namespaces \
  -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.metadata.name}{"\t"}{range .spec.template.spec.containers[*]}{.image}{" "}{end}{"\n"}{end}' \
  | grep milvus-operator

The validated upgrade kept Milvus Operator at version 1.3.0. Keep the Operator version that currently manages your Milvus 2.6.x deployment unless your support policy requires a separate Operator upgrade. Do not downgrade a newer Operator to the tested version. If you need to change the Operator version, use the same Helm or kubectl installation method and the same release name and namespace as the existing installation, then validate the Operator change before updating the Milvus CR.

Step 3: Update the Milvus image

In the complete Milvus CR manifest, change spec.components.image to the target version. Preserve the current mode, component topology, message queue, etcd, storage, and other dependency settings. The following excerpt shows the fields to confirm; do not replace your complete CR with this excerpt.

Before applying the target CR, confirm that indexNode.replicas is 0. The validated Milvus 2.6.20 configuration already used this setting. Keep the explicit zero-replica setting in the target CR.

apiVersion: milvus.io/v1beta1
kind: Milvus
metadata:
  name: <instance-name>
  namespace: <namespace>
spec:
  components:
    image: milvusdb/milvus:v3.0.0
    indexNode:
      replicas: 0

Apply the complete CR manifest:

kubectl apply --filename milvus.yaml

Verify the upgrade

Check the CR status, Pod status, and container images:

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

kubectl get pods --namespace <namespace>

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

Verify that the Milvus CR reports Healthy, all Milvus components use milvusdb/milvus:v3.0.0, no IndexNode Pod is running, and the existing collections remain queryable and searchable. Complete these checks before you enable any v3.0.0-specific feature.