Apache Iceberg 1.11.0: 서버사이드 스캔 계획·DynamicIcebergSink·메타데이터 암호화로 REST 카탈로그가 프로덕션 수준이 된 방법

REST 카탈로그의 한계가 드러난 지점

Apache Iceberg는 테이블 포맷이지만 쿼리 엔진이 테이블을 실제로 읽으려면 스캔 계획(scan planning) 이 필요하다. 스캔 계획이란 쿼리 조건에 맞는 데이터 파일 목록을 골라내는 작업이다. 테이블 메타데이터(스냅샷, 매니페스트 파일, 파티션 통계)를 읽고, 프루닝을 수행하고, 읽어야 할 FileScanTask 목록을 만든다.

기존 구조에서는 이 작업이 쿼리 엔진(클라이언트) 쪽에서 처리되었다. Spark 드라이버, Trino 코디네이터, 혹은 Flink 잡 매니저가 S3 같은 오브젝트 스토리지에서 메타데이터 파일을 직접 내려받아 계획을 세웠다. 테이블이 크고 파티션이 많을수록 드라이버 메모리 소비가 늘고, 잡 시작 시간이 길어졌다.

REST 카탈로그 프로토콜은 원래 테이블 메타데이터를 HTTP API로 제공하는 역할이었다. 스캔 계획 자체는 여전히 클라이언트 책임이었다.

2026년 5월 19일에 릴리스된 Apache Iceberg 1.11.0은 이 구조를 바꾼다. REST 카탈로그가 스캔 계획을 서버 쪽에서 직접 수행하고, 클라이언트에게는 준비된 FileScanTask 목록만 돌려줄 수 있게 됐다. 이와 함께 DynamicIcebergSink(Flink)와 엔드투엔드 메타데이터 암호화가 함께 추가됐다. 세 가지 변화가 모두 REST 카탈로그의 프로덕션 성숙도와 연결된다.

서버사이드 스캔 계획

Apache Iceberg 1.11.0 — 클라이언트사이드 vs 서버사이드 스캔 계획 비교

세 가지 응답 모드

REST 카탈로그 서버가 처리하는 스캔 계획은 규모에 따라 응답 방식이 달라진다.

소규모 스캔: 즉시 FileScanTask 목록 반환.
대규모 스캔: plan-id를 먼저 반환하고 클라이언트가 폴링. /tasks 엔드포인트에서 작업 단위를 청크로 수신.
대용량 분산: 여러 워커가 /tasks 엔드포인트를 병렬로 호출해 동시에 수신.

각 FileScanTask는 데이터 파일 경로, 바이트 범위, 선택적 프로젝션/필터를 담는다. 클라이언트는 메타데이터 파일을 직접 내려받지 않아도 된다.

Partition Statistics Scan API

스캔 계획 외에 파티션 통계 스캔 API가 새롭게 추가됐다. 쿼리 옵티마이저가 테이블의 파티션 구조를 프로그래매틱하게 조회할 수 있는 공식 경로가 생긴 것이다.

이전에는 파티션 수준의 통계를 얻으려면 매니페스트 파일을 직접 파싱해야 했다. 이제는 표준화된 API로 파티션별 행 수, 파일 수, 데이터 크기 등의 집계 정보를 조회할 수 있다. Spark, Trino 등 쿼리 엔진이 카탈로그 경계를 넘지 않고도 플랜을 더 잘 최적화할 수 있는 기반이다.

DynamicIcebergSink (Flink)

Iceberg 1.11.0에 추가된 DynamicIcebergSink는 현재 실험적(experimental) 상태지만, 기존 Flink 싱크의 근본적인 제약을 해소한다.

기존 Iceberg Flink 싱크는 싱크 하나당 테이블 하나였다. 여러 테이블에 쓰려면 싱크를 여러 개 만들어야 했고, 대상 테이블이 런타임에 결정되거나 새 테이블이 동적으로 생성되어야 하는 멀티테넌트 시나리오에 적합하지 않았다.

DynamicIcebergSink는 이 제약을 없앤다.

기능	설명
런타임 라우팅	레코드의 필드 값을 기준으로 대상 테이블을 동적 결정
온디맨드 테이블 생성	대상 테이블이 없으면 자동 생성
동적 스키마 진화	입력 스키마가 바뀌면 대상 테이블 스키마를 자동 진화
동적 파티션 스펙	파티션 스펙도 입력에 맞게 적응

멀티테넌트 데이터 수집(각 테넌트가 별도 Iceberg 테이블), 이벤트 타입별 동적 테이블 분기, 스키마가 유동적인 소스 통합 등에 유용하다.

실험적 상태라는 점은 운영 도입 전 충분한 검증이 필요하다는 의미다. API 변경이 패치 버전에서도 생길 수 있다.

엔드투엔드 메타데이터 암호화

1.11.0에서 Iceberg 최초의 프로덕션 수준 메타데이터 암호화가 도입됐다.

암호화 범위

매니페스트 리스트(manifest list): 스냅샷이 참조하는 모든 매니페스트 파일 목록.
매니페스트 파일: 데이터 파일 경로와 통계를 담은 메타데이터.
메타데이터 무결성 검사: 암호화된 메타데이터의 변조 탐지.

데이터 파일 자체의 암호화는 별도 스토리지 레이어 또는 Parquet 네이티브 암호화로 처리된다.

암호화 방식

봉투 암호화(envelope encryption) 를 사용한다. 각 메타데이터 파일을 데이터 암호화 키(DEK) 로 암호화하고, DEK 자체는 키 암호화 키(KEK) 로 암호화해 메타데이터에 함께 저장한다. KEK는 외부 KMS가 관리한다.

지원 KMS:

AWS KMS
Google Cloud KMS
HashiCorp Vault

키 회전(key rotation) 기능이 내장되어 있다. KEK를 교체해도 기존 DEK를 복호화해 새 KEK로 재암호화하는 과정이 Iceberg 프로토콜 안에서 처리된다.

운영 설정

메타데이터 파일
(매니페스트 등)

↓

DEK로 암호화
AES-256-GCM

→

DEK 자체
(데이터 암호화 키)

↓

KEK로 암호화
외부 KMS 관리

→

암호화된 DEK를
메타데이터에 함께 저장

↓

외부 KMS
AWS KMS / Google KMS
HashiCorp Vault

봉투 암호화 흐름 — 메타데이터 파일 보호 구조

암호화 활성화는 카탈로그 레벨에서 설정한다. 기존 비암호화 테이블과의 혼재는 테이블 단위로 속성을 설정해 처리한다.

엔진 지원 변화

1.11.0부터 기본 빌드 타깃이 바뀐다.

엔진	추가 지원	기존 제거
Apache Spark	4.1 (기본), 3.5.8 추가	—
Apache Flink	2.1.0 (기본)	—
Java	17+ 필수	Java 11 드롭

Spark 4.1을 기본 타깃으로 올리면서 MERGE INTO 스키마 진화와 LIMIT pushdown 기능이 추가됐다. Flink 2.1 지원에서는 DynamicIcebergSink 외에도 삭제 벡터(deletion vector) 지원이 포함됐다.

Java 11 지원 종료는 런타임 업그레이드를 아직 하지 않은 팀에게 블로커가 될 수 있다. Iceberg 1.11.0 이상으로 올리기 전에 JVM 버전을 먼저 확인해야 한다.

Variant 타입 지원 확대

JSON과 반정형 데이터를 처리하는 Variant 타입 처리가 강화됐다.

Parquet 파일에서의 Variant 읽기/쓰기 개선
Arrow 포맷과의 Variant 변환
Variant 컬럼에 대한 필터링 연산 지원
타입 변환 시 안전한 sanitization

Variant 타입은 DuckDB, Databricks가 채택하며 빠르게 확산되고 있다. Iceberg 1.11이 이 타입을 더 안정적으로 지원하면서 JSON 기반 반정형 데이터를 Iceberg 테이블에서 다루는 시나리오가 실용적이 되었다.

운영 체크리스트

1.11.0으로 업그레이드 전 확인사항:

Java 버전: JDK 17 이상 필수. JDK 11 환경은 업그레이드 불가.
REST 카탈로그 서버 버전: 서버사이드 스캔 계획을 활용하려면 카탈로그 서버도 1.11 지원 버전이어야 한다. 클라이언트 라이브러리만 올리는 것으로는 기능 활성화가 안 된다.
Flink 버전: DynamicIcebergSink를 사용하려면 Flink 2.1 이상이 필요하다. 실험적 기능임을 팀에 공유하고 도입 범위를 제한하는 것이 안전하다.
암호화 설정: 메타데이터 암호화를 활성화하려면 외부 KMS 접근 권한 설정이 선행되어야 한다. 기존 비암호화 테이블에 소급 적용하는 마이그레이션 절차는 별도 계획 필요.
제거된 API 확인: 포지셔널 딜리트(positional delete with row data) 관련 deprecated API들이 제거됐다. 이를 사용 중인 코드가 있다면 1.11.0 적용 전 교체해야 한다.

서버사이드 스캔 계획 도입 효과 측정:

드라이버 메모리 사용량(잡 시작 시점 peak GC)
잡 시작 시간(첫 스테이지 시작까지 경과 시간)
카탈로그 서버 CPU/메모리(계획 작업이 이동된 만큼 증가)

Open question: 서버사이드 스캔 계획이 Trino와 Flink에서 안정적으로 지원되는 버전 조합은 아직 커뮤니티에서 확인 중이다. 카탈로그 서버로 Polaris, Unity Catalog, AWS Glue 등을 사용하는 경우 각 벤더의 1.11 지원 일정을 별도로 확인해야 한다.