lakeFS의 액션과 훅

lakeFS의 액션과 훅 (Actions and Hooks)

왜 훅인가: 데이터 품질 게이트와 데이터용 CI/CD

현대의 데이터 파이프라인은 데이터 레이크에서 BI 대시보드, 분석 시스템, 머신러닝 모델 같은 다운스트림 소비자로 데이터를 끊임없이 이동시켜요. 조직이 그 데이터로 중요한 비즈니스 결정을 내리는 만큼, 운영 데이터는 단순한 파일 포맷·스키마 검사부터 PII(개인 식별 정보) 탐지와 제거 같은 고급 제어까지, 정의된 품질 기준과 거버넌스 정책을 일관되게 충족해야 해요.

데이터 라이프사이클 전반에서 품질을 유지하려고 팀들은 데이터 품질 게이트(data quality gates)를 도입해요. 소프트웨어의 지속적 통합(CI)처럼, 운영 데이터에 대한 모든 업데이트는 공개되기 전에 자동 검증을 거쳐야 해요. 그래야 검증된 데이터만 앞으로 나아가고, 신뢰할 수 없거나 정책에 맞지 않는 데이터는 소비자에게 도달하기 전에 막히죠. lakeFS는 훅(hooks)으로 이 게이트를 제공해요. 브랜치에 pre-commit과 pre-merge 훅을 붙이면, 변경이 확정되거나 운영 환경으로 승격되기 전에 스키마 호환성 검증, 파일 포맷 정책 강제, PII 탐지·차단, 데이터 품질 검사, 네이밍/파티셔닝 규칙 강제를 수행할 수 있어요.

훅은 write-audit-publish 승격 워크플로에서 품질 게이트 역할을 해요.

훅의 동작은 액션 파일(actions file)에 선언적으로 정의해요. 트리거 이벤트, 규칙이 적용될 브랜치, 실행할 검증 로직을 지정하죠. 이벤트가 발생하면 lakeFS는 모든 검증을 실행하고, 하나라도 실패하면 main으로의 머지 같은 해당 작업이 차단돼요. 아래 예시는 main에 파일 포맷 계약을 강제해, 지정한 접두사 아래에는 Parquet과 Delta Lake 파일만 허용해요:

name: ParquetOnlyInProduction
description: This webhook ensures that only parquet files are written under production/
on:
  pre-merge:
    branches:
      - main
hooks:
  - id: production_format_validator
    type: webhook
    description: Validate file formats
    properties:
      url: "http://lakefs-hooks:5001/webhooks/format"
      query_params:
        allow: ["parquet", "delta_lake"]
        prefix: analytics/

직접 해볼 워크스루로는 lakeFS samples 저장소의 hooks-demo.ipynb 노트북이 바로 실행 가능한 환경을 제공하고, lakeFS hooks 저장소에는 그대로 가져다 고칠 수 있는 검증 웹훅이 준비되어 있어요.

출처: 문서

본문

Actions와 Hooks의 동작 방식

다른 버전 관리 시스템처럼 lakeFS도 미리 정의된 이벤트가 발생할 때 실행되도록 Actions를 설정할 수 있어요. Actions의 용도는 다양해요:

• Format Validator: 새 파일이 허용된 데이터 포맷 집합에 속하는지 검사하는 웹훅이에요.

• Schema Validator: 새 Parquet, ORC 파일을 읽어서 금지된 컬럼 이름(또는 이름 접두사) 블록리스트에 걸리지 않는지 확인하는 웹훅이에요. 실수로 PII가 노출되는 걸 막는 데 유용해요.

• 외부 시스템 연동: post-merge, post-commit 훅으로 변경에 대한 메타데이터를 다른 시스템으로 내보낼 수 있어요. 예컨대 카탈로그 메타데이터를 내보내 AWS Athena 같은 쿼리 엔진이 lakeFS에서 데이터를 읽게 하는 거죠.

• 다운스트림 소비자에게 알리기: post-merge 훅으로 Airflow DAG를 트리거하거나 API로 웹훅을 보내 변경을 알려요.

훅이 실제로 돌아가는 단계별 예시는 lakeFS Quickstart와 lakeFS samples 저장소를 참고하세요.

개요

action은 실행할 hook을 하나 이상 정의해요. lakeFS가 지원하는 훅은 세 가지예요:

• Lua — 내장 Lua VM을 사용해요

• Webhook — 외부 URL로 REST 호출을 보내요

• Airflow — Airflow에서 DAG를 트리거해요

"Before" 훅은 자기 액션이 실행되기 전에 반드시 성공해야 해요. 훅이 실패하면 액션이 중단돼요. Lua 훅과 Webhook은 동기(synchronous)라서 lakeFS가 완료될 때까지 기다려요. Airflow 훅은 비동기라서 Airflow가 DAG 트리거를 받아들이는 즉시 lakeFS는 기다림을 멈춰요.

설정

액션 설정은 두 부분으로 나뉘어요:

• 액션 파일을 만들어 lakeFS 저장소에 업로드해요

• 액션 파일에 지정한 훅(들)을 설정해요. 설정 방법은 훅 타입에 따라 달라져요.

액션 파일

Action은 같은 트리거 설정을 공유하는 훅의 목록이에요. 즉, 이벤트가 발생하면 액션 아래의 모든 훅이 실행되거나 하나도 실행되지 않아요.

액션 아래의 훅은 순서가 있고, 실행 순서도 그 순서를 따라가요.

각 훅이 실행되기 전에 if 불리언 표현식이 평가돼요. 표현식에서는 success()와 failure() 함수를 쓸 수 있는데, 각각 이 훅 앞의 액션이 성공했는지 실패했는지를 반환해요.

기본 동작은 if가 비어 있거나 생략되면 오류가 없을 때만 스텝이 실행되는 거예요(success()와 동일).

액션 파일 스키마

액션 파일 예시

_lakefs_actions/file_checker.yaml

name: Good files check
description: set of checks to verify that branch is good
on:
  pre-commit:
  pre-merge:
    branches:
      - main
hooks:
  - id: no_temp
    type: webhook
    description: checking no temporary files found
    properties:
      url: "https://example.com/webhook?notmp=true?t=1za2PbkZK1bd4prMuTDr6BeEQwWYcX2R"
  - id: no_freeze
    type: webhook
    description: check production is not in dev freeze
    properties:
      url: "https://example.com/webhook?nofreeze=true?t=1za2PbkZK1bd4prMuTDr6BeEQwWYcX2R"
  - id: alert
    type: webhook
    if: failure()
    description: notify alert system when check failed
    properties:
      url: "https://example.com/alert"
      query_params:
        title: good files webhook failed
  - id: notification
    type: webhook
    if: true
    description: notify that will always run - no matter if one of the previous steps failed
    properties:
      url: "https://example.com/notification"
      query_params:
        title: good files completed

참고

lakeFS는 이벤트가 발생했을 때만 액션 파일을 검증해요.

lakectl actions validate <path>로 액션 파일을 로컬에서 검증할 수 있어요.

액션 파일 업로드

액션 파일은 _lakefs_actions/ 접두사로 lakeFS 저장소에 업로드해야 해요. 액션 가능한 이벤트(위의 Supported Events 참고)가 발생하면 lakeFS는 이벤트가 발생한 저장소 브랜치에서 _lakefs_actions/ 접두사의 모든 파일을 읽어요. 액션 파일 파싱에 실패하면 Run이 실패로 끝나요.

예를 들어 lakeFS는 lakefs://example-repo/feature-1/_lakefs_actions/ 접두사로 매칭되는 모든 액션 파일을 다음 상황에서 찾아 실행해요:

• example-repo 저장소의 feature-1 브랜치에 커밋할 때.

• repo1 저장소에서 feature-1 브랜치를 main 브랜치로 머지할 때.

지원되는 이벤트

경고

prepare-commit 훅은 실험적이에요. 실행 중(prepare-commit과 pre-commit 사이)에 이 시점에는 브랜치 수준 잠금이 없어서 다른 변경이 브랜치에 적용될 수 있어요. 커밋될 내용을 검증해야 한다면, 커밋에 포함될 변경의 일관된 뷰를 제공하는 pre-commit 훅을 대신 사용하세요.

lakeFS Actions는 저장소별로 관리되고 저장소 사이에서 공유할 수 없어요. pre-* 이벤트의 어떤 액션이든 훅이 하나라도 실패하면 진행 중인 lakeFS 작업이 중단돼요. post-* 이벤트의 훅 실패는 작업을 되돌리지 않아요.

훅은 lakeFS 저장소의 특정 접두사에 기록되는 액션 파일로 관리돼요. 액션 파일이 선언적이고 YAML로 작성되므로, lakeFS 안에서 configuration-as-code가 가능해져요.

Runs API & CLI

Run은 트리거 이벤트가 발생했을 때 저장소의 액션 파일이 인스턴스화된 것을 말해요. 예컨대 저장소에 pre-commit 훅이 있으면 모든 커밋이 그 커밋에 해당하는 Run을 만들어요.

lakeFS는 저장소의 액션 파일을 가져오고, 파싱하고, 필터링한 뒤 각 액션 아래의 훅 실행을 시작해요. 실행된 모든 훅(각각 hook_run_id를 가짐)은 그 Run(run_id)의 컨텍스트 안에 있어요.

lakeFS API와 lakectl은 저장소, 브랜치, 커밋, 특정 액션별로 실행 결과를 노출해요. 엔드포인트는 각 Run 아래에서 실행된 훅의 실행 로그를 내려받을 수도 있어서 관측성(observability)에 도움이 돼요.

결과 파일

각 Run과 함께 lakeFS 저장소의 metadata 섹션에는 두 종류의 파일이 생겨요:

• _lakefs/actions/log/<runID>/<hookRunID>.log - 해당 훅 실행의 실행 로그예요.

• _lakefs/actions/log/<runID>/run.manifest - 해당 Run의 모든 훅 실행 결과와 추가 메타데이터를 담은 매니페스트예요.

참고

lakeFS 저장소의 metadata 섹션은 커밋, metarange 같은 lakeFS 자체 메타데이터가 보관되는 곳이에요. 여기 저장된 메타데이터 파일은 사용자가 저장한 파일처럼 접근할 수 없어요.

더 알아보기 (Learn more)

공식 문서: lakeFS Actions & Hooks 가이드