dltHub 密钥管理实战：平台托管加密存储与 Google Secret Manager 自管保险库

dltHub 密钥管理实战平台托管加密存储与 Google Secret Manager 自管保险库【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt生产环境中的 dlt 管道运行时必须访问仓库密码、API Key、Token 等凭据。本文基于 dltHub 平台文档secrets-management.md系统讲解两类密钥管理方案——由 dltHub 平台托管加密存储或接入 Google Secret Manager 等外部保险库实现自带密钥库并结合 dlt 开源仓库源码vault.py、google_secrets.py剖析其底层查找、合并与缓存机制。读完后你将掌握在生产环境安全托管管道凭据的完整配置路径。两种密钥管理思路部署到 dltHub 的管道在运行期需要访问凭据数据仓库密码、API Key、Token。围绕谁来保存这些密钥文档给出两条路线让 dltHub 托管你的密钥把密钥放进 workspace 配置并部署dltHub 负责加密与存储。这是默认方案无需额外配置。自带密钥库Bring your own vault把密钥保存在外部密钥管理器如 Google Secret Manager让 dlt 在运行时按需拉取。生产环境推荐此方案。两条路线的本质区别在于密钥的存放点与暴露面前者将明文密钥交给平台后者只在.dlt/secrets.toml中保留用于访问保险库的最小凭据真实密钥永不进入部署配置。dltHub 如何托管你的密钥dltHub 平台对托管密钥的安全模型由文档给出如下承诺与机制密钥绝不以明文形式存在于平台上。部署时配置经加密通道传输并以静态加密encrypted at rest形式存储在一个安全、隔离的存储中。该存储仅能被单一 vault 服务身份访问且该身份运行在私有网络VPC内部平台其他组件无法触碰。运行时管道 runner 被授予短期访问权限且只能访问本次运行真正需要的密钥子集。这种单服务身份 VPC 隔离 短期最小授权的组合将密钥的存取面压缩到最小。用 Profiles 分离环境dltHub workspace 使用profiles来隔离环境。部署后的管道运行在prodprofile 下因此生产密钥放入.dlt/prod.secrets.toml开发密钥放入.dlt/dev.secrets.toml关于dev、prod、access三个 profile 的语义与使用时机详见 Profiles 文档。简单来说dev是本地开发默认 profile仅本地tests供自动化测试/CI 使用仅本地prod供 dltHub 平台批量任务使用同步到云端access是平台交互式笔记本的只读生产 profile同步到云端。本地运行默认使用dev平台批量任务自动选择prod交互式任务选择access未配置时回退到prod。对于隔离要求更高的生产场景更稳妥的做法是把密钥值保存在自己的保险库中见下文。使用自有保险库Google Secret Manager生产环境最稳健的模式是把真实密钥值存放在外部保险库中让 dlt 在运行时拉取这样你的secrets.toml只保存访问保险库所需的少量凭据而不是密钥本身。dlt 目前支持Google Secret Manager其他保险库AWS Secrets Manager、Azure Key Vault实现方式类似欢迎社区贡献。1. 添加依赖dlt 的 Google Secret Manager provider 依赖google-api-python-client。必须把它加入项目依赖使部署后的 runner 一并安装只装到本地环境会导致部署后的运行失败。在pyproject.toml中dependencies [ dlt[hub]1.17.0, google-api-python-client, ]然后刷新 lockfileuv lock再部署。从源码看该依赖是在GoogleSecretsProvider首次构建 Secret Manager 客户端时按需导入的见 google_secrets.py若缺失会抛出MissingDependencyException提示需要google-api-python-client。这解释了为什么必须让该包进入部署环境的依赖集。2. 创建 Google 服务账号并存储密钥这部分步骤对 OSS dlt 与 dltHub 完全一致详见 OSS 文档 Configure Google Secret Provider要点包括创建具有roles/secretmanager.secretAccessor角色的 GCP 服务账号并下载其 JSON key。在 Google Secret Manager 中添加密钥其中dlt_secrets_toml用于将整个secrets.toml作为单一密钥存储。了解单个密钥的命名约定。3. 在 workspace 中把 dlt 指向保险库在.dlt/secrets.toml中启用 provider并只填入 JSON key 文件中的服务账号凭据。真实密钥仓库 Token 等留在保险库中[providers] enable_google_secrets true [providers.google_secrets] only_secrets false list_secrets false [providers.google_secrets.credentials] project_id project_id client_email ...project_id.iam.gserviceaccount.com private_key -----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n也可以使用环境变量完成等价配置详见 Activate Google Secret Provider。4. 部署并运行uv run dlthub deploy uv run dlthub run my_jobdlthub deploy会同步你的代码与保险库引导配置随后 runner 在运行时从 Google Secret Manager 拉取真实密钥。密钥值本身永远不会存入部署配置。底层原理VaultDocProvider 的查找、合并与缓存理解保险库 provider 的实现能帮助你正确配置密钥形态。dlt 在 vault.py 中定义了抽象基类VaultDocProvider其核心思想是把保险库中的密钥重建为一个类secrets.toml的内存 TOML 文档并作为缓存。文档 vaults.md 总结了它的行为查找并合并 TOML 片段推荐与单值可选合并进工作内存中的 TOML 文档对进程生命周期内所有取值做缓存减少重复调用可选地预列出所有可用密钥避免对不存在的密钥做无谓查询。查找与合并顺序首次访问任何配置值时provider 按以下顺序抓取并合并已知片段全局dlt_secrets_toml优先尝试名为dlt_secrets_toml的特殊密钥其值可以是完整secrets.toml。管道级dlt_secrets_toml若请求的是特定管道的值还会尝试pipeline_name.dlt_secrets_toml。已知 section 与名称provider 了解顶层 sectionsources与destination会按短路径到长路径探测使更具体的片段覆盖更一般的片段sources与sources.source_namedestination与destination.destination_name上述路径在提供管道名时都会同时探测全局与管道级两种作用域。单值查询可选若only_toml_fragmentsfalseTOML 片段未命中时可能查询单值——一次配置可能探测多个位置调用次数会显著增加。_load_fragments方法vault.py正是按此顺序实现的先加载管道级dlt_secrets_toml再对sources/destination依次查询最短路径destination、sources与次短路径destination.name、sources.name最后再查管道级作用域保证更具体片段覆盖更一般片段。合并行为与缓存片段本身是 TOML 文档按发现顺序合并更具体的片段如destination.bigquery覆盖destination优先。每次成功或失败的查询包括未找到都会被缓存到进程结束因此保险库中的变更在进程重启前不会生效。list_secretstrue时 provider 会预列出全部密钥名以跳过不存在的查询这能大幅减少后端调用但需要额外权限。三个关键开关provider 可通过三个布尔项调优调用次数默认值因 provider 而异配置项语义only_secrets为 true 时只抓取被 dlt 标记为 secret 的值如目标凭据、标注为 secret 的字段跳过非 secret 设置only_toml_fragments为 true 时只抓取已知 TOML 片段destination、destination.bigquery、sources、sources.facebook、dlt_secrets_toml跳过单值查询list_secrets为 true 时一次性列出所有密钥名之后跳过对不存在密钥的查询需要额外权限注意list_secrets与only_toml_fragments/only_secrets同时开启时某些查询仍可能被有意跳过源码 vault.py 会给出相应 warning。使用建议来自 vaults.md优先使用 TOML 片段destination、destination.name、sources、sources.name、dlt_secrets_toml最小化往返次数尽量开启list_secrets能显著减少对保险库后端的调用需要把保险库调用限制在 secret 类型配置如凭据时保持only_secretstrue非 secret 配置走环境变量或文件。Google 实现的细节GoogleSecretsProvidergoogle_secrets.py在_look_vault中访问projects/{project_id}/secrets/{full_key}/versions/latest并 base64 解码返回对 404密钥不存在与 403缺少roles/secretmanager.secretAccessor做了降级处理并记录 warning。_list_vault分页列出全部密钥若服务账号缺少roles/secretmanager.secretViewer且开启了list_secretstrue会抛出ConfigProviderException说明配置错误google_secrets.py。密钥命名约定与存储形态Google Secret 名称会被规范化为仅含字母、数字、连字符-与下划线_标点除-与_外与空白被移除section 之间用连字符连接例如destination.bigquery.credentials.project_id→destination-bigquery-credentials-project_idsources.pipedrive.pipedrive_api_key→sources-pipedrive-pipedrive_api_keydestination.bigquery→destination-bigquerymy_pipeline.dlt_secrets_toml→my_pipeline-dlt_secrets_toml这条规范化逻辑在源码 vault.py 的normalize_key中实现保留-与_其余标点与空白全部移除并由GoogleSecretsProvider.get_key_name以-为分隔符拼接google_secrets.py。存储整个secrets.toml最简单密钥名dlt_secrets_toml一个密钥存放你的secrets.toml内容写法与本地完全一致。dlt 会最先探测该密钥因此无需任何命名约定[destination.motherduck.credentials] password motherduck_token database database值里可以放任意多的 section——整个secrets.toml或仅一个凭据块如上。还可以用pipeline_name-dlt_secrets_toml形式的密钥把它限定到单个管道。按 section 存储片段每个密钥的值是一个带[section]头的 TOML 块密钥名destination[destination] postgres.credentials postgresql://loader:***host:5432/postgres密钥名destination-bigquery-credentials[destination.bigquery.credentials] project_id project_id private_key -----BEGIN PRIVATE KEY-----\n....\n-----END PRIVATE KEY-----\n client_email ....gserviceaccount.com密钥名destination-filesystem完整filesystem目标配置[destination.filesystem] bucket_url s3://bucket/path [destination.filesystem.credentials] region_name eu-central-1 aws_access_key_id ... aws_secret_access_key ...密钥名sources-mongodb[sources.mongodb] connection_url mongodbsrv://user:***host/db?authSourceadmintlstrue存储单值每个密钥的值是不带 TOML 头的裸字符串。这需要更多保险库调用。例如以下密钥会被当作类似环境变量的取值sources-pipedrive-pipedrive_api_keydestination-bigquery-credentials-project_iddestination-bigquery-credentials-private_keydestination-bigquery-credentials-client_emaildestination-bigquery-location关于list_secrets的注意点当list_secretstrue时provider 会预列出全部密钥名以跳过对不存在密钥的查询。若服务账号缺少roles/secretmanager.secretViewer列出将失败provider 会抛出配置错误。用静态出口 IP 加固访问如果保险库或其凭据对应的数据仓库支持 IP 白名单可以将其限制为只接受来自 dltHub runner 的流量。按 job 选择开启在 job 的run.pipeline装饰器中添加require{static_egress_ips: True}run.pipeline(my_pipeline, require{static_egress_ips: True}) def my_job(): ...然后在目标资源上放行你所在区域的 dltHub 出口 IP 集合当前各区域 IP 列表见 Static egress IPs。以 EU 区域为例静态出口 IP 为 63.181.217.92、18.156.57.4、63.183.227.2、63.182.151.74US 区域为 34.205.113.62、44.221.24.144、34.193.87.36、98.80.106.70、54.81.217.233。该选项与require.instance、require.dependency_groups一样属于 Job configuration 中按 job 级别的运行配置。与平台环境变量的配合除了 TOML 与保险库dltHub 平台还提供 workspace 级与 profile 级的进程环境变量environment-variables.mdworkspace 级变量作用于每次运行profile 级变量仅在该 profile 生效时覆盖同名 workspace 变量。这些变量在运行启动时被注入进程环境dlt 通过优先级最高的环境变量 provider 读取因此形如DESTINATION__POSTGRES__CREDENTIALS的变量会覆盖部署在prod.secrets.toml中的同名键——这是另一条与外部保险库互补的凭据注入通道适合不希望进仓库的进程级配置。最佳实践小结综合文档与源码在生产环境管理 dltHub 管道密钥时可遵循环境隔离生产密钥放.dlt/prod.secrets.toml开发密钥放.dlt/dev.secrets.toml平台批量任务自动使用prodprofile。生产优先自带保险库secrets.toml只保存访问保险库的凭据真实密钥放 Google Secret Manager或其他兼容 vault。优先整段 TOML 片段以dlt_secrets_toml或destination/sources片段存储能大幅减少对保险库的往返调用。尽量开启list_secrets预列密钥可显著减少后端调用但需确保服务账号具备secretViewer权限。按需加固网络保险库或仓库支持 IP 白名单时为 job 开启static_egress_ips并按区域放行出口 IP。依赖纳入部署环境google-api-python-client必须写入项目依赖并刷新 lockfile否则部署后运行会因缺少依赖失败。路线图内置的 dltHub vault 已在规划中——届时无需接线外部 provider 即可原生管理密钥。在此之前上述平台托管 外部保险库 静态出口 IP的组合已经可以支撑生产级密钥管理。延伸阅读VaultsOSS 参考vault provider 完整参考含 Google Secret Manager、AWS Secrets Manager 与 Airflow Variables 三种 provider 的配置与命名约定。Profilesdev、prod、access及自定义 profile 如何分离环境与工作目录。Job configuration静态出口 IP、实例规格、依赖组等按 job 配置项。Environment variablesworkspace 与 profile 级进程环境变量。Credentials setupdlt 配置 provider 的完整优先级顺序。源码实现vault.py、google_secrets.py、provider.py。【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考