Apache Kafka를 사용하다 보면 가장 자주 마주치는 에러 중 하나가 바로 “Connection to node -1 could not be established. Broker may not be available” 입니다. 이 에러는 클라이언트가 Kafka 브로커에 연결할 수 없을 때 발생하며, 여러 가지 원인이 있을 수 있습니다.

실제 개발 환경에서 이 문제를 해결하면서 겪었던 경험을 바탕으로, 가장 효과적인 해결 방법들을 단계별로 정리해보겠습니다.

1. 에러 발생 원인 분석

이 에러가 발생하는 주요 원인들을 먼저 파악해보겠습니다.

가장 흔한 원인들

2. 기본 설정 확인 및 수정

가장 먼저 확인해야 할 기본 설정들입니다.

Kafka 브로커 상태 확인

# Kafka 프로세스 확인
ps aux | grep kafka

# 포트 사용 확인
netstat -tlnp | grep :9092

정상적인 경우 출력 예시:

tcp6       0      0 :::9092                 :::*                    LISTEN      12345/java

server.properties 핵심 설정

config/server.properties 파일에서 다음 설정을 확인하고 수정하세요:

# 기본 리스너 설정
listeners=PLAINTEXT://localhost:9092

# 외부 클라이언트 접속용 설정 (로컬 환경)
advertised.listeners=PLAINTEXT://localhost:9092

# 브로커 ID (클러스터 내 고유값)
broker.id=0

# ZooKeeper 연결 정보
zookeeper.connect=localhost:2181

3. 네트워크 설정 문제 해결

listeners와 advertised.listeners 차이점

이 두 설정의 차이를 이해하는 것이 중요합니다:

• listeners: Kafka 브로커가 실제로 바인딩할 네트워크 인터페이스
• advertised.listeners: 클라이언트에게 알려줄 접속 주소

다양한 환경별 설정 예시

로컬 개발 환경:

listeners=PLAINTEXT://localhost:9092
advertised.listeners=PLAINTEXT://localhost:9092

서버 환경 (고정 IP):

listeners=PLAINTEXT://0.0.0.0:9092
advertised.listeners=PLAINTEXT://192.168.1.100:9092

다중 네트워크 인터페이스:

listeners=INTERNAL://192.168.1.100:9092,EXTERNAL://10.0.0.100:9093
advertised.listeners=INTERNAL://192.168.1.100:9092,EXTERNAL://10.0.0.100:9093
listener.security.protocol.map=INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT
inter.broker.listener.name=INTERNAL

4. Docker 환경에서의 해결책

Docker를 사용할 때는 특별한 주의가 필요합니다.

Docker Compose 설정 예시

version: '3.8'
services:
  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

  kafka:
    image: confluentinc/cp-kafka:latest
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1

Docker 실행 시 주의사항

# 올바른 Docker 실행 명령
docker run -d \
  --name kafka \
  -p 9092:9092 \
  -e KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092 \
  -e KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181 \
  confluentinc/cp-kafka:latest

5. JAVA 환경 설정 확인

JAVA_HOME 설정 확인 및 수정

# 현재 JAVA_HOME 확인
echo $JAVA_HOME

# Java 버전 확인
java -version

# JAVA_HOME 설정 (Linux/Mac)
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

# 영구 설정을 위해 ~/.bashrc에 추가
echo 'export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64' >> ~/.bashrc
source ~/.bashrc

Windows 환경:

1. 시스템 속성 → 고급 → 환경 변수
2. JAVA_HOME 변수 추가: C:\Program Files\Java\jdk-11.0.x
3. Path에 %JAVA_HOME%\bin 추가

6. 단계별 문제 해결 프로세스

1단계: 서비스 상태 확인

# ZooKeeper 상태 확인
echo ruok | nc localhost 2181

# Kafka 로그 확인
tail -f /path/to/kafka/logs/server.log

2단계: 포트 충돌 확인

# 포트 사용 상태 확인
sudo lsof -i :9092
sudo lsof -i :2181

# 포트를 사용하는 프로세스 종료
sudo kill -9 [PID]

3단계: 설정 파일 검증

# server.properties 문법 확인
kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type brokers --entity-name 0

7. 테스트 및 검증 방법

연결 테스트 도구

# kafka-console-producer로 테스트
kafka-console-producer.sh --bootstrap-server localhost:9092 --topic test-topic

# kafka-console-consumer로 테스트
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic test-topic --from-beginning

# kafkacat을 이용한 연결 테스트
kafkacat -b localhost:9092 -L

브로커 메타데이터 확인

# 브로커 정보 조회
kafka-broker-api-versions.sh --bootstrap-server localhost:9092

# 토픽 목록 확인
kafka-topics.sh --bootstrap-server localhost:9092 --list

8. 예방 하거나, 평소 모니터링 하는 설정

로그 모니터링 설정

# 로그 레벨 설정 (log4j.properties)
log4j.logger.kafka=INFO
log4j.logger.org.apache.kafka=INFO

# 중요 로그 패턴 모니터링
tail -f server.log | grep -E "(ERROR|WARN|Connection)"

헬스체크 스크립트

#!/bin/bash
# kafka-health-check.sh

KAFKA_HOST="localhost:9092"
TOPIC="health-check"

# 토픽 생성 테스트
kafka-topics.sh --create --bootstrap-server $KAFKA_HOST --topic $TOPIC --partitions 1 --replication-factor 1 2>/dev/null

# 메시지 전송 테스트
echo "test message" | kafka-console-producer.sh --bootstrap-server $KAFKA_HOST --topic $TOPIC

if [ $? -eq 0 ]; then
    echo "Kafka is healthy"
    exit 0
else
    echo "Kafka connection failed"
    exit 1
fi

이러한 단계들을 차례대로 수행하면 대부분의 ‘Connection to node -1’ 에러를 해결할 수 있습니다. 각 환경에 맞는 설정을 적용하고, 지속적인 모니터링을 통해 안정적인 Kafka 클러스터를 운영하시기 바랍니다. 더 자세한 정보는 Apache Kafka 공식 문서와 Confluent Kafka 가이드를 참고 부탁드립니다.