Kafka と Woodpecker の切り替え

このページでは、Milvusクラスタのメッセージキュー（MQ）を、Kafka（組み込みまたは外部）とWoodpecker（MinIOバックエンド）の間で双方向に切り替える方法について説明します。一般的なワークフローと前提条件については、「メッセージキューの切り替え」を参照してください。

Helm を使用する場合

Kafka から Woodpecker への切り替え（Helm）

ステップ 1: Milvus インスタンスが実行中であることを確認します。テストコレクションの作成、データの挿入、クエリの実行などを行い、Milvus クラスタが正常に動作していることを確認してください。

ステップ 2: MQ の切り替えを実行します。MixCoord 管理インターフェースを公開し、switch API を呼び出します:

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

別のターミナルで：

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

ステップ 3: 切り替えが完了したことを確認します。

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

切り替えが成功すると、[mqTypeValue=woodpecker] というログが出力されます。

ステップ 4: (オプション) Kafka を停止し、クリーンアップを行います。 組み込みのKafka の場合は、Kafka ポッドとその PVC を削除します。外部Kafka の場合は、外部 Kafka インスタンス内の Milvus トピックをクリーンアップします。これらのトピックは<cluster_prefix>-dml_<seqNo>_<TimeTick><Version> という形式に従います。

Woodpecker から Kafka への切り替え (Helm)

ステップ 1: Milvus インスタンスが実行中であることを確認します。

ステップ 2: 対象の Kafka 接続を設定し、Milvus を再起動します。切り替えを行うには、Milvus が Kafka 接続情報を既に認識している必要があるため、extraConfigFiles を使用してuser.yaml に書き込み、helm upgrade で適用します（これによりポッドが再起動されます）。Switch MQ 機能には、streaming.enabled=true が必要です。SASL/SSL の詳細については、「SASL/SSL を使用した Kafka への接続」を参照してください。

# 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

すべてのポッドの準備が整うまで待機し、Kafkaへのアクセス設定がMilvusの設定に反映されていることを確認してください。

ステップ 3: MQ 切り替えを実行します。

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

別のターミナルで：

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

ステップ 4: 切り替えが完了したことを確認します。

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

切り替えが成功すると、[mqTypeValue=kafka] というログが出力されます。

ステップ 5: (オプション) Woodpecker データのクリーンアップを行います。MinIO/S3 上の Woodpecker データ（<rootPath>/wp/... 配下、通常はfiles/wp/... ）および etcd 内の Woodpecker メタデータ（etcdctl get woodpecker --prefix ）を削除します。後で Woodpecker に戻す予定がある場合は、まずこれらのファイルをクリーンアップしてください。

Milvus Operator を使用する場合

Kafka から Woodpecker への切り替え（Milvus Operator）

ステップ 1: Milvus インスタンスが実行中であることを確認します。

ステップ 2: MQ の切り替えを実行します。MixCoord サービスは外部からアクセスできないため、MixCoord ポッド内部から切り替え API を実行してください:

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

ステップ 3: 切り替えが完了したことを確認します。

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

切り替えが成功すると、[mqTypeValue=woodpecker] がログに記録されます。

ステップ 4: Operator 内の MQ タイプを更新します。Operator が切り替えを元に戻さないように、Operatorが管理する設定を更新します。 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

ステップ 5: (オプション) Kafka を停止し、クリーンアップを行います。 組み込みのKafka の場合は、Kafka ポッドとその PVC を削除します。外部のKafka の場合は、Milvus トピックをクリーンアップします（<cluster_prefix>-dml_<seqNo>_<TimeTick><Version> の形式）。

Woodpecker から Kafka への切り替え（Milvus Operator）

ステップ 1: Milvus インスタンスが実行中であることを確認します。

ステップ 2: 対象の Kafka 接続を設定し、Milvus を再起動します。Kafka 接続を`spec.config ` に配置し（Operator は `spec.config ` を `user.yaml` に変換します）、MQ タイプを設定します。CR を適用すると、ポッドが新しい構成で再起動されます。SASL/SSL の詳細については、「SASL/SSL を使用した Kafka への接続」を参照してください。

# 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

すべてのポッドが「ready」状態になるまで待機し、Kafka へのアクセス設定が Milvus の設定に反映されていることを確認してください。

ステップ 3: 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"}'

ステップ 4: 切り替えが完了したことを確認します。

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

切り替えが成功すると、[mqTypeValue=kafka] というログが出力されます。

ステップ 5: (オプション) Woodpecker データのクリーンアップ。MinIO/S3 上の Woodpecker データ（<rootPath>/wp/... 配下、通常はfiles/wp/... ）および etcd 内の Woodpecker メタデータ（etcdctl get woodpecker --prefix ）を削除します。後で Woodpecker に戻す予定がある場合は、まずこれらのファイルをクリーンアップしてください。

サポートされるシナリオ

ソースMQ	ターゲットMQ	Helm	Milvus Operator
組み込みKafka	Woodpecker (MinIO)	サポート対象	サポート対象
外部Kafka	Woodpecker (MinIO)	対応済み	対応
Woodpecker (MinIO)	外部Kafka	対応	対応
Kafka	Woodpecker（ローカル）	サポートされていますが、推奨されません（すべてのポッドに共有ファイルシステムが必要です）	未対応