Elasticsearch를 운영하다 보면 종종 마주치게 되는 master_not_discovered_exception 에러. 이 에러를 만나면 정말 당황스럽죠. 특히 운영 환경에서 갑자기 발생하면 머리가 하얘집니다.
저도 처음 이 에러를 마주쳤을 때 구글링만 몇 시간을 했던 기억이 나네요. 다행히 이 에러는 원인을 정확히 파악하면 충분히 해결할 수 있습니다. 이번 글에서는 실제 경험을 바탕으로 이 에러의 원인과 해결방법을 체계적으로 정리해보겠습니다.
1. “master_not_discovered_exception” 는 어떤 에러인가?
master_not_discovered_exception은 말 그대로 Elasticsearch 클러스터에서 마스터 노드를 찾을 수 없다는 뜻입니다.
{
"error": {
"root_cause": [{
"type": "master_not_discovered_exception",
"reason": null
}],
"type": "master_not_discovered_exception",
"reason": null
},
"status": 503
}
이 에러가 발생하는 순간 클러스터는 제대로 동작하지 않게 됩니다. 검색도, 인덱싱도 모두 불가능해지죠.
2. 주요 원인 분석
네트워크 연결 문제
가장 흔한 원인 중 하나입니다. 노드들 간의 통신이 차단되어 마스터를 찾을 수 없는 상황이에요.
설정 파일 오류
Elasticsearch 7.x 이후 버전에서는 클러스터 초기화 관련 설정이 필수가 되었습니다. 이 설정이 빠지거나 잘못되면 에러가 발생합니다.
방화벽/보안 그룹 설정
AWS EC2나 클라우드 환경에서 특히 자주 발생하는 문제입니다. 필요한 포트가 막혀있으면 노드들이 서로를 찾을 수 없어요.
3. 단계별 해결방법
3-1. 네트워크 연결 확인
먼저 기본적인 네트워크 연결을 확인해보세요.
# 9200 포트 (HTTP) 확인
curl -X GET "localhost:9200/_cluster/health?pretty"
# 9300 포트 (Transport) 확인 - 노드 간 통신용
telnet [대상_IP] 9300
해결방법:
- 방화벽 포트 열기
# CentOS/RHEL sudo firewall-cmd --permanent --add-port=9200/tcp sudo firewall-cmd --permanent --add-port=9300/tcp sudo firewall-cmd --reload # Ubuntu sudo ufw allow 9200 sudo ufw allow 9300 - AWS EC2 보안 그룹 설정
- 인바운드 규칙에 TCP 9200, 9300 포트 추가
- 소스는 클러스터 내 다른 노드들의 IP 또는 보안 그룹 설정
3-2. 설정 파일 수정 (단일 노드)
단일 노드 클러스터를 운영하는 경우 /etc/elasticsearch/elasticsearch.yml 파일을 다음과 같이 설정합니다:
# 클러스터 이름
cluster.name: my-cluster
# 노드 이름
node.name: node-1
# 네트워크 설정
network.host: 0.0.0.0
http.port: 9200
# 마스터 초기화 설정 (ES 7.x+ 필수)
cluster.initial_master_nodes: ["node-1"]
# 디스커버리 설정
discovery.seed_hosts: ["127.0.0.1"]
주의사항: network.host를 0.0.0.0으로 설정하면 Elasticsearch가 프로덕션 모드로 동작합니다. 이때 추가적인 시스템 설정이 필요할 수 있어요.
3-3. 설정 파일 수정 (멀티 노드)
멀티 노드 클러스터의 경우 각 노드마다 설정을 조금씩 다르게 해야 합니다.
마스터 노드 (예: 192.168.1.10)
cluster.name: production-cluster
node.name: master-node-1
node.roles: ["master"]
network.host: 192.168.1.10
http.port: 9200
discovery.seed_hosts: ["192.168.1.10", "192.168.1.11", "192.168.1.12"]
cluster.initial_master_nodes: ["master-node-1", "master-node-2"]
데이터 노드 (예: 192.168.1.11)
cluster.name: production-cluster
node.name: data-node-1
node.roles: ["data"]
network.host: 192.168.1.11
http.port: 9200
discovery.seed_hosts: ["192.168.1.10", "192.168.1.11", "192.168.1.12"]
# 데이터 노드는 initial_master_nodes 설정 불필요
3-4. 버전별 주의사항
| Elasticsearch 버전 | 주요 변경사항 | 필수 설정 |
|---|---|---|
| 6.x 이하 | discovery.zen.* 설정 사용 |
discovery.zen.minimum_master_nodes |
| 7.x | cluster.initial_master_nodes 도입 |
cluster.initial_master_nodes |
| 8.x | discovery.zen.* 설정 완전 제거 |
cluster.initial_master_nodes |
Elasticsearch 8.x 사용자 주의: discovery.zen 관련 설정은 모두 제거되었습니다. 기존 설정 파일에 이런 설정이 있다면 삭제해야 합니다.
4. 실제 단계별 트러블슈팅
4-1. 로그 확인 방법
문제 해결의 첫 단계는 로그 확인입니다.
# 실시간 로그 확인
tail -f /var/log/elasticsearch/[클러스터명].log
# 특정 에러 검색
grep -i "master_not_discovered" /var/log/elasticsearch/*.log
4-2. 클러스터 상태 확인
# 클러스터 전체 상태
curl -X GET "localhost:9200/_cluster/health?pretty"
# 노드 목록 확인
curl -X GET "localhost:9200/_cat/nodes?v"
# 마스터 노드 확인
curl -X GET "localhost:9200/_cat/master?v"
4-3. 응급 복구 방법
클러스터가 완전히 먹통이 된 경우:
- 모든 노드 중지
sudo systemctl stop elasticsearch - 데이터 디렉토리 백업 (중요!)
sudo cp -r /var/lib/elasticsearch /var/lib/elasticsearch_backup - 설정 파일 재검토 및 수정
- 노드 순차적 재시작
# 마스터 노드부터 시작 sudo systemctl start elasticsearch # 30초 정도 대기 후 다음 노드 시작
5. 동일한 에러 예방법 및 모니터링
5-1. 정기적인 클러스터 상태 확인
#!/bin/bash
# cluster_health_check.sh
CLUSTER_STATUS=$(curl -s -X GET "localhost:9200/_cluster/health" | jq -r '.status')
if [ "$CLUSTER_STATUS" != "green" ]; then
echo "클러스터 상태 이상: $CLUSTER_STATUS"
# 슬랙이나 이메일 알림 발송
fi
5-2. 모니터링 도구 활용
- Kibana Monitoring: 클러스터 상태 실시간 모니터링
- Metricbeat: 시스템 메트릭 수집
- Elastic APM: 애플리케이션 성능 모니터링
5-3. 백업 전략 수립
# 정기적인 스냅샷 생성
curl -X PUT "localhost:9200/_snapshot/backup_repository/snapshot_$(date +%Y%m%d)" \
-H 'Content-Type: application/json' \
-d '{"indices": "*"}'
6. 자주 묻는 질문
Q: 싱글 노드에서도 cluster.initial_master_nodes 설정이 필요한가요? A: 네, Elasticsearch 7.x 이후부터는 싱글 노드라도 이 설정이 필수입니다. 본인의 노드명을 설정해주세요.
Q: AWS에서 자꾸 이 에러가 발생해요. A: 보안 그룹에서 9300 포트가 열려있는지 확인해보세요. 대부분 이 포트가 막혀있어서 발생합니다.
Q: Docker로 실행할 때 주의할 점이 있나요? A: Docker 네트워크 설정을 확인하고, 컨테이너 간 통신이 가능한지 확인해보세요.
master_not_discovered_exception 에러는 처음에는 복잡해 보이지만, 체계적으로 접근하면 충분히 해결할 수 있습니다. 가장 중요한 것은 차근차근 원인을 파악하는 것이에요.
이 글에서 제시한 방법들을 단계별로 따라해보시면 대부분의 문제는 해결될 거예요. 혹시 그래도 해결이 안 된다면 로그를 자세히 확인해보시고, 필요하다면 Elasticsearch 커뮤니티의 도움을 받아보세요. 운영 환경에서는 무엇보다 예방이 중요합니다. 정기적인 모니터링과 백업을 통해 이런 상황을 미연에 방지하는 것이 가장 좋은 방법이죠.