trivadis/lakefs-hooks

lakeFS-hooks Docker镜像文档

镜像概述和主要用途

lakeFS-hooks Docker镜像提供了一组简单的lakeFS Webhook，用于数据对象的预提交和预合并验证。通过设置这些规则，基于lakeFS的数据湖可以确保生产分支始终只包含有效、高质量的数据，同时允许在隔离分支上使用未测试版本进行实验。

核心功能和特性

包含组件

该项目包含以下基本构建块，便于构建自定义lakeFS预合并/预提交钩子：

1. 简洁的lakeFS Python客户端：提供基本的读取和差异比较功能
2. PyArrow文件系统实现：简单的只读实现，用于从lakeFS读取数据对象，支持使用PyArrow读取Parquet、ORC等格式，以便检查元数据或构建可查询表进行测试和验证
3. 可重用Webhook集合：满足常见CI需求的Webhook（详见下文）
4. Dockerfile：用于容器化Webhook服务器以便部署

内置Webhook

文件格式验证器

检查新文件是否属于允许的数据格式集合，可限定特定前缀。

示例：作为lakeFS预合并钩子

yaml
---
name: ParquetOnlyInProduction
description: 此Webhook确保仅Parquet文件可写入production/目录下
on:
  pre-merge:
    branches:
      - master
hooks:
  - id: production_format_validator
    type: webhook
    description: 验证文件格式
    properties:
      url: "http://<host:port>/webhooks/format"
      query_params:
        allow: ["parquet", "delta_lake"]
        prefix: production/

基本文件模式验证器

读取新的Parquet和ORC文件，确保它们不包含列名黑名单（或名称前缀），有助于避免意外的PII暴露。

示例：作为lakeFS预合并钩子

yaml
---
name: NoUserColumnsUnderPub
description: >-
  此Webhook确保包含以"user_"开头的列的文件
  不能写入public/目录下
on:
  pre-merge:
    branches:
      - master
hooks:
  - id: pub_prevent_user_columns
    type: webhook
    description: 确保public/下无user_*列
    properties:
      url: "http://<host:port>/webhooks/schema"
      query_params:
        disallow: ["user_", "private_"]
        prefix: public/

分区脏检查器

确保分区（或目录）完全不可变，仅允许以下情况写入目录：

• 覆盖目录中的所有文件
• 添加文件同时删除所有先前内容

如果添加或替换了文件但保留了部分先前内容，则视为"脏"分区并阻止提交（忽略空文件）。

示例：作为lakeFS预提交钩子

yaml
---
name: NoDirtyPartitionsInProduction
description: 检查tables/hive/下所有分区保持不可变
on:
  pre-commit:
    branches:
      - "*"
hooks:
  - id: hive_ensure_immutable
    type: webhook
    description: 检查所有Hive分区是否完全写入或完全替换
    properties:
      url: "http://<host:port>/webhooks/dirty_check"
      query_params:
        prefix: tables/hive/

提交元数据验证器

确保生产环境中的提交包含足够的元数据，以支持数据血缘和可追溯性。

示例：作为lakeFS预提交钩子

yaml
---
name: EnsureProductionCommitMetadata
description: >-
  检查写入production/的提交包含一组必填元数据字段，
  这些字段不能为空。
on:
  pre-commit:
    branches:
      - "*"
hooks:
  - id: production_ensure_commit_metadata
    type: webhook
    description: 检查所有写入production/的提交是否包含必填元数据字段
    properties:
      url: "http://<host:port>/webhooks/commit_metadata"
      query_params:
        prefix: production/
        fields: [airflow_dag_run_url, job_git_commit, update_sla, sources]

使用场景和适用范围

• 数据质量保障：确保生产分支数据格式、模式符合规范
• 数据安全控制：防止包含敏感信息（如PII）的文件进入公共区域
• 数据不可变性维护：确保分区数据完全更新，避免部分覆盖导致的数据不一致
• 元数据管理：强制提交元数据完整性，支持数据血缘追踪

适用于基于lakeFS构建的数据湖，需要对数据变更进行严格质量控制和合规检查的场景。

安装和使用方法

构建Docker镜像

sh
# 克隆仓库
git clone https://github.com/treeverse/lakeFS-hooks.git
cd lakeFS-hooks/

# 构建镜像
docker build -t lakefs-hooks:latest .

# （可选）标记并推送到镜像仓库

本地运行服务器（开发环境）

sh
# 安装依赖
pip install -r requirements.txt

# 设置环境变量
export LAKEFS_SERVER_ADDRESS="http://lakefs.example.com"
export LAKEFS_ACCESS_KEY_ID="<lakeFS用户的访问密钥ID>"
export LAKEFS_SECRET_ACCESS_KEY="<对应密钥ID的秘密访问密钥>"

# 启动Flask服务器
flask run

测试Webhook：使用curl发送示例预合并事件

sh
curl -v -XPOST -H 'Content-Type: application/json' \
  -d'{
       "event_type": "pre-merge",
       "event_time": "2021-02-17T11:04:18Z",
       "action_name": "test action",
       "hook_id": "hook_id",
       "repository_id": "my-lakefs-repository",
       "branch_id": "main",
       "source_ref": "220158b4b316e536e024aaaaf76b2377a6c71dfd6b974ca3a49354a9bdd0dbc3",
       "commit_message": "a commit message",
       "committer": "user1"
  }' 'http://localhost:5000/webhooks/schema'

运行Docker容器

shell
docker run \
    -e LAKEFS_SERVER_ADDRESS='http://lakefs.example.com' \
    -e LAKEFS_ACCESS_KEY_ID='<lakeFS用户的访问密钥ID>' \
    -e LAKEFS_SECRET_ACCESS_KEY='<对应密钥ID的秘密访问密钥>' \
    -p 5000:5000 \
    lakefs-hooks

配置参数

环境变量

支持与社区

• 问题反馈：https://github.com/treeverse/lakeFS-Flask-Webhook/issues/new
• 官方文档：lakeFS文档
• Slack：加入lakeFS Slack社区
• ****：@
• *******：@lakeFS
• *******：lakeFS频道
• 联系我们：lakeFS联系表单

许可信息

lakeFS-hooks基于Apache 2.0许可证开源。