기본 전제 조건
기본 전제 조건 (Basic Prerequisites)
HBase를 실제로 구동하기 전에 갖춰야 하는 시스템 요구 사항을 정리한 페이지예요. Java 버전, Hadoop 지원 버전, ZooKeeper 등 필수 요소를 먼저 확인해야 배포가 매끄러워요.
출처: 문서
본문
HBase는 Java Virtual Machine에서 실행되므로 모든 HBase 배포에는 JVM 런타임이 필요해요.
다음 표는 다양한 Java 버전에서 실행하는 것에 대한 HBase 커뮤니티의 권장 사항을 요약해요. ✅ 기호는 기본 수준의 테스트와 마주칠 수 있는 문제를 진단·해결하는 데 도움을 주겠다는 의지를 나타내며, 이들이 예상되는 배포 조합이에요. ⚠️ 항목은 이 조합에 문제가 있을 수 있으므로 배포 전략으로 채택하기 전에 더 많은 정보를 찾아봐야 한다는 뜻이에요. ❌는 이 조합이 동작하지 않는다는 뜻이에요. 더 오래된 Java 버전이 HBase 커뮤니티에서 deprecated로 간주되거나, 이 조합이 동작하지 않는 것으로 알려졌다는 뜻이에요. 더 새로운 JDK와 더 오래된 HBase 릴리스의 조합은, 호환성 보장 하에서 해결할 수 없는 알려진 호환성 문제가 있어 그 조합이 불가능할 가능성이 높아요. 어떤 경우에는 제한 사항에 대한 구체적인 지침(예: 컴파일·단위 테스트가 동작하는지, 특정 운영 이슈 등)도 함께 명시돼요. 여기에 나열되지 않은 조합은 모두 ❌로 간주하세요.
HBase는 다운스트림 사용자가 OpenJDK 프로젝트나 벤더의 Long-Term Supported(LTS)로 표시된 JDK 릴리스에만 의존할 것을 권장해요. 이 글을 쓰는 시점에 다음 JDK 릴리스는 LTS가 아니며 Apache HBase 커뮤니티에서 테스트하거나 사용을 권장하지 않아요: JDK9, JDK10, JDK12, JDK13, JDK14. 이 결정에 대한 커뮤니티 논의는 HBASE-20264에서 확인할 수 있어요.
현재 Apache HBase 프로젝트가 수행하는 모든 테스트는 JVM의 HotSpot 변형에서 실행돼요. JDK 배포판을 선택할 때 이것을 고려하세요.
릴리스 라인별 Java 지원
| HBase Version | JDK 6 | JDK 7 | JDK 8 | JDK 11 | JDK 17 |
|---|---|---|---|---|---|
| HBase 2.6 | ❌ | ❌ | ✅ | ✅ | ✅ |
| HBase 2.5 | ❌ | ❌ | ✅ | ✅ | ⚠️* |
| HBase 2.4 | ❌ | ❌ | ✅ | ✅ | ❌ |
| HBase 2.3 | ❌ | ❌ | ✅ | ⚠️* | ❌ |
| HBase 2.0-2.2 | ❌ | ❌ | ✅ | ❌ | ❌ |
| HBase 1.2+ | ❌ | ✅ | ✅ | ❌ | ❌ |
| HBase 1.0-1.1 | ❌ | ✅ | ⚠️ | ❌ | ❌ |
| HBase 0.98 | ✅ | ✅ | ⚠️ | ❌ | ❌ |
| HBase 0.94 | ✅ | ✅ | ❌ | ❌ | ❌ |
JDK11 지원의 예비 지원은 HBase 2.3.0에서, JDK17 지원은 HBase 2.5.x에서 도입됐어요. 우리는 pre commit 검사와 nightly 검사에서 JDK11/17로 테스트 스위트를 컴파일·실행할 거예요. 해당 JDK 버전으로 일부 IT를 실행했고 커뮤니티에서 실제 운영 클러스터에 그 JDK 버전을 사용하는 사용자가 있는 한 지원을 ✅로 표시할 거예요.
HBase의 JDK11/JDK17 지원은 HBASE-22972와 HBASE-26038을 참고하세요. HBase에도 영향을 줄 수 있는 Hadoop의 JDK11/JDK17 지원은 HADOOP-15338과 HADOOP-17177을 참고하세요.
클러스터의 각 노드에 JAVA_HOME을 설정해야 해요. hbase-env.sh가 이를 위한 편리한 메커니즘을 제공해요.
운영 체제 유틸리티 (Operating System Utilities)
ssh
HBase는 클러스터 노드 간 통신에 Secure Shell(ssh) 명령과 유틸리티를 광범위하게 사용해요. 클러스터의 각 서버는 Hadoop과 HBase 데몬이 관리될 수 있도록 ssh가 실행되고 있어야 해요. 비밀번호가 아닌 공유 키를 사용해 Master 및 임의의 백업 Master에서 로컬 노드를 포함한 모든 노드에 SSH로 연결할 수 있어야 해요. Linux 또는 Unix 시스템에서 이러한 설정의 기본 방법론은 "Procedure: Configure Passwordless SSH Access" 챕터에서 볼 수 있어요. 클러스터 노드가 OS X를 사용한다면 Hadoop 위키의 SSH: Setting up Remote Desktop and Enabling Self-Login 섹션을 참고하세요.
DNS
HBase는 로컬 호스트명을 사용해 자체 IP 주소를 보고해요.
NTP
클러스터 노드의 시계는 동기화되어야 해요. 약간의 변동은 허용되지만, 더 큰 스큐(skew)는 예측 불가능하고 갑작스러운 동작을 유발할 수 있어요. 시간 동기화는 클러스터에서 설명할 수 없는 문제가 보이면 가장 먼저 확인해야 할 것 중 하나예요. 클러스터에서 Network Time Protocol(NTP) 서비스나 다른 시간 동기화 메커니즘을 실행하고 모든 노드가 동일한 서비스를 바라보도록 하는 것이 권장돼요. NTP 설정은 *The Linux Documentation Project (TLDP)*의 Basic NTP Configuration을 참고하세요.
파일·프로세스 수 제한 (ulimit)
Apache HBase는 데이터베이스예요. 한 번에 많은 수의 파일을 열 수 있는 능력이 필요해요. 많은 Linux 배포판은 단일 사용자가 열 수 있는 파일 수를 1024(구버전 OS X에서는 256)로 제한해요. HBase를 실행하는 사용자로 로그인해 ulimit -n 명령을 실행하면 서버의 이 제한을 확인할 수 있어요. 제한이 너무 낮을 때 겪을 수 있는 문제 일부는 the Troubleshooting section을 참고하세요. 다음과 같은 오류도 보일 수 있어요.
2010-04-06 03:04:37,542 INFO org.apache.hadoop.hdfs.DFSClient: Exception increateBlockOutputStream java.io.EOFException 2010-04-06 03:04:37,542 INFO org.apache.hadoop.hdfs.DFSClient: Abandoning block blk_-6935524980745310745_1391901
ulimit을 최소 10,000, 더 바람직하게는 10,240으로 올리는 것이 권장돼요. 값이 보통 1024의 배수로 표현되기 때문이에요. 각 ColumnFamily는 최소 하나의 StoreFile을 가지며, region이 부하를 받으면 6개 이상의 StoreFile을 가질 수도 있어요. 필요한 열린 파일 수는 ColumnFamily 수와 region 수에 따라 달라져요. 다음은 RegionServer에서 잠재적인 열린 파일 수를 계산하는 대략적인 공식이에요.
잠재적인 열린 파일 수 계산하기 (Calculate the Potential Number of Open Files):
(StoreFiles per ColumnFamily) x (regions per RegionServer)
예를 들어 스키마가 region당 3개의 ColumnFamily를 가지고 각 ColumnFamily당 평균 3개의 StoreFile이 있으며 RegionServer당 100개의 region이 있다고 가정하면, JVM은 열린 JAR 파일, 설정 파일 등을 제외하고 3 * 3 * 100 = 900개의 파일 디스크립터를 열어요. 파일을 여는 것은 리소스를 많이 차지하지 않고, 사용자가 너무 많은 파일을 열도록 허용하는 위험은 최소예요.
또 다른 관련 설정은 사용자가 한 번에 실행할 수 있는 프로세스 수예요. Linux와 Unix에서 프로세스 수는 ulimit -u 명령으로 설정해요. 이는 주어진 사용자에게 사용 가능한 CPU 수를 제어하는 nproc 명령과 혼동해서는 안 돼요. 부하가 걸리면 ulimit -u가 너무 낮으면 OutOfMemoryError 예외가 발생할 수 있어요.
HBase 프로세스를 실행하는 사용자에 대한 최대 파일 디스크립터·프로세스 수를 구성하는 것은 HBase 설정이 아니라 운영 체제 설정이에요. 또한 설정이 실제로 HBase를 실행하는 사용자에게 적용되는지 확인하는 것도 중요해요. HBase를 시작한 사용자와 그 사용자의 ulimit 설정을 보려면 해당 인스턴스의 HBase 로그 첫 줄을 확인하세요.
예: Ubuntu의 ulimit 설정 (Example: ulimit Settings on Ubuntu)
Ubuntu에서 ulimit 설정을 구성하려면 /etc/security/limits.conf를 편집하세요. 이 파일은 네 개의 컬럼이 있는 공백 구분 파일이에요. 이 파일 형식에 대한 자세한 내용은 limits.conf man 페이지를 참고하세요. 다음 예제에서 첫 줄은 hadoop이라는 운영 체제 사용자에 대해 열린 파일 수(nofile)의 soft·hard 한도를 32768로 설정해요. 두 번째 줄은 같은 사용자에 대해 프로세스 수를 32000으로 설정해요.
hadoop - nofile 32768 hadoop - nproc 32000
설정은 Pluggable Authentication Module(PAM) 환경이 이들을 사용하도록 지시된 경우에만 적용돼요. PAM이 이 한도를 사용하도록 구성하려면 /etc/pam.d/common-session 파일에 다음 줄이 포함되어 있는지 확인하세요.
session required pam_limits.so
Linux 셸 (Linux Shell)
HBase와 함께 제공되는 모든 셸 스크립트는 GNU Bash 셸에 의존해요.
Windows
Windows 머신에서 프로덕션 시스템을 실행하는 것은 권장되지 않아요.
Hadoop
다음 표는 각 HBase 버전에서 지원하는 Hadoop 버전을 요약해요. 표에 나타나지 않는 더 오래된 버전은 지원되지 않고 필요한 기능이 없을 가능성이 높은 것으로 간주되며, 더 새로운 버전은 테스트되지 않았지만 적합할 수 있어요.
HBase 버전에 따라 가장 적절한 Hadoop 버전을 선택해야 해요. Apache Hadoop이나 벤더의 Hadoop 배포판을 사용할 수 있어요. 여기서는 구분하지 않아요. Hadoop 벤더에 대한 정보는 the Hadoop wiki를 참고하세요.
Hadoop 1.x와 비교해 Hadoop 2.x는 더 빠르고 short-circuit reads(참고: Leveraging local data) 같은 기능이 포함되어 HBase 랜덤 읽기 프로파일을 개선하는 데 도움을 줘요. Hadoop 2.x는 또한 전반적인 HBase 경험을 개선하는 중요한 버그 수정도 포함해요. HBase는 더 이전 버전의 Hadoop에서 실행하는 것을 지원하지 않아요. 다른 HBase 버전에 특정된 요구 사항은 아래 표를 참고하세요.
오늘날 마지막 Hadoop 2.x 릴리스인 2.10.2가 몇 년 전에 릴리스됐고, Hadoop 커뮤니티가 공식적으로 Hadoop 2.x를 EOL 처리하지는 않았지만 아주 오랜 시간 동안 Hadoop 2.x 릴리스가 없으므로 Hadoop 3.x가 권장돼요.
이 표를 해석하는 범례:
- ✅ = 완전히 동작하도록 테스트됨
- ❌ = 완전히 동작하지 않는 것으로 알려짐, 또는 CVE가 있어 더 새로운 마이너 릴리스에서 지원을 제거함
- ⚠️ = 테스트되지 않음, 동작할 수도·안 할 수도 있음
| HBase-2.5.x | HBase-2.6.x | |
|---|---|---|
| Hadoop-2.10.[0-1] | ❌ | ❌ |
| Hadoop-2.10.2+ | ✅ | ✅ |
| Hadoop-3.1.0 | ❌ | ❌ |
| Hadoop-3.1.1+ | ❌ | ❌ |
| Hadoop-3.2.[0-2] | ❌ | ❌ |
| Hadoop-3.2.3+ | ✅ | ❌ |
| Hadoop-3.3.[0-1] | ❌ | ❌ |
| Hadoop-3.3.[2-4] | ✅ | ❌ |
| Hadoop-3.3.5+ | ✅ | ✅ |
| Hadoop-3.4.0+ | ✅ (2.5.11+) | ✅ (2.6.2+) |
활성 릴리스 라인의 Hadoop 버전 지원 매트릭스 (Hadoop version support matrix for active release lines)
| HBase-2.3.x | HBase-2.4.x | |
|---|---|---|
| Hadoop-2.10.x | ✅ | ✅ |
| Hadoop-3.1.0 | ❌ | ❌ |
| Hadoop-3.1.1+ | ✅ | ✅ |
| Hadoop-3.2.x | ✅ | ✅ |
| Hadoop-3.3.x | ✅ | ✅ |
EOM 2.3+ 릴리스 라인의 Hadoop 버전 지원 매트릭스 (Hadoop version support matrix for EOM 2.3+ release lines)
| HBase-2.0.x | HBase-2.1.x | HBase-2.2.x | |
|---|---|---|---|
| Hadoop-2.6.1+ | ✅ | ❌ | ❌ |
| Hadoop-2.7.[0-6] | ❌ | ❌ | ❌ |
| Hadoop-2.7.7+ | ✅ | ✅ | ❌ |
| Hadoop-2.8.[0-2] | ❌ | ❌ | ❌ |
| Hadoop-2.8.[3-4] | ✅ | ✅ | ❌ |
| Hadoop-2.8.5+ | ✅ | ✅ | ✅ |
| Hadoop-2.9.[0-1] | ⚠️ | ❌ | ❌ |
| Hadoop-2.9.2+ | ⚠️ | ⚠️ | ✅ |
| Hadoop-3.0.[0-2] | ❌ | ❌ | ❌ |
| Hadoop-3.0.3+ | ❌ | ✅ | ❌ |
| Hadoop-3.1.0 | ❌ | ❌ | ❌ |
| Hadoop-3.1.1+ | ❌ | ✅ | ✅ |
EOM 2.x 릴리스 라인의 Hadoop 버전 지원 매트릭스 (Hadoop version support matrix for EOM 2.x release lines)
| HBase-1.5.x | HBase-1.6.x | HBase-1.7.x | |
|---|---|---|---|
| Hadoop-2.7.7+ | ✅ | ❌ | ❌ |
| Hadoop-2.8.[0-4] | ❌ | ❌ | ❌ |
| Hadoop-2.8.5+ | ✅ | ✅ | ✅ |
| Hadoop-2.9.[0-1] | ❌ | ❌ | ❌ |
| Hadoop-2.9.2+ | ✅ | ✅ | ✅ |
| Hadoop-2.10.x | ⚠️ | ✅ | ✅ |
EOM 1.5+ 릴리스 라인의 Hadoop 버전 지원 매트릭스 (Hadoop version support matrix for EOM 1.5+ release lines)
| HBase-1.0.x (Hadoop 1.x is NOT supported) | HBase-1.1.x | HBase-1.2.x | HBase-1.3.x | HBase-1.4.x | |
|---|---|---|---|---|---|
| Hadoop-2.4.x | ✅ | ✅ | ✅ | ✅ | ❌ |
| Hadoop-2.5.x | ✅ | ✅ | ✅ | ✅ | ❌ |
| Hadoop-2.6.0 | ❌ | ❌ | ❌ | ❌ | ❌ |
| Hadoop-2.6.1+ | ⚠️ | ⚠️ | ✅ | ✅ | ❌ |
| Hadoop-2.7.0 | ❌ | ❌ | ❌ | ❌ | ❌ |
| Hadoop-2.7.1+ | ⚠️ | ⚠️ | ✅ | ✅ | ✅ |
EOM 1.x 릴리스 라인의 Hadoop 버전 지원 매트릭스 (Hadoop version support matrix for EOM 1.x release lines)
| HBase-0.92.x | HBase-0.94.x | HBase-0.96.x | HBase-0.98.x (Support for Hadoop 1.1+ is deprecated.) | |
|---|---|---|---|---|
| Hadoop-0.20.205 | ✅ | ❌ | ❌ | ❌ |
| Hadoop-0.22.x | ✅ | ❌ | ❌ | ❌ |
| Hadoop-1.0.x | ❌ | ❌ | ❌ | ❌ |
| Hadoop-1.1.x | ⚠️ | ✅ | ✅ | ⚠️ |
| Hadoop-0.23.x | ❌ | ✅ | ⚠️ | ❌ |
| Hadoop-2.0.x-alpha | ❌ | ⚠️ | ❌ | ❌ |
| Hadoop-2.1.0-beta | ❌ | ⚠️ | ✅ | ❌ |
| Hadoop-2.2.0 | ❌ | ⚠️ | ✅ | ✅ |
| Hadoop-2.3.x | ❌ | ⚠️ | ✅ | ✅ |
| Hadoop-2.4.x | ❌ | ⚠️ | ✅ | ✅ |
| Hadoop-2.5.x | ❌ | ⚠️ | ✅ | ✅ |
EOM pre-1.0 릴리스 라인의 Hadoop 버전 지원 매트릭스 (Hadoop version support matrix for EOM pre-1.0 release lines)
대략 Hadoop 2.7.0 시점부터 Hadoop PMC는 메이저 버전 2 릴리스 라인의 새 마이너 릴리스를 안정적이지 않다고 / 프로덕션 준비가 안 됐다고 표현하는 습관을 들였어요. 따라서 HBase는 다운스트림 사용자에게 이 릴리스 위에서 실행하지 말 것을 명시적으로 조언해요. 추가로 2.8.1 릴리스도 Hadoop PMC가 같은 경고를 줬다는 점을 유의하세요. 참고로 Apache Hadoop 2.7.0, Apache Hadoop 2.8.0, Apache Hadoop 2.8.1, Apache Hadoop 2.9.0 릴리스 발표를 참고하세요.
Hadoop PMC는 3.1.0 릴리스를 안정적이지 않다고 / 프로덕션 준비가 안 됐다고 명명했어요. 따라서 HBase는 다운스트림 사용자에게 이 릴리스 위에서 실행하지 말 것을 명시적으로 조언해요. 참고로 Hadoop 3.1.0 릴리스 발표를 보세요.
HBase는 Hadoop에 의존하므로 lib 디렉터리 아래에 Hadoop jar를 번들해요. 번들된 jar는 stand-alone 모드에서만 사용하기 위한 것이에요. 분산 모드에서는 클러스터에 배포된 Hadoop 버전이 HBase 아래의 것과 일치하는 것이 중요해요. 버전 불일치 문제를 피하려면 HBase lib 디렉터리의 hadoop jar를 클러스터에서 실행 중인 버전의 동등한 hadoop jar로 교체하세요. HBase 아래의 jar를 전체 클러스터에 걸쳐 교체해야 한다는 것을 확인하세요. Hadoop 버전 불일치 문제는 다양한 형태로 나타나요. HBase가 멈춘 것처럼 보이면 불일치를 확인하세요.
HBase 바이너리 릴리스 및 Maven 아티팩트의 Hadoop 3 지원 (Hadoop 3 Support for the HBase Binary Releases and Maven Artifacts)
HBase 2.5.1 이하에서 공식 HBase 바이너리 릴리스와 Maven 아티팩트는 Hadoop 2.x로 빌드됐어요.
HBase 2.5.2부터 HBase는 Hadoop 2.x와 Hadoop 3.x 모두로 빌드된 바이너리 릴리스와 Maven 아티팩트를 제공해요. Hadoop 2 아티팩트에는 버전 접미사가 없고, Hadoop 3 아티팩트는 버전에 -hadoop-3 접미사를 추가해요. 즉 hbase-2.5.2-bin.tar.gz.asc는 Hadoop 2로 빌드된 바이너리 릴리스이고, hbase-2.5.2-hadoop3-bin.tar.gz는 Hadoop 3으로 빌드된 릴리스예요.
Hadoop 3 버전 정책 (Hadoop 3 version policy)
각 HBase 릴리스에는 기본 Hadoop 3 버전이 있어요. 이는 빌드 중에 Hadoop 3 버전이 지정되지 않은 경우와 공식 바이너리 릴리스·아티팩트를 빌드할 때 사용돼요. 일반적으로 새 마이너 버전(즉 2.5.0)이 릴리스될 때 기본 버전은 릴리스 프로세스 시작 시점의 최신 지원 Hadoop 3 버전으로 설정돼요.
HBase 2.5.10과 2.6.1까지는 HBase가 패치 릴리스에서 더 새로운 Hadoop 3 릴리스 지원을 추가했더라도 기본 Hadoop 3 버전(그리고 공식 바이너리 릴리스에 사용된 것)은 업데이트되지 않았어요. 이는 업그레이드를 단순화했지만, HBase 릴리스가 수정이 포함된 더 새로운 Hadoop 릴리스가 있음에도 불구하고 수정되지 않은 오래된 CVE를 Hadoop과 Hadoop 의존성 양쪽에서 자주 포함한다는 뜻이었어요.
HBase 2.5.11과 2.6.2부터 기본 Hadoop 3 버전은 항상 최신 지원 Hadoop 3 버전으로 설정되며, -hadoop3 바이너리 릴리스와 아티팩트에도 사용돼요. 이는 HBase 바이너리 릴리스에 포함된 알려진 CVE 수를 대폭 줄이고 Hadoop의 모든 수정과 개선이 포함되도록 보장해요.
dfs.datanode.max.transfer.threads
HDFS DataNode는 한 번에 제공할 파일 수에 상한이 있어요. 로딩을 하기 전에 Hadoop의 conf/hdfs-site.xml을 구성해 dfs.datanode.max.transfer.threads 값을 최소한 다음으로 설정했는지 확인하세요.
위 구성 후 HDFS를 재시작하세요.
이 설정이 없으면 이상하게 보이는 실패가 발생해요. 한 가지 징후는 누락된 블록에 대한 불만이에요. 예:
10/12/08 20:10:31 INFO hdfs.DFSClient: Could not obtain block blk_XXXXXXXXXXXXXXXXXXXXXX_YYYYYYYY from any node: java.io.IOException: No live nodes contain current block. Will get new block locations from namenode and retry...
또한 Case Studies를 참고하고, 이 속성은 이전에 dfs.datanode.max.xcievers로 알려졌다는 점을 유의하세요(예: Hadoop HDFS: Deceived by Xciever).
ZooKeeper 요구 사항 (ZooKeeper Requirements)
Apache ZooKeeper quorum이 필요해요. 정확한 버전은 HBase 버전에 따라 달라지지만, 1.0.0에서 기본이 된 useMulti 기능으로 인해(HBASE-16598 참고) 최소 ZooKeeper 버전은 3.4.x예요.