LLM WikiAccess-protected knowledge portal

WIKI

Apache Polaris 1.7.0: 멱등 쓰기·자격증명 벤딩 강화·고아 파일 정리로 Lakehouse 카탈로그 신뢰성을 높이는 방법

요약 Apache Polaris 1.7.0이 2026년 8월 2일 릴리스됐다. 이번 릴리스는 기능 추가보다 카탈로그 운영 신뢰성 을 높이는 방향에 집중한다. 멱등 쓰기 idempotent writes 옵트인, 자격증명 벤딩 정책 강화, 로케이션 인코딩 수정, 고아 파일 정리 수정, 그리고 시맨틱 모델 API 베타 도입이 핵심이다. 릴리스 배경에는 분산 멀티 엔진 환경에서 동일한 테이블을 동시에 수정하는 경쟁 쓰기 문제가 있다.

경로human/study/content/database-frontier/108-apache-polaris-1-7-0-idempotent-writes-credential-vending-semantic-model.md
카테고리Study
태그#credential #infra #model #mysql #semantic #study #vending #writes

요약

Apache Polaris 1.7.0이 2026년 8월 2일 릴리스됐다. 이번 릴리스는 기능 추가보다 카탈로그 운영 신뢰성을 높이는 방향에 집중한다. 멱등 쓰기(idempotent writes) 옵트인, 자격증명 벤딩 정책 강화, 로케이션 인코딩 수정, 고아 파일 정리 수정, 그리고 시맨틱 모델 API 베타 도입이 핵심이다.

릴리스 배경에는 분산 멀티 엔진 환경에서 동일한 테이블을 동시에 수정하는 경쟁 쓰기 문제가 있다. Spark, Flink, Trino가 같은 Iceberg REST 카탈로그를 바라볼 때, 클라이언트 재시도로 인한 중복 커밋이 데이터 불일치를 일으킬 수 있다. 멱등 쓰기는 이 문제를 카탈로그 레이어에서 직접 해결한다. 파괴적 변경(breaking change)으로 JDBC 스키마 v5 전환과 bootstrap 명령어 변경이 포함되어 있어 업그레이드 전 준비가 필요하다.

릴리스 맥락

Apache Polaris는 Iceberg REST 카탈로그 사양의 오픈 소스 레퍼런스 구현이다. 카탈로그는 테이블 메타데이터 포인터를 관리하며, Spark·Trino·Flink·Dremio 같은 여러 엔진이 동일한 Iceberg 테이블을 읽고 쓸 수 있게 중재한다.

1.7.0 이전의 주요 한계는 다음과 같다:

멱등 쓰기 (Idempotent Writes)

동작 방식

멱등 쓰기는 옵트인 방식으로 활성화한다:

polaris.idempotency.enabled=true  # 기본값: false
polaris.idempotency.ttl=PT5M      # 기본값: 5분

활성화하면 클라이언트는 Idempotency-Key HTTP 헤더를 포함해 createTable 또는 updateTable 요청을 보낸다. 폴라리스는 이 키를 테이블 엔티티에 임베드해 동일한 트랜잭션으로 커밋한다. 재시도 요청이 TTL 윈도우 내에 동일한 키를 가져오면 원본 성공 응답을 재전송한다.

카탈로그는 GET /v1/config 응답의 idempotency-key-lifetime 필드를 통해 지원 여부와 TTL을 클라이언트에게 알린다.

구현 방식 변경

초기 설계는 별도의 idempotency_records 테이블을 두고 IdempotencyStore 인터페이스로 관리하는 방식이었다. 1.7.0에서 PR #5086이 이를 제거하고, 멱등성 상태를 테이블 엔티티 자체에 부착하는 엔티티 속성 방식으로 전환했다. 별도 테이블을 관리하는 오버헤드를 없애고 커밋 원자성을 단순화한다.

자격증명 벤딩 강화

AWS: SigV4 세션 정책 첨부

자격증명 벤딩에서 IAM 세션 정책 JSON을 STS AssumeRole 요청에 직접 첨부할 수 있게 됐다. SigV4AuthenticationParameters에 선택적 sessionPolicy 필드가 추가됐다.

실용적 의미: 엔진마다 다른 최소 권한 정책을 적용할 수 있다. 예를 들어 읽기 전용 쿼리 엔진에게는 s3:GetObject만 허용된 세션 정책을 붙이고, 쓰기 엔진에게는 더 넓은 권한을 부여한다.

GCS: 워크로드 아이덴티티 기반 귀속

GCS 환경에서 벤딩된 자격증명에 원칙 귀속(principal attribution)이 추가됐다. 이는 AWS STS 세션 태그의 GCP 대응 기능이다.

활성화하려면 다음 플래그가 필요하다:

환경 변수역할
GCS_PRINCIPAL_ATTRIBUTION_ENABLED=true기능 활성화
GCS_PRINCIPAL_ATTRIBUTION_WIF_AUDIENCEWorkload Identity Federation 대상
GCS_PRINCIPAL_ATTRIBUTION_TOKEN_ISSUER토큰 발급자 URL
GCS_PRINCIPAL_ATTRIBUTION_SIGNING_KEY_FILE서명 키 파일 경로

로케이션 인코딩 수정

기본 테이블 스토리지 로케이션이 이제 JVM 기본 문자셋 대신 UTF-8로 퍼센트 인코딩된다.

이전 버전에서는 비ASCII 네임스페이스나 테이블 이름을 사용하면 JVM 기본 문자셋에 따라 로케이션이 달라질 수 있었다. 예를 들어 UTF-8 JVM과 latin-1 JVM에서 동일 테이블이 서로 다른 오브젝트 경로를 가리켰다. 1.7.0은 이 결정을 UTF-8로 고정한다.

주의: 비ASCII 이름을 사용하는 기존 테이블은 인코딩 전환 후 경로가 변경될 수 있다. 업그레이드 전 영향 범위를 확인해야 한다.

고아 파일 정리 개선

Iceberg v2 삭제 매니페스트 처리

ManifestFileCleanupTaskHandler가 Iceberg v2 삭제 매니페스트를 처리하게 됐다. 이전에는 merge-on-read DML을 실행한 v2 테이블에 DROP TABLE PURGE를 실행하면 position-delete 파일과 그 매니페스트가 오브젝트 스토리지에 남았다.

비동기 태스크 재시도

비동기 태스크 실행에서 핸들러가 일시적 오류(IO 오류, 삭제 실패 등)로 false를 반환할 때 재시도하게 됐다. 이전에는 false 반환이 경고 로그만 남기고 태스크가 영구적으로 종료됐다.

시맨틱 모델 API (베타)

1.7.0에는 시맨틱 모델 API의 베타 버전이 포함됐다. 이 API는 Iceberg 테이블 위에 비즈니스 의미 레이어(semantic layer)를 기술하는 스펙을 목표로 한다—계산 열, 측정값, 차원 정의 같은 것들이다.

현 단계에서 알아야 할 것:

아키텍처 다이어그램

멀티 엔진 클라이언트
Spark
Trino
Flink
Dremio
↓ Iceberg REST 요청 (Idempotency-Key 헤더 옵션)
Apache Polaris 1.7.0 — Iceberg REST 카탈로그
멱등 쓰기 (옵트인)
createTable / updateTable
엔티티 속성 방식 · TTL 5분
자격증명 벤딩
AWS SigV4 세션 정책
GCS 워크로드 아이덴티티 귀속
비동기 정리 태스크
v2 삭제 매니페스트 처리
IO 오류 재시도
↓
JDBC 영속성 (스키마 v5)
events.catalog_id nullable
__realm__ → NULL
↓
시맨틱 모델 API
베타 — API 불안정
↓
오브젝트 스토리지
S3 / GCS / ADLS
Apache Polaris 1.7.0 — 주요 변경 위치와 흐름

파괴적 변경 (Breaking Changes)

JDBC 스키마 v5

관계형 JDBC 영속성을 사용하는 경우 events.catalog_id 컬럼이 nullable로 변경됐다. 카탈로그에 범위가 없는 이벤트(principal 이벤트, 정책 이벤트, 속도 제한 이벤트 등)는 이전에는 자리 표시자 문자열 __realm__을 저장했지만 이제는 NULL로 저장된다.

기존 __realm__ 값에 의존하는 쿼리나 파이프라인이 있으면 업그레이드 전에 수정해야 한다.

Bootstrap 명령어 변경

관리 도구의 bootstrap 명령어에서 --schema-version (-v) 옵션이 제거됐다. 새 영역(realm)은 항상 최신 스키마 버전으로 부트스트랩된다. 이 옵션을 사용하는 배포 스크립트나 CI 파이프라인이 있으면 해당 인수를 제거해야 한다.

MaintenanceService 시그니처 변경

MaintenanceService.performMaintenance()의 시그니처가 변경됐다. 이제 최신 미완료 유지보수 실행을 대체하기 위한 명시적 OptionalLong overrideRunId 인자가 필요하다. 직접 구현한 MaintenanceService 코드가 있으면 업데이트가 필요하다.

운영 업그레이드 체크리스트

항목조치
JDBC 스키마 v5 전환events.catalog_id = '__realm__' 조건의 쿼리·파이프라인 수정
bootstrap 스크립트--schema-version / -v 인수 제거
MaintenanceService 구현체overrideRunId: OptionalLong 인자 추가
비ASCII 네임스페이스·테이블오브젝트 경로 인코딩 변경 영향 범위 확인
멱등 쓰기 활성화 여부polaris.idempotency.enabled=true (필요 시) + TTL 튜닝
GCS 자격증명 귀속4개 환경 변수 설정 (선택적)
시맨틱 모델 API베타 확인—프로덕션 코드 작성 보류

정리

Polaris 1.7.0은 카탈로그가 단순한 메타데이터 포인터 저장소에서 트랜잭션 조정 시스템으로 진화하는 과정을 보여준다. 멱등 쓰기는 Iceberg REST 사양이 멀티 엔진 동시 쓰기를 조율하는 프로토콜로 발전하고 있음을 보여준다. 자격증명 벤딩 강화는 클라우드 보안 모범 사례(최소 권한, 감사 추적)를 카탈로그 레이어로 가져온다.

실용적 관점에서 즉시 중요한 것은 파괴적 변경이다. 스키마 v5, bootstrap 명령어 변경, MaintenanceService 시그니처 변경은 업그레이드 전에 반드시 점검해야 한다. 시맨틱 모델 API는 방향성을 이해하는 데는 유용하지만 현 시점에서 프로덕션 의존은 이르다.

References