Ubuntu 18.04에서 ZooKeeper 단일 노드 설치 가이드

ZooKeeper 설치 개요 이미지: 데이터 센터 서버와 ZooKeeper 관련 다이어그램

요약

한문장 정의

ZooKeeper는 분산 환경에서 구성 정보, 이름, 동기화, 그룹 서비스 프로비저닝을 중앙에서 관리하는 Java 기반 오픈소스 서비스입니다.

목표 독자와 주요 의도

대상: Ubuntu 18.04를 운영하는 시스템 관리자와 DevOps 엔지니어
주요 의도: ZooKeeper 단일 노드 설치 및 기본 운영 준비
관련 의도 변형: Java 설치, systemd 서비스 등록, ZooKeeper 구성, 로컬 테스트

요구 사항

Ubuntu 18.04가 실행되는 서버
루트(root) 또는 sudo 권한을 가진 계정

중요: 프로덕션 환경에서는 단일 노드 구성이 가용성 요구를 충족하지 않습니다. 다중 노드(홀수 개의 노드) 클러스터 구성을 고려하세요.

소개 및 핵심 특징

ZooKeeper는 다음과 같은 상황에 적합합니다:

분산 시스템의 상태 정보 저장
구성 및 서비스 위치 정보 관리
분산 락 또는 리더 선출 같은 간단한 동기화

장점 요약: 신뢰성, 단순한 아키텍처, 빠른 처리, 낮은 지연, 확장성(클러스터 확장 시)

간단 용어: Znode — ZooKeeper의 계층적 데이터 노드. tickTime — 세션 타임아웃이나 리더 선출 등에 영향 주는 기본 시간 단위(밀리초).

준비 단계: 시스템 업데이트

먼저 시스템 패키지를 최신으로 업데이트합니다.

apt-get update -y
apt-get upgrade -y

업데이트가 끝나면 재부팅을 권장합니다.

reboot

노트: SSH 세션이 끊기므로 필요한 경우 로컬 콘솔이나 매니저 툴에서 실행하세요.

Java 설치

ZooKeeper는 Java로 작성되어 있습니다. Ubuntu 18.04 기본 저장소에 최신 Oracle Java가 없으므로 PPA를 추가합니다.

add-apt-repository ppa:linuxuprising/java

저장소를 갱신하고 Oracle Java 11을 설치합니다.

apt-get update -y
apt-get install oracle-java11-set-default

설치 후 Java 버전을 확인합니다.

java --version

예상 출력 예제:

java 11.0.2 2018-10-16 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.2+7-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.2+7-LTS, mixed mode)

Note: OpenJDK를 사용하려면 oracle-java11 대신 openjdk-11-jdk 패키지를 설치해도 됩니다.

ZooKeeper 전용 사용자 생성

서비스 보안을 위해 전용 시스템 사용자를 만듭니다.

useradd zookeeper -m
usermod --shell /bin/bash zookeeper
passwd zookeeper
usermod -aG sudo zookeeper

설명: zookeeper 사용자가 sudo 그룹에 추가되면 필요 시 제한된 관리 작업을 수행할 수 있습니다. 프로덕션에서는 sudo 권한을 더 엄격히 제어하세요.

ZooKeeper 설치

디스크에 상태와 로그를 저장할 디렉터리를 생성하고 권한을 설정합니다.

mkdir -p /data/zookeeper
chown -R zookeeper:zookeeper /data/zookeeper

/opt로 이동해 아파치 아카이브에서 배포판을 다운로드하고 압축을 풉니다. 이 가이드에서는 3.4.9 버전을 사용합니다(원본 자료 기준).

cd /opt
wget https://archive.apache.org/dist/zookeeper/zookeeper-3.4.9/zookeeper-3.4.9.tar.gz

tar -xvzf zookeeper-3.4.9.tar.gz
mv zookeeper-3.4.9 zookeeper
chown -R zookeeper:zookeeper /opt/zookeeper

중요: 최신 안정화 버전 사용을 권장합니다. 아카이브 대신 최신 릴리스 URL을 확인하세요.

구성 파일 만들기

ZooKeeper 설정 파일을 만듭니다.

nano /opt/zookeeper/conf/zoo.cfg

다음 내용을 추가합니다.

tickTime=2500
dataDir=/data/zookeeper
clientPort=2181
maxClientCnxns=80

설명: tickTime은 기본 시간 단위(밀리초)입니다. session 타임아웃과 내부 타이밍 동작에 영향을 줍니다. 단일 노드 테스트 목적일 경우 추가 서버 항목(예: server.1=…)은 필요 없습니다.

ZooKeeper 시작과 테스트 연결

설치를 완료한 뒤 ZooKeeper를 시작합니다.

cd /opt/zookeeper
bin/zkServer.sh start

예상 출력:

ZooKeeper JMX enabled by default
Using config: /opt/zookeeper/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED

로컬 클라이언트로 접속해 명령을 실행해 봅니다.

bin/zkCli.sh -server 127.0.0.1:2181

접속 성공 시 프롬프트가 나타납니다.

[zk: 127.0.0.1:2181(CONNECTED) 1]

help 명령으로 사용 가능한 클라이언트 명령을 확인할 수 있습니다.

help
ZooKeeper -server host:port cmd args
    stat path [watch]
    set path data [version]
    ls path [watch]
    ... (중략)

접속을 종료하려면 quit를 입력합니다.

quit

서비스 정지:

bin/zkServer.sh stop

출력 예시:

ZooKeeper JMX enabled by default
Using config: /opt/zookeeper/bin/../conf/zoo.cfg
Stopping zookeeper ... STOPPED

systemd 서비스 파일 만들기

서버 재부팅 시 자동 실행 및 관리 편의를 위해 systemd 유닛을 만듭니다.

nano /etc/systemd/system/zookeeper.service

파일 내용:

[Unit]
Description=Zookeeper Daemon
Documentation=http://zookeeper.apache.org
Requires=network.target
After=network.target

[Service]
Type=forking
WorkingDirectory=/opt/zookeeper
User=zookeeper
Group=zookeeper
ExecStart=/opt/zookeeper/bin/zkServer.sh start /opt/zookeeper/conf/zoo.cfg
ExecStop=/opt/zookeeper/bin/zkServer.sh stop /opt/zookeeper/conf/zoo.cfg
ExecReload=/opt/zookeeper/bin/zkServer.sh restart /opt/zookeeper/conf/zoo.cfg
TimeoutSec=30
Restart=on-failure

[Install]
WantedBy=default.target

데몬 리로드와 서비스 시작, 부팅 시 자동 시작을 등록합니다.

systemctl daemon-reload
systemctl start zookeeper
systemctl enable zookeeper

상태 확인:

systemctl status zookeeper

상태 출력 예시(요약):

? zookeeper.service - Zookeeper Daemon
   Loaded: loaded (/etc/systemd/system/zookeeper.service; disabled; vendor preset: enabled)
   Active: active (running) since Wed 2019-03-06 15:03:01 UTC; 5s ago
   ...

운영 체크리스트 (role 기반)

시스템 관리자
- Java 및 패키지 업데이트 정책 수립
- 디스크 사용량 모니터링 및 /data/zookeeper 백업 계획
- systemd 유닛 파일 권한과 로그 위치 확인
DevOps 엔지니어
- 프로덕션은 홀수 노드(3/5) 클러스터 권장
- 서버 간 시간 동기화(NTP) 보장
- 방화벽에서 2181, 2888, 3888 포트 정책 검토
애플리케이션 개발자
- 재시도 정책과 세션 타임아웃 튜닝
- 클라이언트 라이브러리의 ZooKeeper 연결 예외 처리

보안 권장 사항

ZooKeeper ACL을 사용해 Znode 접근 제어를 설정하세요.
운영 환경에서 외부 접속을 제한하고 내부 네트워크로만 클라이언트 포트를 열어 두세요.
로그 디렉터리와 데이터 디렉터리의 파일 권한을 최소권한으로 설정하세요.
TLS/SSL 및 인증 기능이 필요한 경우 최신 ZooKeeper 버전과 관련 설정을 확인하세요.

프로덕션으로 확장하기 위한 미니 플레이북

홀수 개의 노드를 준비하고 각 노드에 동일한 ZooKeeper 버전 설치
각 노드의 zoo.cfg에 server.N=host:peerPort:leaderElectionPort 항목 추가
각 노드의 dataDir에 myid 파일 생성(예: echo 1 > /data/zookeeper/myid)
방화벽과 라우팅을 구성해 노드 상호 연결 허용
단계별로 롤링 업그레이드를 계획하고, 스냅샷과 백업을 준비

문제 해결 팁

서버가 STARTED로 표시되지 않으면 로그 확인:

cat /opt/zookeeper/logs/zookeeper.out

클라이언트가 연결되지 않을 경우 포트 및 방화벽 확인:

ss -ltnp | grep 2181
ufw status

세션 타임아웃 이슈 발생 시 tickTime과 클라이언트 설정을 재검토

인수 기준

systemctl status zookeeper가 active (running)을 반환해야 합니다.
bin/zkCli.sh로 127.0.0.1:2181에 접속해 기본 명령(ls, create, get)을 수행할 수 있어야 합니다.
/data/zookeeper에 ZooKeeper가 데이터를 기록해야 합니다.
서비스가 재부팅 후 자동으로 시작되어야 합니다.

간단 용어집

Znode: ZooKeeper의 계층적 데이터 노드
tickTime: ZooKeeper의 기본 시간 단위(밀리초)
clientPort: 클라이언트 연결 포트(기본 2181)

요약 및 다음 단계

요약: 이 문서는 Ubuntu 18.04에 ZooKeeper 단일 노드를 설치하고 systemd로 서비스화하는 전 과정을 다룹니다. 개발/테스트 환경에서는 단일 노드가 유용하지만, 가용성과 일관성이 중요한 프로덕션 환경에서는 반드시 홀수 개의 노드로 클러스터를 구성하세요.

다음 권장 작업:

최신 ZooKeeper 안정화 버전으로 업그레이드 계획 수립
백업 및 모니터링(로그, 디스크, 메트릭) 설정
프로덕션 배포 전 보안(ACL, 네트워크 제한) 점검

중요: 추가 도움이 필요하면 사용 사례(테스트 vs 프로덕션), 노드 수, 네트워크 구성을 알려주시면 확장 가이드를 더 구체적으로 제공하겠습니다.

Ubuntu 18.04에 단일 노드 Apache ZooKeeper 설치 및 구성

요약