Basculer entre Kafka et Woodpecker

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

Avec Helm

Passer de Kafka à 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 : Effectuez 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 Kafka et effectuez un nettoyage. Pour Kafka intégré, supprimez les pods Kafka et leurs PVC. Pour Kafka externe, nettoyez les sujets Milvus dans l’instance Kafka externe — ils suivent le format <cluster_prefix>-dml_<seqNo>_<TimeTick><Version>.

Passer de Woodpecker à Kafka (Helm)

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

Étape 2 : Configurez la connexion Kafka cible et redémarrez Milvus. Le passage à Kafka nécessite que Milvus connaisse déjà la connexion Kafka ; vous devez donc l’enregistrer dans ` user.yaml ` via ` extraConfigFiles `, puis appliquer la configuration avec ` helm upgrade ` (ce qui redémarre les pods). ` streaming.enabled=true ` est requis pour la fonctionnalité Switch MQ. Pour plus de détails sur SASL/SSL, consultez la section « Se connecter à Kafka avec SASL/SSL ».

# values.yaml
extraConfigFiles:
  user.yaml: |+
    kafka:
      brokerList:
        - <your_kafka_address>:<your_kafka_port>
      saslUsername:
      saslPassword:
      saslMechanisms: PLAIN
      securityProtocol: SASL_SSL

helm upgrade -i my-release zilliztech/milvus \
  --set kafka.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 à Kafka a bien été intégrée à la configuration de Milvus.

Étape 3 : Exécutez la migration vers 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": "kafka"}'

É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=kafka] ».

É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.

Avec Milvus Operator

Passer de Kafka à 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 bascule 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 : 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 en arrière. 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 Kafka et effectuez le nettoyage. Pour Kafka intégré, supprimez les pods Kafka et leurs PVC. Pour Kafka externe, nettoyez les sujets Milvus (format <cluster_prefix>-dml_<seqNo>_<TimeTick><Version>).

Passer de Woodpecker à Kafka (opérateur Milvus)

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

Étape 2 : Configurez la connexion Kafka cible et redémarrez Milvus. Placez la connexion Kafka sous spec.config (l’opérateur convertit spec.config en user.yaml) et définissez le type de MQ ; l’application du CR actualise les pods avec la nouvelle configuration. Pour plus de détails sur SASL/SSL, consultez la section « Se connecter à Kafka avec SASL/SSL ».

# change_configmap.yaml
apiVersion: milvus.io/v1beta1
kind: Milvus
metadata:
  name: my-release
  labels:
    app: milvus
spec:
  config:
    kafka:
      brokerList:
        - <your_kafka_address>:<your_kafka_port>
      saslUsername:
      saslPassword:
      saslMechanisms: PLAIN
      securityProtocol: SASL_SSL
  dependencies:
    msgStreamType: kafka

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 à Kafka a bien été intégrée à la configuration de Milvus.

Étape 3 : Exécutez la migration vers MQ.

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

É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=kafka].

É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
Kafka intégré	Woodpecker (MinIO)	Prise en charge	Prise en charge
Kafka externe	Woodpecker (MinIO)	Pris en charge	Pris en charge
Woodpecker (MinIO)	Kafka externe	Pris en charge	Pris en charge
Kafka	Woodpecker (local)	Pris en charge mais non recommandé (tous les pods doivent disposer d'un système de fichiers partagé)	Non pris en charge