Switch MQ Type for Milvus Cluster
This topic describes how to switch the message queue (MQ) type for an existing Milvus cluster deployment. Milvus supports online MQ switching between Pulsar, Kafka, and Woodpecker without downtime.
This feature is pending release and is subject to change. Please reach out to Milvus support if you want to try it out or have any questions.
Prerequisites
- A running Milvus cluster instance installed via Milvus Operator or Helm.
- The Milvus instance has been upgraded to the latest version that supports this Switch MQ feature.
Switch from Pulsar/Kafka to Woodpecker (MinIO)
Follow these steps to switch the MQ type from Pulsar or Kafka to Woodpecker with MinIO storage.
Step 1: Verify the Milvus instance is running
Before switching, ensure that your Milvus cluster instance is running properly. You can verify this by creating a test collection, inserting data, and running a query.
Step 2: (Optional) Verify Woodpecker configuration
The default Milvus configuration already sets Woodpecker storage type to MinIO, so no additional configuration is required in most cases.
However, if you have previously customized the Woodpecker configuration, you must ensure that woodpecker.storage.type is set to minio. Update the Milvus configuration without changing the mqType value:
woodpecker:
storage:
type: minio
- For Helm, refer to Configure Milvus with Helm Charts for instructions on updating configuration.
- For Milvus Operator, refer to Configure Milvus with Milvus Operator for instructions on updating configuration.
Step 3: Execute the MQ switch
Run the following command to trigger the switch to Woodpecker:
curl -X POST http://<mixcoord_addr>:9091/management/wal/alter \
-H "Content-Type: application/json" \
-d '{"target_wal_name": "woodpecker"}'
Replace <mixcoord_addr> with the actual address of your MixCoord service.
Step 4: Verify the switch is complete
The switch process completes automatically. Monitor the Milvus logs for the following key messages to confirm the switch has finished:
WAL switch success: <MQ1> switch to <MQ2> finish, re-opening required
AlterWAL broadcast message acknowledged by all vchannels
successfully updated mq.type configuration in etcd
In the log messages above, <MQ1> is the source MQ type (e.g., pulsar or kafka), and <MQ2> is the target MQ type (woodpecker).
- The first message indicates that the WAL switch from the source to the target has completed.
- The second message indicates that all physical channels have been switched.
- The third message indicates that the
mq.typeconfiguration has been updated in etcd.
Switch from Woodpecker (MinIO) to Pulsar or Kafka
Follow these steps to switch the MQ type from Woodpecker back to Pulsar or Kafka.
Step 1: Verify the Milvus instance is running
Before switching, ensure that your Milvus cluster instance is running properly.
Step 2: Configure the target MQ
Before triggering the switch, you need to ensure the target MQ service (Pulsar or Kafka) is available and its access configuration is rendered into the Milvus configuration.
The exact steps in this section depend on whether you are using an internal (bundled) or external MQ service.
Option A: Internal Pulsar/Kafka (bundled with Helm)
If you are using the bundled Pulsar or Kafka deployed by Helm, update your Helm release to enable the target MQ service and disable Woodpecker. The streaming.enabled=true flag is required to enable the Streaming Node, which is a prerequisite for the Switch MQ feature. For example, to switch to Pulsar:
helm upgrade -i my-release milvus/milvus \
--set pulsarv3.enabled=true \
--set woodpecker.enabled=false \
--set streaming.enabled=true \
-f values.yaml
After the upgrade, verify that the target MQ access configuration has been rendered into the Milvus configuration. For example, for Pulsar:
pulsar:
address: <pulsar-proxy-address>
port: 6650
Option B: Internal Pulsar/Kafka (managed by Milvus Operator)
If you are using Milvus Operator, update the Milvus custom resource to include the target MQ access configuration. Refer to Configure Milvus with Milvus Operator for details on updating Milvus configuration.
Option C: External Pulsar/Kafka
If you are using an external Pulsar or Kafka service, you do not need to change the mqType. Simply add the external MQ access configuration to your values.yaml and restart the Milvus instance to render the configuration.
Step 3: Execute the MQ switch
Run the following command to trigger the switch to Pulsar (replace pulsar with kafka if switching to Kafka):
curl -X POST http://<mixcoord_addr>:9091/management/wal/alter \
-H "Content-Type: application/json" \
-d '{"target_wal_name": "pulsar"}'
Replace <mixcoord_addr> with the actual address of your MixCoord service.
Step 4: Verify the switch is complete
The switch process completes automatically. Monitor the Milvus logs for the following key messages to confirm the switch has finished:
WAL switch success: <MQ1> switch to <MQ2> finish, re-opening required
AlterWAL broadcast message acknowledged by all vchannels
successfully updated mq.type configuration in etcd
In the log messages above, <MQ1> is the source MQ type (woodpecker), and <MQ2> is the target MQ type (e.g., pulsar or kafka).
- The first message indicates that the WAL switch from the source to the target has completed.
- The second message indicates that all physical channels have been switched.
- The third message indicates that the
mq.typeconfiguration has been updated in etcd.