본문 바로가기
WIKI 기술 지식 베이스

Kafka와 Woodpecker 사이 전환 (Switch between Kafka and Woodpecker)

원문 보기 위키 갱신

이 페이지에서는 Milvus cluster의 메시지 큐(MQ)를 Kafka(builtin 또는 external)와 Woodpecker(MinIO 백엔드) 사이에서 양방향으로 전환하는 방법을 설명해요. 일반적인 작업 흐름과 사전 요구 사항은 Switch Message Queue를 참고하세요.

사전 요구 사항: Switch MQ 기능은 Milvus 3.0 이상에서 사용할 수 있어요. 시작하기 전에 Milvus 인스턴스를 Milvus 3.0 이상으로 업그레이드해야 해요. 이전 버전에서는 사용할 수 없어요.

메시지 큐 전환은 위험도가 높은 작업이에요. 자신의 배포 방식에 맞는 섹션을 골라 — With Helm 또는 With Milvus Operator — 처음부터 끝까지 따라가세요. Helm과 Operator 명령을 섞어 쓰지 마세요.

출처: Milvus 문서

본문

With Helm

Kafka에서 Woodpecker로 전환 (Helm)

1단계: Milvus 인스턴스가 실행 중인지 확인해요. 테스트 컬렉션을 만들고 데이터를 넣은 뒤 쿼리를 실행하는 방식으로 Milvus cluster가 정상 동작하는지 확인해요.

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를 중지하고 정리해요. builtin Kafka라면 Kafka 파드와 PVC를 제거해요. external Kafka라면 외부 Kafka 인스턴스에서 Milvus 토픽을 정리해요. 토픽 형식은 -dml__이에요.

나중에 Kafka로 다시 전환할 계획이라면 충돌을 피하기 위해 먼저 데이터/토픽을 정리해 두세요.

Woodpecker에서 Kafka로 전환 (Helm)

1단계: Milvus 인스턴스가 실행 중인지 확인해요.

2단계: 대상 Kafka 연결을 설정하고 Milvus를 재시작해요. 전환은 Milvus가 Kafka 연결을 이미 알고 있어야 하므로, extraConfigFiles를 통해 user.yaml에 작성하고 helm upgrade로 적용해요(파드를 롤링함). Switch MQ 기능에는 streaming.enabled=true가 필요해요. SASL/SSL 관련 내용은 Connect to Kafka with 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

모든 파드가 준비될 때까지 기다린 뒤, Kafka 접근 설정이 Milvus 설정에 반영됐는지 확인해요.

3단계: MQ 전환을 실행해요.

대상 Kafka에 이전 설정에서 남은 Milvus 토픽이 없는지 확인해요. Kafka로 처음 전환하는 것이라면 이 내용을 건너뛰고, 아니라면 같은 이름의 잔여 Milvus 토픽을 먼저 정리해요.

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 데이터(/wp/..., 보통 files/wp/...)와 etcd에 있는 Woodpecker 메타데이터(etcdctl get woodpecker --prefix)를 삭제해요. 나중에 Woodpecker로 다시 전환할 계획이라면 이 파일들을 먼저 정리해 두세요.

With Milvus Operator

Kafka에서 Woodpecker로 전환 (Milvus Operator)

1단계: Milvus 인스턴스가 실행 중인지 확인해요.

2단계: MQ 전환을 실행해요. MixCoord 서비스는 노출되어 있지 않으므로, MixCoord 파드 안에서 switch 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를 중지하고 정리해요. builtin Kafka라면 Kafka 파드와 PVC를 제거해요. external Kafka라면 Milvus 토픽(형식 -dml__)을 정리해요.

Woodpecker에서 Kafka로 전환 (Milvus Operator)

1단계: Milvus 인스턴스가 실행 중인지 확인해요.

2단계: 대상 Kafka 연결을 설정하고 Milvus를 재시작해요. Kafka 연결을 spec.config 아래에 넣고(Operator가 spec.config를 user.yaml로 렌더링함) MQ 타입을 설정해요. CR을 적용하면 새 설정으로 파드가 롤링돼요. SASL/SSL 관련 내용은 Connect to Kafka with 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

모든 파드가 준비될 때까지 기다린 뒤, Kafka 접근 설정이 Milvus 설정에 반영됐는지 확인해요.

3단계: MQ 전환을 실행해요.

대상 Kafka에 이전 설정에서 남은 Milvus 토픽이 없는지 확인해요. Kafka로 처음 전환하는 것이라면 이 내용을 건너뛰고, 아니라면 같은 이름의 잔여 Milvus 토픽을 먼저 정리해요.

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 데이터(/wp/..., 보통 files/wp/...)와 etcd에 있는 Woodpecker 메타데이터(etcdctl get woodpecker --prefix)를 삭제해요. 나중에 Woodpecker로 다시 전환할 계획이라면 이 파일들을 먼저 정리해 두세요.

지원 시나리오 (Supported scenarios)

소스 MQ 대상 MQ Helm Milvus Operator
Builtin Kafka Woodpecker (MinIO) Supported Supported
External Kafka Woodpecker (MinIO) Supported Supported
Woodpecker (MinIO) External Kafka Supported Supported
Kafka Woodpecker (local) Supported but not recommended (모든 파드가 공유 파일시스템 필요) Not supported

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.