Apache Kudu 에서 시간 동기화(NTP)가 중요한 이유

Apache Kudu 를 처음 설치하고 Tablet Server 를 올렸는데, 로그에 "Clock unsynchronized" 에러가 찍히며 프로세스가 죽는 경험을 한 적 있으신가요? 분산 데이터베이스에서 "시계가 안 맞는다" 는 건 단순한 경고가 아니라 데이터 정합성을 보장할 수 없다 는 뜻이기 때문에, Kudu 는 아예 기동 자체를 거부합니다. 이 글은 Kudu 공식 Troubleshooting 문서 를 바탕으로, 왜 시간 동기화가 필수인지, 어떤 에러가 나오는지, 어떻게 고치는지를 정리합니다.

1. 왜 Kudu 는 시계에 민감한가

Kudu 는 내부적으로 Hybrid Logical Clock(HLC) 을 사용합니다. HLC 는 물리 시계(wall clock)와 논리 카운터를 결합한 타임스탬프로, 분산 노드 간 이벤트 순서를 결정하는 핵심 메커니즘입니다.

HLC 가 올바르게 동작하려면 물리 시계의 오차 범위(error bound) 를 알아야 합니다. NTP 데몬이 커널에 보고하는 이 오차 범위를 Kudu 가 읽어서, "지금 이 노드의 시각이 실제 시각과 최대 얼마나 차이 날 수 있는지" 를 판단합니다. 이 값이 너무 크면 — 즉 시계를 신뢰할 수 없으면 — 다음과 같은 문제가 생깁니다.

• 읽기 일관성 깨짐: 스냅샷 읽기 시점을 정확히 잡을 수 없어서 "과거 데이터가 보였다 안 보였다" 하는 현상 발생
• 쓰기 충돌 오판: 두 노드에서 같은 row 를 동시에 수정할 때, 어느 쪽이 먼저인지 판단 불가
• Raft 합의 지연: Leader election 과 log replication 에 사용하는 타임아웃 계산이 틀어짐

Kudu 는 이런 위험을 방지하기 위해, 시계 오차가 허용 범위를 넘으면 아예 서비스를 중단 합니다.

2. 실제로 만나는 에러 메시지

Kudu Master 또는 Tablet Server 로그에서 다음 에러들을 볼 수 있습니다.

2.1 시계가 아예 동기화되지 않은 경우

Clock unsynchronized. Status: Service unavailable: Error reading clock.

NTP 데몬이 설치되지 않았거나, 아직 동기화를 완료하지 못한 상태입니다. Kudu 는 ntp_gettime() 시스템 콜로 커널의 시계 상태를 확인하는데, 커널이 "동기화 안 됨" 을 보고하면 이 에러가 발생합니다.

2.2 동기화는 됐지만 오차가 너무 큰 경우

Clock synchronized, but error: 11130000, is past the maximum allowable error: 10000000

NTP 가 돌아가고 있지만, 추정 오차가 Kudu 의 허용 한계를 넘었습니다. 숫자의 단위는 마이크로초(us) 입니다. 위 예시는 "현재 오차 11.13초, 허용 한계 10초" 를 의미합니다.

2.3 기동 시 HybridClock 초기화 실패

Cannot initialize HybridClock. Clock synchronized but error was too high

위 2.2 와 같은 상황이 프로세스 시작 시점에 발생하면 이 메시지와 함께 기동이 실패합니다.

3. 핵심 설정 플래그

Kudu 의 시간 동기화 관련 주요 플래그는 다음과 같습니다.

경고: --max_clock_sync_error_usec 를 올려서 에러를 피하려는 유혹이 있지만, 이는 근본 해결이 아닙니다. 허용 오차를 늘리면 읽기/쓰기 일관성 보장이 약해집니다. NTP 를 제대로 설정하는 것이 정답입니다.

4. NTP 데몬 선택: ntpd vs chrony vs systemd-timesyncd

Kudu 는 커널의 시계 discipline 상태를 확인하기 때문에, NTP 데몬이 커널에 시간 정보를 제대로 보고해야 합니다. 모든 NTP 구현이 이를 지원하는 것은 아닙니다.

systemd-timesyncd 를 쓰면 안 되는 이유

Debian/Ubuntu 계열은 기본으로 systemd-timesyncd 가 활성화되어 있습니다. 이 서비스는 SNTP 클라이언트로서 시각을 맞추기는 하지만, ntp_adjtime() / ntp_gettime() 같은 커널 discipline API 를 통해 상태를 보고하지 않습니다. Kudu 는 정확히 이 API 를 통해 동기화 여부를 확인하기 때문에, systemd-timesyncd 만으로는 Kudu 가 "시계가 동기화됐다" 고 인식하지 못합니다.

# systemd-timesyncd 비활성화 후 chrony 또는 ntpd 로 교체
sudo systemctl stop systemd-timesyncd
sudo systemctl disable systemd-timesyncd

5. chrony 설정 (권장)

chrony 는 ntpd 보다 빠르게 동기화되고, VM 환경에서 시계가 크게 틀어졌을 때도 안정적으로 수렴합니다. Kudu 환경에서는 chrony 를 권장합니다.

5.1 설치

# Debian / Ubuntu
sudo apt-get install chrony
 
# RHEL / CentOS / Rocky
sudo yum install chrony

5.2 설정 파일 (/etc/chrony.conf)

# NTP 서버 — 최소 4개 권장
server time1.google.com iburst
server time2.google.com iburst
server time3.google.com iburst
server time4.google.com iburst
 
# AWS 환경이라면 아래를 추가 (또는 위 서버 대신 사용)
# server 169.254.169.123 prefer iburst
 
# GCE 환경이라면
# server metadata.google.internal prefer iburst
 
# Kudu 호환을 위해 반드시 활성화
rtcsync
 
# 시작 시 오차가 1초 이상이면 즉시 step 보정
makestep 1.0 3
 
# 최대 polling 간격 (2^7 = 128초). 기본값보다 짧게 잡으면 동기화 정밀도 향상
maxpoll 7

핵심 포인트:

• rtcsync: 이 옵션이 있어야 chrony 가 커널의 시계 discipline 을 활성화하고, Kudu 가 ntp_gettime() 으로 "synchronized" 상태를 읽을 수 있습니다. 이 한 줄을 빠뜨리면 Kudu 가 시계를 인식하지 못합니다.
• iburst: 데몬 시작 직후 빠르게 8개 패킷을 보내서 초기 동기화 시간을 단축합니다.
• makestep 1.0 3: 첫 3번의 업데이트에서 오차가 1초 이상이면 slew 대신 step 으로 즉시 보정합니다. VM 스냅샷 복원이나 재부팅 직후에 특히 유용합니다.

5.3 서비스 시작

sudo systemctl enable chronyd
sudo systemctl start chronyd

5.4 동기화 확인

chronyc tracking

출력에서 확인할 항목:

Reference ID    : D8EF2300 (time1.google.com)
Stratum         : 2
Ref time (UTC)  : Sat Apr 12 03:22:15 2026
System time     : 0.000023420 seconds fast of NTP time
Last offset     : +0.000012345 seconds
RMS offset      : 0.000025678 seconds
Root delay      : 0.012345678 seconds
Root dispersion : 0.001234567 seconds
Leap status     : Normal

• Leap status: Normal — 커널이 시계를 "동기화됨" 으로 인식. Kudu 가 정상 기동 가능
• System time — 현재 오차. 밀리초 미만이면 양호

# NTP 소스 서버 확인
chronyc sources -v
 
# 소스별 통계
chronyc sourcestats

6. ntpd 설정 (대안)

chrony 를 쓸 수 없는 환경이라면 ntpd 도 문제없이 동작합니다.

6.1 설치

# Debian / Ubuntu
sudo apt-get install ntp
 
# RHEL / CentOS
sudo yum install ntp

6.2 초기 시각 맞추기

ntpd 는 시작 시 시계 오차가 크면 수렴하는 데 수 분에서 수십 분 이 걸릴 수 있습니다. 먼저 ntpdate 또는 ntpd -q 로 시각을 한 번 맞춘 뒤 데몬을 시작하세요.

# 먼저 ntpd 가 꺼져 있는지 확인
sudo systemctl stop ntp
 
# 즉시 시각 보정
sudo ntpdate -b time.google.com
 
# 데몬 시작
sudo systemctl enable ntp
sudo systemctl start ntp

6.3 설정 파일 (/etc/ntp.conf)

server time1.google.com iburst
server time2.google.com iburst
server time3.google.com iburst
server time4.google.com iburst
 
# 최대 polling 간격 단축
maxpoll 7

6.4 동기화 확인

# 커널 시계 상태 확인
ntptime

출력에서 status 필드에 NANO 또는 OK 가 포함되어 있으면 정상입니다. UNSYNC 가 보이면 아직 동기화가 안 된 것입니다.

# NTP 피어 상태 요약
ntpstat
 
# 상세 피어 정보
ntpq -p

6.5 -x 플래그 주의

일부 배포판은 ntpd 시작 옵션에 -x 플래그를 넣어둡니다. 이 플래그는 step 보정을 비활성화하고 slew 만 허용하는데, 시계가 크게 틀어진 상태에서는 동기화에 극단적으로 오랜 시간 이 걸립니다. Kudu 노드에서는 -x 를 제거하는 것을 권장합니다.

# /etc/sysconfig/ntpd 또는 /etc/default/ntp 에서 확인
# OPTIONS="-x -u ntp:ntp" 에서 -x 를 제거
OPTIONS="-u ntp:ntp"

7. 클라우드 환경별 NTP 서버

클라우드 VM 에서는 해당 클라우드가 제공하는 NTP 서버를 쓰는 것이 네트워크 지연이 가장 짧아 오차가 최소화됩니다.

prefer 키워드는 해당 서버를 우선 참조하겠다는 의미입니다. 클라우드 내부 NTP 서버는 물리적으로 가까우므로 prefer 를 붙여두면 안정적입니다.

8. 트러블슈팅 체크리스트

Kudu 가 시계 관련 에러로 죽었을 때, 아래 순서로 확인하세요.

8.1 NTP 데몬이 돌고 있는가

# chrony 인 경우
sudo systemctl status chronyd
 
# ntpd 인 경우
sudo systemctl status ntp

8.2 systemd-timesyncd 가 대신 돌고 있지 않은가

timedatectl status

출력에 NTP service: systemd-timesyncd 가 보이면 교체가 필요합니다.

8.3 커널이 "동기화됨" 을 보고하는가

# chrony 환경
chronyc tracking | grep "Leap status"
# "Normal" 이면 정상
 
# ntpd 환경
ntptime | grep status
# "NANO" 또는 "OK" 가 포함되면 정상, "UNSYNC" 면 문제

8.4 추정 오차가 10초 이내인가

# chrony
chronyc tracking | grep "Root dispersion"
 
# ntpd
ntptime | grep "maximum error"

오차가 10초(10,000,000 us) 를 넘으면 Kudu 가 거부합니다. NTP 서버 연결 상태와 네트워크를 점검하세요.

8.5 NTP 서버에 도달 가능한가

# chrony
chronyc sources
 
# ntpd
ntpq -p

모든 소스가 ? 또는 unreachable 이면 방화벽에서 UDP 123 포트가 열려 있는지 확인하세요.

9. chrony 의 local reference 모드 주의사항

폐쇄망 환경에서 외부 NTP 서버에 접근할 수 없을 때, chrony 를 local reference 모드로 운영하는 경우가 있습니다. 이때 chrony local reference 노드 자체에는 Kudu 를 배포하지 마세요. Kudu 3.4 이하에서는 해당 노드의 ntptime 이 "unsynchronized" 를 보고하는 알려진 이슈가 있습니다. chronyc tracking 은 "Normal" 로 보여도 커널 discipline 상태가 다르게 보고될 수 있습니다.

해결 방법:

• chrony local reference 서버는 별도 노드 로 분리
• Kudu Master/Tablet Server 는 그 서버를 클라이언트로 참조 하도록 설정

10. Kudu 기동 전 최종 점검 스크립트

모든 Kudu 노드에서 기동 전에 돌릴 수 있는 간단한 점검 스크립트입니다.

#!/usr/bin/env bash
set -euo pipefail
 
echo "=== NTP 동기화 점검 ==="
 
# 1. systemd-timesyncd 가 비활성화되어 있는지
if systemctl is-active --quiet systemd-timesyncd 2>/dev/null; then
  echo "[FAIL] systemd-timesyncd 가 활성화되어 있습니다. 비활성화 후 chrony/ntpd 를 설치하세요."
  exit 1
fi
echo "[OK] systemd-timesyncd 비활성"
 
# 2. chrony 또는 ntpd 가 동작 중인지
if systemctl is-active --quiet chronyd 2>/dev/null; then
  echo "[OK] chronyd 동작 중"
  NTP_TYPE="chrony"
elif systemctl is-active --quiet ntp 2>/dev/null || systemctl is-active --quiet ntpd 2>/dev/null; then
  echo "[OK] ntpd 동작 중"
  NTP_TYPE="ntpd"
else
  echo "[FAIL] chrony 또는 ntpd 가 동작하지 않습니다."
  exit 1
fi
 
# 3. 커널 동기화 상태
if command -v ntptime &>/dev/null; then
  if ntptime 2>&1 | grep -q "UNSYNC"; then
    echo "[FAIL] 커널 시계가 아직 동기화되지 않았습니다. NTP 데몬이 수렴할 때까지 대기하세요."
    exit 1
  fi
  echo "[OK] 커널 시계 동기화 확인"
fi
 
# 4. 추정 오차 확인 (chrony)
if [ "$NTP_TYPE" = "chrony" ]; then
  OFFSET=$(chronyc tracking 2>/dev/null | grep "System time" | awk '{print $4}')
  echo "[INFO] 현재 시스템 시각 오차: ${OFFSET} seconds"
fi
 
echo ""
echo "=== 점검 완료. Kudu 기동 가능합니다. ==="

11. 정리

시간 동기화는 Kudu 운영의 가장 기본적인 전제 조건 입니다. 클러스터를 처음 구축할 때 NTP 를 먼저 잡아두면, 이후 운영에서 시계 관련 장애를 만날 일이 거의 없습니다. 반대로 이걸 무시하면 가장 이해하기 어려운 형태의 데이터 불일치를 만나게 됩니다.

이 글은 Apache Kudu 공식 Troubleshooting 문서 를 기반으로 작성되었습니다. 실제 클러스터 환경에서 NTP 설정이나 Kudu 운영에 대해 도움이 필요하시면 언제든 문의해 주세요.

— Data Dynamics 엔지니어링 팀