Basculer entre Pulsar et Woodpecker

Cette page décrit comment basculer la file d’attente de messages (MQ) d’un cluster Milvus entre Pulsar (intégré ou externe) et Woodpecker (backend MinIO), dans les deux sens. Pour connaître le déroulement général et les prérequis, consultez la section Basculer la file d’attente de messages.

Avec Helm

Passer de Pulsar à Woodpecker (Helm)

Étape 1 : Vérifiez que l’instance Milvus est en cours d’exécution. Assurez-vous que votre cluster Milvus fonctionne correctement — par exemple, en créant une collection de test, en insérant des données et en exécutant une requête.

Étape 2 : Exécutez le changement de file d’attente de messages. Accédez à l’interface de gestion MixCoord, puis appelez l’API de changement :

kubectl port-forward --address 0.0.0.0 service/my-release-milvus-mixcoord 29091:9091

Dans un autre terminal :

curl -X POST http://127.0.0.1:29091/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "woodpecker"}'

Étape 3 : Vérifiez que la migration est terminée.

kubectl logs <mixcoord-pod> | grep "successfully updated mq.type configuration in etcd"

Une migration réussie génère l'entrée suivante dans le journal : [mqTypeValue=woodpecker].

Étape 4 : (Facultatif) Arrêtez Pulsar et effectuez le nettoyage. Pour Pulsar intégré, désactivez Pulsar et activez Woodpecker, puis supprimez les PVC Pulsar :

helm upgrade my-release zilliztech/milvus \
  --set image.all.tag=v3.0.0 \
  --set pulsarv3.enabled=false \
  --set woodpecker.enabled=true \
  --set streaming.enabled=true \
  --set indexNode.enabled=false

kubectl get pvc | grep my-release-pulsarv3
kubectl delete pvc <pulsar-pvc-name> ...

Pour Pulsar externe, nettoyez les sujets Milvus dans l’instance Pulsar externe. Les sujets Milvus respectent le format <cluster_prefix>-dml_<seqNo>_<TimeTick><Version> (par exemple, by-dev-rootcoord-dml_10_464633776992639586v0).

Passer de Woodpecker à Pulsar (Helm)

Étape 1 : Vérifiez que l’instance Milvus est en cours d’exécution.

Étape 2 : Configurez la connexion Pulsar cible et redémarrez Milvus. Pour effectuer la transition, Milvus doit déjà connaître la connexion Pulsar ; vous devez donc l'enregistrer dans « user.yaml » via extraConfigFiles, puis appliquer les modifications avec helm upgrade (ce qui redémarre les pods). La commande « streaming.enabled=true » est requise pour la fonctionnalité Switch MQ.

# values.yaml
extraConfigFiles:
  user.yaml: |+
    pulsar:
      address: <pulsar addr>
      port: <pulsar port, e.g. 6650>

helm upgrade -i my-release zilliztech/milvus \
  --set pulsarv3.enabled=true \
  --set woodpecker.enabled=false \
  --set streaming.enabled=true \
  -f values.yaml

Attendez que tous les pods soient prêts, puis vérifiez que la configuration d’accès à Pulsar a bien été intégrée à la configuration de Milvus.

Étape 3 : Exécutez la migration MQ.

kubectl port-forward --address 0.0.0.0 service/my-release-milvus-mixcoord 29091:9091

Dans un autre terminal :

curl -X POST http://127.0.0.1:29091/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "pulsar"}'

Étape 4 : Vérifiez que la migration est terminée.

kubectl logs <mixcoord-pod> | grep "successfully updated mq.type configuration in etcd"

Une migration réussie génère le message « [mqTypeValue=pulsar] ».

Étape 5 : (Facultatif) Nettoyez les données Woodpecker. Supprimez les données Woodpecker sur MinIO/S3 (sous <rootPath>/wp/..., généralement files/wp/...) et les métadonnées Woodpecker dans etcd (etcdctl get woodpecker --prefix). Si vous prévoyez de revenir à Woodpecker ultérieurement, supprimez d’abord ces fichiers.

Avec Milvus Operator

Passer de Pulsar à Woodpecker (Milvus Operator)

Étape 1 : Vérifiez que l’instance Milvus est en cours d’exécution.

Étape 2 : Exécutez la commutation MQ. Le service MixCoord n’est pas exposé ; vous devez donc exécuter l’API de commutation depuis l’intérieur du pod MixCoord :

kubectl exec -it <mixcoord-pod> -- \
  curl -X POST http://localhost:9091/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "woodpecker"}'

Étape 3 : Vérifiez que la commutation est terminée.

kubectl logs <mixcoord-pod> | grep "successfully updated mq.type configuration in etcd"

Une commutation réussie génère l'entrée suivante dans le journal : [mqTypeValue=woodpecker].

Étape 4 : Mettez à jour le type de MQ dans l’Operator. Mettez à jour la configuration gérée par l’Operator afin que celui-ci ne revienne pas sur la bascule. Créez change_configmap.yaml:

apiVersion: milvus.io/v1beta1
kind: Milvus
metadata:
  name: my-release
  labels:
    app: milvus
spec:
  dependencies:
    msgStreamType: woodpecker

kubectl patch -f change_configmap.yaml --patch-file change_configmap.yaml --type merge

Étape 5 : (Facultatif) Arrêtez Pulsar et effectuez le nettoyage. Pour Pulsar intégré, désinstallez la version de Pulsar et supprimez ses PVC :

helm uninstall my-release-pulsar
kubectl get pvc | grep my-release-pulsar
kubectl delete pvc <pulsar-pvc-name> ...

Pour Pulsar externe, nettoyez les sujets Milvus (format <cluster_prefix>-dml_<seqNo>_<TimeTick><Version>).

Passer de Woodpecker à Pulsar (opérateur Milvus)

Étape 1 : Vérifiez que l’instance Milvus est en cours d’exécution.

Étape 2 : Configurez la connexion Pulsar cible et redémarrez Milvus. Placez la connexion Pulsar sous spec.config (l’opérateur convertit spec.config en user.yaml) et définissez le type de MQ ; l’application du CR redémarre les pods avec la nouvelle configuration.

# change_configmap.yaml
apiVersion: milvus.io/v1beta1
kind: Milvus
metadata:
  name: my-release
  labels:
    app: milvus
spec:
  config:
    pulsar:
      address: <pulsar addr>
      port: <pulsar port, e.g. 6650>
  dependencies:
    msgStreamType: pulsar

kubectl patch -f change_configmap.yaml --patch-file change_configmap.yaml --type merge

Attendez que tous les pods soient prêts, puis vérifiez que la configuration d’accès à Pulsar a bien été intégrée à la configuration de Milvus.

Étape 3 : Exécutez la migration MQ.

kubectl exec -it <mixcoord-pod> -- \
  curl -X POST http://localhost:9091/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "pulsar"}'

Étape 4 : Vérifiez que la migration est terminée.

kubectl logs <mixcoord-pod> | grep "successfully updated mq.type configuration in etcd"

Une migration réussie génère l’entrée suivante dans le journal : [mqTypeValue=pulsar].

Étape 5 : (Facultatif) Supprimez les données Woodpecker. Supprimez les données Woodpecker sur MinIO/S3 (dans le répertoire <rootPath>/wp/..., généralement files/wp/...) ainsi que les métadonnées Woodpecker dans etcd (etcdctl get woodpecker --prefix). Si vous prévoyez de revenir à Woodpecker ultérieurement, supprimez d’abord ces fichiers.

Scénarios pris en charge

MQ source	MQ cible	Helm	Opérateur Milvus
Pulsar intégré	Woodpecker (MinIO)	Prise en charge	Prise en charge
Pulsar externe	Woodpecker (MinIO)	Pris en charge	Prise en charge
Woodpecker (MinIO)	Pulsar externe	Pris en charge	Prise en charge
Pulsar	Woodpecker (local)	Pris en charge mais non recommandé (tous les pods doivent partager un système de fichiers)	Non pris en charge