업그레이드 경로

업그레이드 경로 (Upgrade Paths)

이 문서는 HBase를 메이저 버전 간에 업그레이드할 때의 상세 경로와 호환성 고려 사항을 설명해요. 2.x에서 3.x로, 2.0.x-2.2.x에서 2.3+로, 1.x에서 2.x로 가는 경로를 다뤄요. 업그레이드 전에 이 문서를 정독하면 예상치 못한 문제를 피할 수 있어요.

출처: 문서

본문

2.x에서 3.x로 업그레이드

RegionServer Grouping 기능이 재구현됐어요. 자세한 내용은 Apache HBase Operational Management의 Migrating From Old Implementation 섹션을 참고하세요.

hbase:namespace 테이블이 제거되고 hbase:meta에 통합됐어요. 자세한 내용은 Data Model을 참고하세요.

2.3.x에서 hbase-2.4.x로 업그레이드하는 데 특별한 고려 사항은 없어요. 더 이전 버전에서는 Upgrade from 2.0.x-2.2.x to 2.3+ 가이드를 따르세요. 일반적으로 2.2.x는 롤링 업그레이드가 가능해야 하고, 2.1.x 또는 2.0.x의 경우 먼저 Upgrade from 2.0 or 2.1 to 2.2+ 장애물을 넘겨야 해요.

2.0.x-2.2.x에서 2.3+로 업그레이드

이전 버전에서 hbase-2.3.x로 업그레이드하는 데 특별한 고려 사항은 없어요. 2.2.x부터는 롤링 업그레이드가 가능해야 해요. 2.1.x 또는 2.0.x의 경우 먼저 Upgrade from 2.0 or 2.1 to 2.2+ 장애물을 넘겨야 해요.

업그레이드된 ZooKeeper 의존성 버전

Apache ZooKeeper에 대한 의존성이 3.5.7로 업그레이드됐어요(HBASE-24132). 3.4.x가 EOL이기 때문이에요. 더 새로운 3.5.x 클라이언트는 더 오래된 3.4.x 서버와 호환돼요. 하지만 HBase를 스탠드얼론 모드로 사용하며 in-place 업그레이드를 수행한다면 ZooKeeper 커뮤니티가 문서화한 몇 가지 업그레이드 단계가 있어요. 이것은 프로덕션 배포에는 영향을 주지 않지만 개발자 로컬 환경에는 영향을 줄 수 있어요.

새로운 In-Master Procedure Store

주목할 점은 HBase 2.3.0이 in-Master Procedure Store 구현을 변경한다는 것이에요. 전용 사용자 지정 store였던 것을 대신 표준 HBase Region을 사용하게 됐어요(HBASE-23326). 옛 형식에서 새 형식으로의 마이그레이션은 새 2.3.0 Master가 시작 시 자동으로 실행해요. 옛 사용자 지정 구현 파일을 *${hbase.rootdir}*에 호스팅했던 옛 MasterProcWALs 디렉터리는 성공적인 마이그레이션 시 삭제돼요. 새 MasterProc 하위 디렉터리가 이를 대체해 새 Procedure Store in-Master Region의 Store 파일과 WAL을 호스팅해요.

in-Master Region은 파일 시스템에서 ${hbase.rootdir}/data 아래가 아닌 ${hbase.rootdir}/MasterProc의 대체 위치에 쓴다는 점에서 특이해요. 그리고 특수 Procedure Store in-Master Region은 활성 Master 자신을 제외한 모든 클라이언트로부터 숨겨져요. 그 외에는 Master 프로세스가 플러시와 컴팩션을 실행하고, 과도하게 플러시될 때 WAL을 아카이빙하는 등 다른 Region과 같아요. 그 파일들은 적절한 파일 시스템 위치를 가리키기만 하면 표준 Region 및 Store 파일 도구로 읽어 트리아지와 분석할 수 있어요.

마이그레이션 후에는 옛 코드로 활성 master를 시작하지 않도록 해야 해요. 새 procedure store를 인식하지 못하기 때문이에요. 그래서 백업 master(s)를 먼저 새 2.3으로 업그레이드한 다음 활성 master를 업그레이드하는 것이 좋아요. 달리 명시되지 않는 한, 이것은 모든 업그레이드에 권장되는 방식이에요. 즉 백업 master(s)를 먼저, 그다음 활성 master, 그다음 region servers 순서랍니다.

2.0 또는 2.1에서 2.2+로 업그레이드

HBase 2.2+는 Region을 할당/할당 해제/이동하는 새 Procedure 형식을 사용해요. HBase 2.1과 2.0의 Unassign/Assign Procedure 타입은 처리하지 않아요. 업그레이드는 새 2.2 Master를 시작하기 전에 먼저 Master Procedure Store에서 옛 스타일의 Procedures를 비워야 해요. 그래서 옛 버전(2.0 또는 2.1) Master를 죽이기 전에 transition 중인 region이 없어야 해요. 그리고 새 버전(2.2+) Master가 올라오면 RegionServer를 하나씩 롤링 업그레이드할 수 있어요.

2.1.1+ 또는 2.0.3+ 클러스터를 운영 중이라면 더 안전한 방법이 있어요. Master를 업그레이드하려면 네 단계가 필요해요.

  1. 활성 및 대기 Masters를 모두 종료해요(클러스터는 중단 없이 계속 읽기와 쓰기를 제공할 거예요).
  2. Master의 hbase-site.xml에서 hbase.procedure.upgrade-to-2-2 프로퍼티를 true로 설정하고 여전히 2.1.1+(또는 2.0.3+) 버전을 사용해 Master 하나만 시작해요.
  3. Master가 종료될 때까지 기다려요. 종료 원인으로 Master 로그에 'UPGRADE OK: All existed procedures have been finished, quit...' 메시지가 있는지 확인하세요. 이제 Procedure Store가 비어 있어요.
  4. 새 2.2+ 버전으로 새 Masters를 시작해요.

그런 다음 RegionServer를 하나씩 롤링 업그레이드할 수 있어요. 자세한 내용은 HBASE-21075를 참고하세요.

이 단계를 수행하지 않으면 2.2+ master를 시작할 때 master 로그에서 다음 예외를 볼 수 있어요.

org.apache.hadoop.hbase.HBaseIOException: Unsupported procedure type class org.apache.hadoop.hbase.master.assignment.UnassignProcedure found

1.x에서 2.x로 업그레이드

이 섹션에서는 먼저 이전 안정 HBase 릴리스에 비해 중요한 변경 사항을 짚은 다음 업그레이드 과정을 살펴볼 거예요. 놀라움을 피하기 위해 전자를 주의 깊게 읽으세요.

주목할 변경 사항!

먼저 HBase 2.0+로 업그레이드할 때 부딪힐 수 있는 배포/운영 변경을 다룰 거예요. 그 후 다운스트림 애플리케이션을 위한 변경을 짚을 거예요. Coprocessors는 운영 섹션에서 다뤄진다는 점에 유의하세요. 또한 이 섹션은 관심을 가질 만한 새 기능에 대한 정보를 전달하기 위한 것이 아님에 유의하세요. 변경 사항의 전체 요약은 업그레이드하려는 버전의 소스 릴리스 산출물에 있는 CHANGES.txt 파일을 참고하세요.

HBase 2.0+의 기본 사전 준비 최소치 업데이트

Basic Prerequisites 섹션에 나와 있듯이 HBase 2.0+는 Java 8과 Hadoop 2.6의 최소 요구가 있어요. HBase 커뮤니티는 HBase 버전을 업그레이드하기 전에 필요한 사전 준비 업그레이드를 이미 완료했는지 확인하는 것을 권장해요.

HBCK는 HBase 서버 버전과 일치해야 함

HBase 2.0+ 클러스터에 HBase 1.x 버전의 HBCK를 사용하면 안 돼요. HBCK는 HBase 서버 버전과 강하게 연결되어 있어요. 이전 릴리스의 HBCK 도구를 HBase 2.0+ 클러스터에 사용하면 해당 클러스터를 복구할 수 없는 방식으로 파괴적으로 변경할 거예요.

HBase 2.0부터 HBCK(A.K.A HBCK1 또는 hbck1)는 일부 비공개 시스템 내부의 상태를 보고할 수 있는 읽기 전용 도구이지만 hbase2의 동작을 이해하지 못해 상태를 자주 잘못 읽어요.

HBCK의 대체에 대한 내용은 Operations and Management 문서를 참고하세요.

관련하여, 업그레이드 전에 hbck1이 INCONSISTENCIES가 없다고 보고하는지 확인하세요. 업그레이드 후 hbase1 유형의 불일치를 고치는 것은 복잡한 과정이에요.

HBase 2.0+에 더 이상 없는 구성 설정

다음 구성 설정은 더 이상 적용되지 않거나 사용할 수 없어요. 자세한 내용은 상세 릴리스 노트를 참고하세요.

  • hbase.config.read.zookeeper.config (마이그레이션 세부사항은 upgrade2.0.zkconfig 참고)
  • hbase.zookeeper.useMulti (HBase는 이제 항상 ZK의 multi 기능을 사용)
  • hbase.rpc.client.threads.max
  • hbase.rpc.client.nativetransport
  • hbase.fs.tmp.dir
  • hbase.bucketcache.combinedcache.enabled
  • hbase.bucketcache.ioengine는 더 이상 'heap' 값을 지원하지 않음.
  • hbase.bulkload.staging.dir
  • hbase.balancer.tablesOnMaster는 엄밀히 말하면 제거되지 않았지만 그 의미가 근본적으로 바뀌었고 사용자가 설정해서는 안 돼요. 자세한 내용은 upgrade2.0.regions.on.master 섹션을 참고하세요.
  • hbase.master.distributed.log.replay 자세한 내용은 upgrade2.0.distributed.log.replay 섹션 참고
  • hbase.regionserver.disallow.writes.when.recovering 자세한 내용은 upgrade2.0.distributed.log.replay 섹션 참고
  • hbase.regionserver.wal.logreplay.batch.size 자세한 내용은 upgrade2.0.distributed.log.replay 섹션 참고
  • hbase.master.catalog.timeout
  • hbase.regionserver.catalog.timeout
  • hbase.metrics.exposeOperationTimes
  • hbase.metrics.showTableName
  • hbase.online.schema.update.enable (HBase는 이제 항상 지원)
  • hbase.thrift.htablepool.size.max
HBase 2.0+에서 이름이 바뀐 구성 프로퍼티

다음 프로퍼티는 이름이 바뀌었어요. 옛 프로퍼티를 설정하려는 시도는 런타임에 무시돼요.

Old name New name
hbase.rpc.server.nativetransport hbase.netty.nativetransport
hbase.netty.rpc.server.worker.count hbase.netty.worker.count
hbase.hfile.compactions.discharger.interval hbase.hfile.compaction.discharger.interval
hbase.hregion.percolumnfamilyflush.size.lower.bound hbase.hregion.percolumnfamilyflush.size.lower.bound.min
HBase 2.0+에서 기본값이 다른 구성 설정

다음 구성 설정은 기본값이 바뀌었어요. 해당되는 경우 HBase 1.2의 동작을 복원할 값이 주어져요.

  • hbase.security.authorization 이제 기본값 false. 이전 기본값과 같은 동작을 복원하려면 true로 설정.
  • hbase.client.retries.number 이제 10으로 설정. 이전에는 35였어요. 다운스트림 사용자는 Configuration에 설명된 대로 클라이언트 타임아웃을 사용하는 것이 좋아요.
  • hbase.client.serverside.retries.multiplier 이제 3으로 설정. 이전에는 10이었어요. 다운스트림 사용자는 Configuration에 설명된 대로 클라이언트 타임아웃을 사용하는 것이 좋아요.
  • hbase.master.fileSplitTimeout 이제 10분으로 설정. 이전에는 30초였어요.
  • hbase.regionserver.logroll.multiplier 이제 0.5로 설정. 이전에는 0.95였어요. 이 변경은 아래의 블록 크기 두 배와 연결돼요. 이 두 구성 변경을 합치면 hbase-1.x의 WAL과 거의 같은 크기의 WAL이 만들어져야 하지만, blocksize 임계값에 도달하기 전에 WAL을 롤하지 못하기 때문에 작은 블록이 생길 가능성은 줄어들어요. 논의는 HBASE-19148 참고.
  • hbase.regionserver.hlog.blocksize 기본값이 WAL 디렉터리의 HDFS 기본 블록 크기의 2배. 이전에는 WAL 디렉터리의 HDFS 기본 블록 크기와 같았어요.
  • hbase.client.start.log.errors.counter 5로 변경. 이전에는 9였어요.
  • hbase.ipc.server.callqueue.type 'fifo'로 변경. HBase 1.0 - 1.2에서 'deadline'이었어요. 이전 및 이후 1.x 버전에서는 이미 'fifo'가 기본이에요.
  • hbase.hregion.memstore.chunkpool.maxsize 기본 1.0. 이전에는 0.0이었어요. 실질적으로 이것은 이전에는 memstore가 onheap일 때 청크 풀을 사용하지 않았고 이제는 사용한다는 뜻이에요. MSLAB 청크 풀에 대한 자세한 내용은 Long GC pauses 섹션을 참고하세요.
  • hbase.master.cleaner.interval 이제 10분으로 설정. 이전에는 1분이었어요.
  • hbase.master.procedure.threads 이제 사용 가능한 CPU 수의 1/4이 기본이지만 16개 스레드보다 적지는 않아요. 이전에는 CPU 수와 같은 수의 스레드였어요.
  • hbase.hstore.blockingStoreFiles 이제 16. 이전에는 10이었어요.
  • hbase.http.max.threads 이제 16. 이전에는 10이었어요.
  • hbase.client.max.perserver.tasks 이제 2. 이전에는 5였어요.
  • hbase.normalizer.period 이제 5분. 이전에는 30분이었어요.
  • hbase.regionserver.region.split.policy 이제 SteppingSplitPolicy. 이전에는 IncreasingToUpperBoundRegionSplitPolicy.
  • replication.source.ratio 이제 0.5. 이전에는 0.1이었어요.
"Master hosting regions" 기능이 깨지고 지원되지 않음

HBase 1.y에 있던 "Master acts as region server" 기능과 관련 후속 작업은 HBase 2.y에서 동작하지 않으며, Master 초기화 시 교착 상태(deadlock) 때문에 프로덕션 환경에서 사용해서는 안 돼요. 다운스트림 사용자는 관련 구성 설정을 실험적이고 이 기능을 프로덕션에 부적절한 것으로 취급하는 것이 좋아요.

관련 변경 요약:

  • Master는 더 이상 기본적으로 region을 보유하지 않음
  • hbase.balancer.tablesOnMaster는 불리언이며 기본 false (HBase 1.x 테이블 목록을 보유하면 기본 false가 됨)
  • hbase.balancer.tablesOnMaster.systemTablesOnly는 사용자 테이블을 master에서 분리하는 불리언. 기본 false
  • 옛 서버 목록 구성을 복제하려는 사람들은 스탠드얼론 RegionServer 프로세스를 배포하고 Region Server Groups에 의존해야 해요.
"Distributed Log Replay" 기능이 깨지고 제거됨

Distributed Log Replay 기능은 깨져서 HBase 2.y+에서 제거됐어요. 결과적으로 관련된 모든 구성, 메트릭, RPC 필드, 로깅도 제거됐어요. 이 기능은 HBase 1.0 준비 과정에서 신뢰할 수 없다는 것이 밝혀졌고 기본적으로 사용되지 않았으며, 활성화하는 구성을 무시하기 시작한 HBase 1.2.0에서 사실상 제거됐다는 점에 유의하세요(HBASE-14465). 현재 이 기능을 사용 중이라면 깨끗한 종료를 수행하고 모든 DLR 작업이 완료되는지 확인한 다음 업그레이드 전에 기능을 비활성화하세요.

prefix-tree 인코딩 제거

prefix-tree 인코딩은 HBase 2.0.0에서 제거됐어요(HBASE-19179). hbase-1.2.7, hbase-1.4.0, hbase-1.3.2에서 (늦게!) deprecated 됐어요.

이 기능은 적극적으로 유지 관리되지 않았기 때문에 제거됐어요. 쓰기를 느리게 하는 대신 랜덤 읽기 대기 시간을 개선한 이 훌륭한 기능을 되살리는 데 관심이 있다면 dev at hbase dot apache dot org의 HBase 개발자 목록에 글을 써 보세요.

HBase 2.0+로 업그레이드하기 전에 prefix-tree 인코딩을 모든 테이블에서 제거해야 해요. 그렇게 하려면 먼저 인코딩을 PREFIX_TREE에서 HBase 2.0에서 지원되는 다른 것으로 바꿔야 해요. 그 후 이전에 PREFIX_TREE 인코딩을 사용하던 테이블에 대해 메이저 컴팩션을 실행해야 해요. 어떤 column family가 호환되지 않는 데이터 블록 인코딩을 사용하는지 확인하려면 Pre-Upgrade Validator를 사용할 수 있어요.

변경된 메트릭

다음 메트릭 이름이 변경됐어요.

  • 이전에 "AssignmentManger" [sic]라는 이름으로 게시되던 메트릭은 이제 "AssignmentManager"라는 이름으로 게시돼요.

다음 메트릭의 의미가 바뀌었어요.

  • region server별로 게시되던 'blockCacheEvictionCount' 메트릭은 더 이상 (컴팩션 등으로 인한) hfile 무효화로 인해 캐시에서 제거된 블록을 포함하지 않아요.
  • 'totalRequestCount' 메트릭은 요청당 한 번 증가해요. 이전에는 요청에 실린 Actions의 수만큼 증가했어요. 예를 들어 요청이 4개의 Gets와 2개의 Puts로 구성된 multi라면 'totalRequestCount'를 6씩 증가시켰을 거예요. 이제는 요청에 관계없이 1씩 증가해요. hbase-2.0.0에서 이 메트릭의 값이 더 낮게 보일 것으로 예상하세요.
  • 'readRequestCount'는 이제 비어 있지 않은 행을 반환하는 읽기를 계산해요. 옛 hbase에서는 Result인지 여부와 관계없이 'readRequestCount'를 증가시켰어요. 이 변경은 존재하지 않는 행에 대한 요청이 있다면 읽기 요청 그래프의 프로필을 평평하게 만들 거예요. 데이터베이스가 어떻게 로드되었는지에 따라 YCSB 읽기 중심 워크로드가 이렇게 할 수 있어요.

제거된 메트릭:

  • Distributed Log Replay 기능 관련 메트릭은 더 이상 없어요. 이전에는 region server 컨텍스트에서 'replay'라는 이름으로 찾을 수 있었어요. 자세한 내용은 "Distributed Log Replay" feature broken and removed 섹션 참고.

추가된 메트릭:

  • 'totalRowActionRequestCount'는 읽기와 쓰기를 합한 region 행 동작의 카운트예요.
변경된 로깅

HBase-2.0.0은 이제 로깅 프론트엔드로 slf4j를 사용해요. 이전에는 log4j (1.2)를 사용했어요. 대부분 전환은 매끄러워야 해요. slf4j는 log4j.properties 로깅 구성 파일을 잘 해석해서 로그 시스템 출력에서 차이를 느끼지 못할 거예요.

그래도 log4j.properties를 가다듬을 필요가 있을 수 있어요. 예를 들어 HBASE-20351을 참고하세요. 낡은 로그 구성 파일이 매 셸 명령 호출의 프리앰블로 netty 구성이 DEBUG 수준으로 덤프되는 것으로 나타났어요.

zoo.cfg에서 ZooKeeper 구성 더 이상 읽지 않음

HBase는 더 이상 ZooKeeper 관련 구성 설정에 'zoo.cfg' 파일을 선택적으로 읽지 않아요. 이전에 이 기능을 위해 'hbase.config.read.zookeeper.config' 구성에 의존했다면, 필요한 설정을 hbase-site.xml 파일로 마이그레이션하면서 각 프로퍼티 이름에 접두사 'hbase.zookeeper.property.'를 추가해야 해요.

권한 변경

다음 권한 관련 변경은 의미 또는 기본값을 바꿨어요.

  • 사용자에게 부여된 권한은 기존 권한을 덮어쓰는 것이 아니라 병합돼요. (자세한 내용은 HBASE-17472 릴리스 노트 참고)
  • Region Server Group 명령(1.4.0에서 추가)은 이제 admin 권한이 필요해요.
대부분의 Admin API는 pre-HBase 2.0 클라이언트에서 HBase 2.0+ 클러스터에 대해 동작하지 않음

pre-HBase 2.0 클라이언트에서 사용하면 동작하지 않는 것으로 알려진 많은 admin 명령이 있어요. 여기에는 pre-HBase 2.0의 라이브러리 jar를 가진 HBase 셸이 포함돼요. 필요한 클라이언트 버전으로도 업데이트할 때까지 admin API와 명령 사용의 중단을 계획해야 해요.

pre-HBase 2.0 클라이언트에서 실행할 때 HBase 2.0+ 클러스터에 대해 동작하지 않는 클라이언트 연산:

  • list_procedures
  • split
  • merge_region
  • list_quotas
  • enable_table_replication
  • disable_table_replication
  • Snapshot 관련 명령
1.0에서 deprecated 된 admin 명령 제거

1.0에서 deprecated 된 다음 명령이 제거됐어요. 해당되는 경우 대체 명령이 나열돼요.

  • 'hlog' 명령이 제거됐어요. 다운스트림 사용자는 대신 'wal' 명령에 의존해야 해요.
Region Server 메모리 소비 변경

HBase 1.4 이전 버전에서 업그레이드하는 사용자는 Region Server memory consumption changes. 섹션의 지침을 읽어야 해요.

또한 HBase 2.0은 플러시 결정을 위한 memstore 메모리 추적 방식을 변경했어요. 이전에는 데이터 크기와 저장 오버헤드가 모두 플러시 임계값에 대한 활용도를 계산하는 데 사용됐어요. 이제는 데이터 크기만 이 region별 결정에 사용돼요. 전체적으로는 저장 오버헤드 추가가 강제 플러시 결정에 사용돼요.

분할과 병합을 위한 Web UI가 행 접두사에서 동작함

이전에는 Web UI에 테이블 상태 페이지에서 인코딩된 region 이름 기반으로 병합하거나 분할하는 기능이 포함되어 있었어요. HBase 2.0에서는 이 기능이 대신 행 접두사를 취하는 방식으로 동작해요.

pre-HBase 1.4의 복제 사용자를 위한 특별 업그레이드

1.4.0 릴리스 이전의 HBase 버전을 복제와 함께 사용하는 사용자는 Replication peer's TableCFs config 섹션의 지침을 반드시 읽어야 해요.

HBase 셸 변경

HBase 셸 명령은 번들된 JRuby 인스턴스에 의존해요. 이 번들된 JRuby가 버전 1.6.8에서 버전 9.1.10.0으로 업데이트됐어요. 이것은 Ruby 1.8에서 Ruby 2.3.3으로의 변경을 나타내며, 사용자 스크립트에 비호환 언어 변경을 도입해요.

HBase 셸 명령은 이제 초기 HBase 1.4 릴리스에 있던 '--return-values' 플래그를 무시해요. 대신 셸은 항상 그 플래그가 전달된 것처럼 동작해요. 콘솔에 식 결과가 인쇄되는 것을 피하고 싶다면 IRB 구성을 변경해야 해요.

HBase 2.0+에서 Coprocessor API가 변경됨

모든 Coprocessor API가 향후 HBase 버전에 대한 바이너리 API 호환성 지원성을 개선하도록 리팩터링됐어요. 자신 또는 의존하는 애플리케이션이 사용자 지정 HBase coprocessors를 가지고 있다면, HBase 2.0+로 업그레이드하기 전에 해야 할 변경 사항에 대한 자세한 내용은 HBASE-18169 릴리스 노트를 읽어야 해요.

예를 들어 HBase 1.2에서 BaseRegionObserver를 가지고 있었다면 최소한 RegionObserver와 RegionCoprocessor를 모두 구현하고 메서드를 추가하도록 업데이트해야 해요.

...
  @Override
  public Optional<RegionObserver> getRegionObserver() {
    return Optional.of(this);
  }
...

자세한 내용은 Upgrading Coprocessors to 2.0를 참고하세요.

HBase 2.0+는 더 이상 HFile v2 파일을 쓸 수 없음

HBase는 내부 HFile 처리를 단순화했어요. 결과적으로 기본 버전 3보다 이전의 HFile 버전을 더 이상 쓸 수 없어요. 업그레이드하는 사용자는 업그레이드 전에 hbase-site.xml의 hfile.format.version이 2로 설정되지 않았는지 확인해야 해요. 그렇게 하지 않으면 Region Server 장애가 발생할 거예요. HBase는 여전히 옛 버전 2 형식으로 작성된 HFiles를 읽을 수 있어요.

HBase 2.0+는 더 이상 Sequence File 기반 WAL 파일을 읽을 수 없음

HBase는 더 이상 Apache Hadoop Sequence File 형식으로 작성된 deprecated WAL 파일을 읽을 수 없어요. hbase.regionserver.hlog.reader.impl와 hbase.regionserver.hlog.writer.impl 구성 항목은 Protobuf 기반 WAL reader/writer 클래스를 사용하도록 설정해야 해요. 이 구현은 HBase 0.96부터 기본이었으므로 레거시 WAL 파일은 대부분의 다운스트림 사용자에게 문제가 되지 않아야 해요.

2.6.0부터 유효한 값이 protobuf 기반 reader/writer뿐이므로 hbase.regionserver.hlog.reader.impl와 hbase.regionserver.hlog.writer.impl 구성 항목은 제거됐어요. hbase-site.xml에 설정해도 실제 효과가 없어요.

깨끗한 클러스터 종료는 WAL 파일이 없도록 해야 해요. 특정 WAL 파일의 형식이 확실하지 않다면 HBase 클러스터가 오프라인일 때 hbase wal 명령으로 파일을 파싱할 수 있어요. HBase 2.0+에서는 이 명령이 Sequence File 기반 WAL을 읽을 수 없어요.

필터 동작 변경

Filter ReturnCode NEXT_ROW가 모든 family의 다음 행이 아니라 현재 family의 다음 행으로 건너뛰는 것으로 재정의됐어요. ReturnCode가 region 수준이 아니라 store 수준의 개념이므로 더 합리적이에요.

다운스트림 HBase 2.0+ 사용자는 shaded client를 사용해야 함

다운스트림 사용자는 런타임 사용에 Maven 좌표 org.apache.hbase:hbase-shaded-client에 의존하는 것을 강력히 권장해요. 이 아티팩트는 HBase 클러스터와 대화하는 데 필요한 모든 구현 세부사항을 포함하면서 노출되는 타사 의존성 수를 최소화해요.

이 아티팩트는 공용 API와의 소스 호환성을 유지하기 위해 org.apache.hadoop 패키지 공간의 일부 클래스(예: o.a.h.configuration.Configuration)를 노출한다는 점에 유의하세요. 이 클래스들은 나머지 HBase 클라이언트 코드와 동일한 이동(relocated) 타사 의존성을 사용하도록 변경될 수 있게 포함된 것이에요. 코드에서 Hadoop을 또한 사용해야 한다면 모든 Hadoop 관련 jar가 클래스패스에서 HBase 클라이언트 jar 앞에 오도록 해야 해요.

MapReduce의 다운스트림 HBase 2.0+ 사용자는 새 아티팩트로 전환해야 함

Apache Hadoop MapReduce용 HBase 통합의 다운스트림 사용자는 런타임 사용에 org.apache.hbase:hbase-shaded-mapreduce 모듈에 의존하도록 전환해야 해요. 역사적으로 다운스트림 사용자는 이 클래스들에 org.apache.hbase:hbase-server 또는 org.apache.hbase:hbase-shaded-server 아티팩트에 의존했어요. 두 사용 방식 모두 더 이상 지원되지 않으며 대부분의 경우 런타임에 실패할 거예요.

이 아티팩트는 공용 API와의 소스 호환성을 유지하기 위해 org.apache.hadoop 패키지 공간의 일부 클래스(예: o.a.h.configuration.Configuration)를 노출한다는 점에 유의하세요. 이 클래스들은 나머지 HBase 클라이언트 코드와 동일한 이동(relocated) 타사 의존성을 사용하도록 변경될 수 있게 포함된 것이에요. 코드에서 Hadoop을 또한 사용해야 한다면 모든 Hadoop 관련 jar가 클래스패스에서 HBase 클라이언트 jar 앞에 오도록 해야 해요.

런타임 클래스패스의 중대한 변경

HBase의 여러 내부 의존성이 런타임 클래스패스에서 업데이트되거나 제거됐어요. Downstream HBase 2.0+ users should use the shaded client의 지침을 따르지 않는 다운스트림 클라이언트 사용자는 Maven이 끌어오는 의존성 집합을 영향에 대해 검사해야 해요. LimitedPrivate Coprocessor API의 다운스트림 사용자는 영향에 대해 런타임 환경을 검사해야 해요.

클라이언트 API의 소스 및 바이너리 호환성에 대한 여러 파괴적 변경

HBase의 Java 클라이언트 API에는 소스와 바이너리 호환성을 모두 깨는 여러 변경이 있어요. 자세한 내용은 업그레이드할 릴리스의 Compatibility Check Report를 참고하세요.

추적 구현 변경

HBase의 추적 기능의 뒷받침 구현이 Apache HTrace 3에서 HTrace 4로 업데이트됐어요. 여기에는 여러 파괴적 변경이 포함돼요. HTrace 3과 4는 같은 런타임에 공존할 수 있지만 서로 통합되지 않아 별개의 추적 정보를 만들게 돼요.

이 업그레이드 동안 HBase의 내부 변경은 컴파일에 충분했지만 추적 기능에 회귀가 없다는 것은 확인되지 않았어요. 당분간 이 기능을 실험적인 것으로 간주하세요.

이전에 HBase 연산과 통합된 클라이언트 측 추적에 의존했다면 사용 방식을 HTrace 4로 업그레이드하는 것이 좋아요.

Apache HTrace 프로젝트가 Attic/은퇴로 이동한 후, HBase의 추적은 HBase 2.0 이후로 깨지고 유지 관리되지 않은 채 남아 있어요. HBASE-22120 새 프로젝트가 HTrace를 OpenTelemetry로 대체할 거예요. 3.0.0 릴리스에 배송될 거예요. 자세한 내용은 Tracing 문서를 참고하세요.

HFile 전방 호환성 상실

2.0.0, 2.0.1, 2.1.0이 생성한 HFiles는 1.4.6-, 1.3.2.1-, 1.2.6.1- 및 기타 비활성 릴리스에 전방 호환되지 않아요. HFile 호환성을 잃는 이유는 새 버전(2.0.0, 2.0.1, 2.1.0)이 TimeRangeTracker(TRT)를 직렬화/역직렬화하는 데 protobuf를 사용하는 반면 옛 버전은 DataInput/DataOutput을 사용하기 때문이에요. 이를 해결하려면 HBASE-21012를 2.x에, HBASE-21013을 1.x에 넣어야 해요. 자세한 내용은 HBASE-21008을 확인하세요.

성능

읽기와 쓰기 경로에 중대한 변경이 있었으므로 hbase-2.0.0으로 업그레이드하면 성능 프로필에 변화가 있을 가능성이 높아요. 릴리스 시점에는 쓰기가 더 느리고 읽기는 문맥에 따라 비슷하거나 훨씬 나을 수 있어요. 재튜닝에 시간을 투자할 준비를 하세요(Performance 참고). 성능은 현재 적극 검토 중인 영역이기도 하므로 향후 릴리스에서 개선을 기대할 수 있어요(HBASE-20188 TESTING Performance 참고).

통합 테스트와 Kerberos

통합 테스트(IntegrationTests*)는 보안 클러스터에 대한 인증을 위해 Kerberos 자격 증명 캐시에 의존했어요. 이로 인해 자격 증명 캐시의 티켓이 만료되면 인증 실패로 테스트가 실패하곤 했어요. hbase-2.0.0(및 hbase-1.3.0+)부터 통합 테스트 클라이언트는 구성 프로퍼티 hbase.client.keytab.file과 hbase.client.kerberos.principal을 사용할 거예요. 이것들은 필수예요. 클라이언트는 구성된 keytab 파일에서 로그인을 수행하고 프로세스 수명 동안 백그라운드에서 자격 증명을 자동으로 새로 고칠 거예요(HBASE-16231 참고).

기본 컴팩션 처리량

HBase 2.x는 컴팩션이 실행될 수 있는 속도에 대한 기본 제한과 함께 제공돼요. 이 제한은 RegionServer별로 정의돼요. 1.5보다 이전의 HBase 버전에서는 기본적으로 컴팩션이 실행될 수 있는 속도에 제한이 없었어요. 컴팩션 처리량에 제한을 적용하면 RegionServer에서 더 안정적인 운영을 보장해야 해요.

이 제한은 컴팩션별이 아니라 RegionServer별이라는 점에 주의하세요.

처리량 제한은 초당 쓰여진 바이트 범위로 정의되며, 주어진 하한과 상한 내에서 달라질 수 있어요. RegionServer는 컴팩션의 현재 처리량을 관찰하고 외부 압력에 대해 하한과 상한 내에서 허용 처리량을 조정하는 선형 공식을 적용해요. 컴팩션의 경우 외부 압력은 허용된 최대 store 파일 수에 대한 store 파일 수로 정의돼요. store 파일이 많을수록 컴팩션 압력이 높아져요.

이 처리량 구성은 다음 프로퍼티에 의해 관리돼요.

  • 하한은 hbase.hstore.compaction.throughput.lower.bound로 정의되고 기본 50 MB/s(52428800)예요.
  • 상한은 hbase.hstore.compaction.throughput.higher.bound로 정의되고 기본 100 MB/s(104857600)예요.

이 동작을 이전 HBase 버전의 무제한 컴팩션 처리량으로 되돌리려면 다음 프로퍼티를 컴팩션에 제한을 적용하지 않는 구현으로 설정하세요.

hbase.regionserver.throughput.controller=org.apache.hadoop.hbase.regionserver.throttle.NoLimitThroughputController

Coprocessors를 2.0으로 업그레이드하기

Coprocessor는 2.0에서 상당히 변경됐어요. 최상위 설계 변경에서 변경/제거된 메서드, 인터페이스 등까지 다양해요(부모 jira: HBASE-18169 Coprocessor fix and cleanup before 2.0.0 release). 이렇게 광범위하게 변경된 이유 중 일부:

  1. 구현 대신 인터페이스 전달하기. 예: HTableDescriptor 대신 TableDescriptor, HRegion 대신 Region(HBASE-18241 client.Table과 client.Admin이 HTableDescriptor를 사용하지 않도록 변경).
  2. 구현자가 더 적은 boilerplate를 채우고 더 많은 컴파일 타임 검사를 할 수 있도록 설계 리팩터링(HBASE-17732)
  3. Coprocessor API에서 Protocol Buffers 제거(HBASE-18859, HBASE-16769 등)
  4. Coprocessor에 노출하는 것을 줄여 노출하기엔 너무 사적인 내부에 대한 훅 제거(예: HBASE-18453 CompactionRequest를 사용자에게 직접 노출해서는 안 됨; HBASE-18298 CP 노출을 위한 RegionServerServices Interface 정리 등)

2.0에서 coprocessor를 사용하려면 새 API에 맞춰 다시 빌드해야 해요. 그렇지 않으면 로드에 실패하고 HBase 프로세스가 죽을 거예요.

coprocessor를 업그레이드하기 위한 제안된 변경 순서:

  1. Base*Observer 클래스를 확장하는 대신 observer 인터페이스를 직접 구현하세요. Foo extends BaseXXXObserver를 Foo implements XXXObserver로 변경하세요(HBASE-17312).
  2. 이 예시를 따라 상속에서 컴포지션으로의 설계 변경에 적응하세요(HBASE-17732).
  3. getTable()이 CoprocessorEnvrionment에서 제거됐어요. coprocessor는 Table 인스턴스를 자체 관리해야 해요.

새 API로 coprocessor를 작성하는 몇 가지 예시는 hbase-example 모듈 여기에서 찾을 수 있어요.

마지막으로, 변경/제거된 API가 회복할 수 없을 정도로 깨뜨린다면, 그리고 그것을 다시 추가할 타당한 근거가 있다면 [email protected]로 알려 주세요.

1.x에서 2.x로의 롤링 업그레이드

롤링 업그레이드는 현재 실험적 기능이에요. 제한적인 테스트를 거쳤어요. 제한된 경험에서 아직 발견되지 않은 모서리 케이스가 있을 가능성이 있으므로 이 경로를 택한다면 조심해야 해요. 다음 섹션에 설명된 1.x에서 2.x로의 업그레이드 과정인 stop/upgrade/start 방식이 가장 안전한 경로예요.

그래도 아래는 1.4 클러스터의 롤링 업그레이드를 위한 처방이에요.

사전 요구 사항

  • 최신 1.4.x 릴리스로 업그레이드하세요. 1.4 이전 릴리스도 동작할 수 있지만 테스트되지 않았으므로, region assignment와 crash 처리에 능숙한 전문가가 아니라면 2.x로 업그레이드하기 전에 1.4.3+로 업그레이드하세요. 1.4.x로 업그레이드하는 방법은 Upgrading from pre-1.4 to 1.4+ 섹션을 참고하세요.
  • zk-less assignment가 활성화되어 있는지 확인하세요. 즉 hbase.assignment.usezk를 false로 설정하세요. 이것이 가장 중요한 부분이에요. 1.x master가 2.x region server에/로부터 region을 할당/할당 해제할 수 있게 해 줘요. zk 기반 assignment에서 zk-less assignment로 마이그레이션하는 방법은 HBASE-11059의 릴리스 노트 섹션을 참고하세요.
  • 업그레이드 전에 hbck1이 INCONSISTENCIES가 없다고 보고하는지 확인하세요. 업그레이드 후 hbase1 유형의 불일치를 고치는 것은 복잡한 과정이에요.
  • 1.4.3에서 2.1.0으로의 롤링 업그레이드를 테스트했지만, 2.0.x로 업그레이드하려 해도 동작해야 해요.

지침

  1. region server를 내리고 2.1.0으로 업그레이드하세요. HBASE-17931이 있으면 meta region과 다른 시스템 테이블의 region이 즉시 이 region server로 이동돼요. 그렇지 않으면 수동으로 새 region server로 이동하세요. 이것은 매우 중요해요. 왜냐하면
    • meta region의 스키마는 하드코딩되어 있어서 meta가 옛 region server에 있으면 새 region server가 (예: table state) 일부 family가 없어 접근할 수 없어요.
    • 더 낮은 버전의 클라이언트는 더 높은 버전의 서버와 통신할 수 있지만 반대는 안 돼요. meta region이 옛 region server에 있으면 새 region server가 더 높은 버전의 클라이언트로 더 낮은 버전의 서버와 통신하게 되어 이상한 문제를 일으킬 수 있어요.
  2. 다른 모든 region server를 롤링 업그레이드하세요.
  3. masters를 업그레이드하세요.

롤링 업그레이드 중 region server 크래시가 있는 것은 괜찮아요. 1.x master가 1.x와 2.x region server에 모두 region을 할당할 수 있고, HBASE-19166이 1.x region server도 2.x region server가 쓴 WAL을 읽고 분할할 수 있도록 문제를 고쳤어요.

롤링 업그레이드 전에 Changes of Note! 섹션을 주의 깊게 읽으세요. prefix-tree 인코딩, 옛 hfile 형식 등 2.0에서 제거된 기능을 사용하지 않도록 해야 해요. 둘 다 업그레이드를 실패시킬 수 있고 클러스터를 중간 상태로 남겨 복구하기 어렵게 만들 수 있어요.

이 처방으로 성공했다면 dev 목록에 경험을 알리거나/및 취한 편차로 위를 업데이트해서 이 경로를 가는 다른 사람들이 노력의 혜택을 받을 수 있게 해 주세요.

1.x에서 2.x로의 업그레이드 과정

기존 HBase 1.x 클러스터를 업그레이드하려면:

  • hbck1이 INCONSISTENCIES가 없다고 보고하는지 확인하세요. 업그레이드 후 hbase1 유형의 불일치를 고치는 것은 복잡한 과정이에요. 진행 전에 모든 hbck1 불만을 고치세요.
  • 기존 1.x 클러스터의 깨끗한 종료
  • coprocessors 업데이트
  • Master 역할을 먼저 업그레이드
  • RegionServers 업그레이드
  • (결국) Clients 업그레이드

1.7.1+로 업그레이드

HBase 릴리스 1.7.0은 마이너 릴리스 호환성 보장을 깨뜨리는 호환되지 않는 테이블 메타데이터 직렬화 형식을 도입했어요. 문제는 HBASE-26021에 보고됐고 문제의 직렬화 패치는 HBase 1.7.1에서 되돌려졌어요. 1.7.x 업그레이드에 대한 몇 가지 중요한 참고 사항이 아래에 있어요.

  • 1.7.x 버전으로의 업그레이드를 고려 중이라면 1.7.0을 완전히 건너뛰고 1.7.1+ 버전으로 업그레이드하세요. 1.7.0은 철회되었고 Apache 사이트에서 제거됐어요.
  • 이미 처음부터 1.7.0 클러스터를 설치했고 1.7.1+로 마이그레이션하려 한다면, 깨진 호환성 계약 때문에 일반 롤링 업그레이드 절차를 따를 수 없어요. 대신 클러스터를 종료하고 1.7.1+ 바이너리로 재부팅하세요. 더 새로운 버전은 호환되지 않는 직렬화를 가진 기존 테이블을 감지하고 부트스트랩 시 올바른 형식으로 다시 써요.
  • 이미 1.7.1+ 버전에 있다면 모든 것이 좋고 추가 단계를 수행할 필요가 없어요.

pre-1.4에서 1.4+로 업그레이드

Region Server 메모리 소비 변경

HBase 1.4 이전 버전에서 업그레이드하는 사용자는 memstore 객체(KeyValue, 객체 및 배열 헤더 크기 등)에 의한 힙 사용량 추정이 32G까지의 힙 크기(CompressedOops 사용)에 대해 더 정확해졌고, 결과적으로 실제로 10-50% 감소한다는 점을 알아야 해요. 이것은 또한 더 "뚱뚱한" 플러시로 인해 플러시와 컴팩션 횟수가 줄어들게 해요. YMMV. 결과적으로 플러시 전 memstore의 실제 힙 사용량이 최대 100% 증가할 수 있어요. region server에 대한 구성된 메모리 제한이 관찰된 사용량에 기반해 튜닝되었다면, 이 변경은 더 나쁜 GC 동작이나 심지어 OutOfMemory 오류를 초래할 수 있어요. 비활성화하려면 환경 프로퍼티(hbase-site.xml 아님) "hbase.memorylayout.use.unsafe"를 false로 설정하세요.

복제 피어의 TableCFs 구성

1.4 이전에는 테이블 이름이 복제 피어의 TableCFs 구성에 namespace를 포함할 수 없었어요. ZooKeeper에 저장된 ReplicationPeerConfig에 TableCFs를 추가해 고쳤어요. 그래서 1.4로 업그레이드할 때 먼저 ZooKeeper의 원래 ReplicationPeerConfig 데이터를 업데이트해야 해요. 클러스터에 TableCFs 구성이 있는 복제 피어가 있으면 업그레이드하는 네 단계가 있어요.

  • 복제 피어를 비활성화해요.

  • master에 복제 피어 znode를 쓸 권한이 있으면 master를 직접 롤링 업데이트해요. 그렇지 않으면 TableCFsUpdater 도구를 사용해 복제 피어의 구성을 업데이트해요.

    $ bin/hbase org.apache.hadoop.hbase.replication.master.TableCFsUpdater update

  • regionservers를 롤링 업데이트해요.

  • 복제 피어를 활성화해요.

참고:

  • 옛 클라이언트(1.4 이전)를 사용해 복제 피어의 구성을 변경할 수 없어요. 클라이언트가 ZooKeeper에 직접 구성으로 쓰기 때문에 옛 클라이언트는 TableCFs 구성을 놓칠 거예요. 그리고 옛 클라이언트는 옛 tablecfs znode에 TableCFs 구성을 쓰므로 새 버전 regionserver에서 동작하지 않을 거예요.

Raw scan이 이제 TTL을 무시함

raw scan을 수행하면 이제 TTL 설정에 따라 만료된 결과도 반환할 거예요.

pre-1.3에서 1.3+로 업그레이드

Kerberos로 통합 테스트를 실행한다면 upgrade2.0.it.kerberos을 참고하세요.

1.x로 업그레이드

업그레이드 과정에 대한 자세한 내용은 업그레이드하려는 HBase 버전을 위해 특별히 게시된 문서를 참고하세요.

더 알아보기 (Learn more)