DOCS/troubleshooting/250918_happybell80_fluent_bit_opensearch_data_prepper_integration.md

Fluent Bit와 OpenSearch 3.2.0 연동 문제 해결 - Data Prepper 브릿지 구축

문제 상황

• 발생일: 2025-09-18
• 환경: 24서버(Fluent Bit) → 23서버(OpenSearch 3.2.0)
• 증상: Fluent Bit이 OpenSearch로 로그 전송 실패
• 근본 원인: 모든 Fluent Bit 버전이 _type 파라미터를 전송하나, OpenSearch 3.x는 이를 거부

오류 상세

1. OpenSearch 플러그인 오류

[error] [output:opensearch:opensearch.0] HTTP status=400 URI=/_bulk, response:
{"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"Action/metadata line [1] contains an unknown parameter [_type]"}]},"status":400}

2. ES 플러그인 오류

[error] [output:es:es.0] HTTP status=400 URI=/_bulk, response:
{"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"Action/metadata line [1] contains an unknown parameter [_type]"}]},"status":400}

테스트 내역

Fluent Bit 버전별 테스트 결과

버전	opensearch 플러그인	es 플러그인	결과
4.0.9	_type 에러	에러 없지만 전송 안됨	❌
3.2.2	_type 에러	에러 없지만 전송 안됨	❌
2.2.2	_type 에러	_type 에러	❌

시도한 설정 조합

1. Suppress_Type_Name On - 무시됨
2. Type _doc - 무시됨
3. Logstash_Format On/Off - 동일한 문제
4. Workers 1 - 동일한 문제

다른 도구 테스트

• Filebeat 8.x: 라이센스 체크 실패 (OpenSearch와 비호환)
• Filebeat 7.x: 버전 호환성 문제
• Vector: 설정은 되나 데이터 수집 실패

해결 방법: Data Prepper 브릿지 구축

아키텍처

Fluent Bit (24서버) → HTTP → Data Prepper (24서버) → OpenSearch (23서버)

1. Data Prepper 설치 및 설정

pipelines.yaml

log-pipeline:
  source:
    http:
      port: 2021
      path: "/"
      health_check_service: true
      ssl: false
  processor:
    - parse_json:
        source: "message"
        destination: "@message"
  sink:
    - opensearch:
        hosts: ["http://192.168.219.45:9200"]
        index: "dataprepper-%{yyyy.MM.dd}"
        document_type: "_doc"

data-prepper-config.yaml (필요 시)

# 기본 설정 파일 (비어있어도 파일은 필요)

Docker 실행

docker run -d --name data-prepper \
  --network host \
  --restart unless-stopped \
  -v /home/admin/ivada_project/fluent-bit/data-prepper/pipelines.yaml:/usr/share/data-prepper/pipelines/pipelines.yaml:ro \
  -v /home/admin/ivada_project/fluent-bit/data-prepper/data-prepper-config.yaml:/usr/share/data-prepper/config/data-prepper-config.yaml:ro \
  opensearchproject/data-prepper:2.4.0

2. Fluent Bit 설정 변경

fluent-bit.conf (OUTPUT 섹션)

[OUTPUT]
    Name              http
    Match             *
    Host              127.0.0.1
    Port              2021
    URI               /
    Format            json
    Json_date_key     timestamp
    Json_date_format  iso8601

3. Fluent Bit 재시작

docker restart fluent-bit

검증 결과

• 인덱스 생성: dataprepper-2025.09.17, dataprepper-2025.09.18 ✅
• 문서 수집: 4,000+ 문서 성공적으로 저장 ✅
• 실시간 로그: 모든 Docker 컨테이너 로그 수집 중 ✅
• 안정성: 지속적으로 HTTP 200 응답, 안정적 운영 중

핵심 문제 분석

근본 원인

1. Elasticsearch 7.x 이후 변경사항: _type 파라미터가 deprecated되고 제거됨
2. OpenSearch 3.x 엄격한 검증: _type 파라미터를 완전히 거부
3. Fluent Bit 하위 호환성: 레거시 Elasticsearch를 위해 계속 _type 전송

왜 설정이 무시되는가?

• Fluent Bit의 opensearch/es 플러그인이 하드코딩된 _type 필드를 전송
• Suppress_Type_Name, Type 등의 설정이 실제로 적용되지 않음
• 이는 Fluent Bit의 알려진 이슈이며, 최신 버전에서도 미해결

교훈

1. 버전 호환성 확인 필수: OpenSearch/Elasticsearch 메이저 버전 변경 시 클라이언트 호환성 검증
2. 브릿지 패턴 활용: 직접 연결이 어려울 때 중간 브릿지(Data Prepper) 사용
3. 공식 도구 우선: OpenSearch는 Data Prepper, Elasticsearch는 Logstash 사용 권장

대안 솔루션

1. OpenSearch 2.x 사용: _type 파라미터 허용 (다운그레이드)
2. Logstash 사용: Elasticsearch 출력 플러그인으로 OpenSearch 연결
3. 커스텀 HTTP 포워더: 간단한 Python/Node.js 스크립트로 _type 제거

참고 명령어

Data Prepper 헬스체크

curl -s http://localhost:2021/health

OpenSearch 인덱스 확인

curl -s "http://192.168.219.45:9200/_cat/indices?v" | grep dataprepper

문서 수 확인

curl -s "http://192.168.219.45:9200/dataprepper-*/_count"

구현 현황 (2025-09-18 업데이트)

Git 리포지토리 구조

• fluent-bit 리포지토리: Data Prepper 설정 포함
  • /data-prepper/pipelines.yaml: 파이프라인 설정
  • /data-prepper/data-prepper-config.yaml: 기본 설정
  • /data-prepper/README.md: 실행 가이드

현재 운영 상태

• Data Prepper: 51124 서버에서 독립 컨테이너로 실행 중
• Fluent Bit: Git Actions로 자동 배포 (Data Prepper는 수동 관리)
• 로그 수집: 정상 작동, OpenSearch에 지속적으로 전송 중

향후 개선 사항

• Git Actions에 Data Prepper 자동 배포 추가 고려
• 51124 서버 전용 배포 스크립트 작성 필요

---

현재 상태 (2025-09-27)

51123 Data Prepper 배포 완료

• 문제: 51123 Fluent Bit이 127.0.0.1:2021로 전송 시도하나 Data Prepper 미실행
• 해결: docker-compose.yaml에 data-prepper 서비스 추가

파일 구조

fluent-bit/
├── docker-compose.yaml          # fluent-bit + data-prepper 서비스
├── data-prepper/
│   ├── pipelines.yaml          # port: 2021, hosts: ["http://localhost:9200"]
│   ├── data-prepper-config.yaml # ssl: false
│   └── README.md               # 배포 가이드
└── fluent-bit.conf             # OUTPUT: 127.0.0.1:2021

배포 명령 (51123)

cd /home/admin/fluent-bit
docker compose up -d data-prepper

검증

# 헬스체크
curl http://localhost:2021/health

# 인덱스 확인
curl "http://localhost:9200/_cat/indices?v" | grep dataprepper

• 상태: 해결 완료 - docker-compose.yaml에 data-prepper 서비스 정의 완료, 배포 대기

---

작성자: happybell80 작성일: 2025-09-18 최종 수정: 2025-09-27 - 51123 Data Prepper 배포 설정 완료