DataHub Snowflake 连接器前置指南权限模型与认证配置全解析【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub导读本指南围绕 DataHub 元数据摄取ingestion体系中的 Snowflake 连接器完整讲解生产环境接入前的两项前置工作在 Snowflake 侧创建最小权限的数据摄取角色以及为连接器配置安全可靠的认证方式。读完本文你将能够按照最小权限原则编写授权 SQL、理解每一项 privilege 的用途与取舍并掌握用户名密码、Key Pair 与 Okta OAuth 三类认证的 recipe 配置方法为后续的表/视图元数据、血缘lineage、使用统计usage与标签tags摄取打好基础。文档主体内容来自 snowflake_pre.md并结合作者仓库中 snowflake_config.py、snowflake_connection.py 等源码进行纵深印证。一、OverviewSnowflake 连接器解决什么问题snowflake模块源码位于 metadata-ingestion/src/datahub/ingestion/source/snowflake/负责将 Snowflake 仓库中的元数据摄取到 DataHub面向生产级摄取工作流。根据同目录 README.md 中的概念映射表该连接器覆盖的实体范围包括数据库 / 模式映射为 DataHub 的 ContainerDATABASE / SCHEMA表 / 视图 / 动态表 / 外部表 / 流Stream映射为 Dataset其中动态表还包含 target lag、SQL 定义以及与源表的血缘列SchemaField提取列类型、可空性、描述与标签表级与列级血缘来自视图定义、动态表定义以及 SQL 查询历史使用统计DatasetUsageStatistics与操作Operation按数据集统计查询次数、用户访问模式与 DML 操作指标标签Tag受extract_tags配置控制支持数据库/模式/表/列级继承角色Role映射为urn:li:corpGroup:{role_name}。前置条件章节即本文主体回答的是在真正开始摄取之前运维需要在 Snowflake 侧做什么——本质上是为连接器创建一个遵循最小权限原则的专用角色与用户并视功能需求授予对共享SNOWFLAKE数据库Account Usage的访问权。二、Prerequisites创建 DataHub 专用角色与用户连接器需要特定的 privilege 才能读取 Snowflake 仓库中的元数据。官方建议以ACCOUNTADMIN身份或具有MANAGE GRANTS权限的用户执行下述 SQL创建一个 DataHub 专属角色并完成授权。以下脚本完整继承自原文档并补充了每一段注释对应的功能说明create or replace role datahub_role; // 授予对 warehouse 的访问权以便运行查询查看元数据 grant operate, usage on warehouse your-warehouse to role datahub_role; // 授予对数据库和模式的访问权以便查看其中的表/视图/动态表 grant usage on DATABASE your-database to role datahub_role; grant usage on all schemas in database your-database to role datahub_role; grant usage on future schemas in database your-database to role datahub_role; grant select on all streams in database your-database to role datahub_role; grant select on future streams in database your-database to role datahub_role; // 若未使用 Snowflake Profiling 或 Classification 功能为表和视图授予 references 权限 grant references on all tables in database your-database to role datahub_role; grant references on future tables in database your-database to role datahub_role; grant references on all external tables in database your-database to role datahub_role; grant references on future external tables in database your-database to role datahub_role; grant references on all views in database your-database to role datahub_role; grant references on future views in database your-database to role datahub_role; -- Note: Semantic views are covered by the above view grants // 若存在 Dynamic Tables 且希望 DataHub 提取它们及其血缘需要 monitor 权限 grant monitor on all dynamic tables in database your-database to role datahub_role; grant monitor on future dynamic tables in database your-database to role datahub_role; // 若使用了 Snowflake Profiling 或 Classification 功能为表授予 select 权限 grant select on all tables in database your-database to role datahub_role; grant select on future tables in database your-database to role datahub_role; grant select on all external tables in database your-database to role datahub_role; grant select on future external tables in database your-database to role datahub_role; grant select on all dynamic tables in database your-database to role datahub_role; grant select on future dynamic tables in database your-database to role datahub_role; // 创建 DataHub 用户并绑定 datahub_role create user datahub_user display_name DataHub password default_role datahub_role default_warehouse your-warehouse; // 将 datahub_role 授予新用户 grant role datahub_role to user datahub_user; // 可选 - 提取血缘、使用统计或标签不含血缘时需要 grant imported privileges on database snowflake to role datahub_role; // 可选 - INTERNAL marketplace私有数据共享摄取所需 // 该授权用于 // - SHOW AVAILABLE LISTINGS (IS_ORGANIZATION TRUE) 查看内部市场 listing // - SNOWFLAKE.ACCOUNT_USAGE.DATABASES 识别导入的数据库 // - SNOWFLAKE.DATA_SHARING_USAGE.LISTING_ACCESS_HISTORY 统计使用情况 // - DESCRIBE AVAILABLE LISTING 丰富元数据当 fetch_internal_marketplace_listing_detailstrue 时 grant imported privileges on database snowflake to role datahub_role; // 市场提供方模式marketplace_mode: provider 或 both需要 // SHOW SHARES 会列出角色拥有或继承的 shareDESC SHARE 要求 share 的 OWNERSHIP。 // 市场创建的 share 通常由 SYSADMIN 拥有如需 DESC SHARE需将 SYSADMIN 授予 DataHub 角色 use role securityadmin; grant role sysadmin to role datahub_role; // 或者直接在 recipe 中设置 role: SYSADMIN // 可选 - 提取 Streamlit Apps 时需要 grant usage on all streamlits in database your-database to role datahub_role; grant usage on future streamlits in database your-database to role datahub_role; // 可选 - 提取 Stages、Tasks 或 Pipes 时需要 grant usage on all stages in database your-database to role datahub_role; grant usage on future stages in database your-database to role datahub_role; grant monitor on all tasks in database your-database to role datahub_role; grant monitor on future tasks in database your-database to role datahub_role; grant monitor on all pipes in database your-database to role datahub_role; grant monitor on future pipes in database your-database to role datahub_role;上述脚本体现了一个重要设计权限不是一次性全量授予而是按所需功能逐步叠加。include_stages、include_tasks、include_pipes、include_streamlits等摄取开关定义见 snowflake_config.py与上面对应的 grant 一一对应仅当你在 recipe 中打开这些功能时才需要对应权限。2.1 各项 privilege 的作用与最小权限权衡原文档逐项说明了每个 privilege 为什么必要这里完整保留并补充实践建议operate仅用于启动 warehouse。如果摄取期间 warehouse 已在运行或启用了自动恢复auto-resume该权限并非必需。由于operate存在成本风险可被用来启动计算资源建议尽量依赖 auto-resume 而省略它。usagewarehouse用于使用该 warehouse 运行查询。usagedatabase 与 schema极易被遗漏的关键权限。若没有 database/schema 上的usage即使表上已授权表、视图和流依然不可见。管理员若只授予了table上的权限而漏掉 schema 或 database连接器将无法取得这些对象的元数据。按需收窄到单个 schema如果只需要摄取部分 schema 的元数据可以只对特定 schema 授权而不是对整个数据库授权grant usage on schema your-database.your-schema to role datahub_role;selectstreams用于读取流定义使流能够被提取为 DataHub 的 DatasetSNOWFLAKE STREAM。注意这不意味着可以读取底层数据——除非底层数据集本身有 select 权限。usagestreamlit用于展示数据库中的 Streamlit 应用仅在include_streamlits: true时需要授权方式参考上面的 schema 级示例。usagestages用于通过SHOW STAGES列出 stage仅在include_stages: true或include_pipes: true时需要。monitortasks用于通过SHOW TASKS列出 task仅在include_tasks: true时需要。monitorpipes用于通过SHOW PIPES列出 pipe仅在include_pipes: true时需要。monitordynamic tablesDataHub 提取动态表的表级与列级血缘所必需。原文档特别强调以上是提取数据库、schema、视图与表所需的最低权限集合。若需启用更多功能请按可选段落继续授权。2.2 启用血缘 / 使用统计 / 标签Account Usage 访问权如果计划通过include_table_lineage启用表级血缘、通过include_usage_stats启用使用统计或通过extract_tags启用标签提取不含血缘还需要授予对snowflake数据库Account Usage 系统表所在位置的访问权grant imported privileges on database snowflake to role datahub_role;需要注意imported privileges的授予方式SNOWFLAKE数据库是 Snowflake 拥有的共享数据库与普通数据库不同——普通数据库可以对单个表授予细粒度的SELECT而共享数据库只能通过IMPORTED PRIVILEGES一次性获得对库内所有对象的全有或全无all-or-nothing访问。其覆盖范围主要是SNOWFLAKE.ACCOUNT_USAGE.*全部视图如QUERY_HISTORY、ACCESS_HISTORY、USERS等SNOWFLAKE.ORGANIZATION_USAGE.*需要 Snowflake 支持团队在组织层面单独开通。2.2.1 DataHub 具体访问哪些 ACCOUNT_USAGE 表下表原文档原表列出了授予IMPORTED PRIVILEGES后连接器实际访问的ACCOUNT_USAGE表及其用途你可以据此判断自己的功能组合究竟需要哪些权限TablePurposeRequired ForQUERY_HISTORYQuery logs for lineage, usage stats, and semantic view usage/queriesinclude_table_lineage,include_usage_stats; for semantic viewssemantic_views.enabledsemantic_views.include_usage/semantic_views.include_queriesACCESS_HISTORYTable/view lineage and access patternsinclude_table_lineage,include_usage_statsUSERSUser email mapping for corp user entitiesinclude_usage_stats(for user attribution)TAG_REFERENCESTag metadata extractionextract_tagsVIEWSView metadata (DDL, ownership, etc.) for all viewsAlways (when views exist)COPY_HISTORYLineage fromCOPY INTOoperations (all stages/sources)include_table_lineage这些表在源码中的使用可以得到印证例如 snowflake_query.py 中存在对SNOWFLAKE.ACCOUNT_USAGE.VIEWS、SNOWFLAKE.ACCOUNT_USAGE.USERS、SNOWFLAKE.ACCOUNT_USAGE.DATABASES的查询以及针对 semantic view 使用统计的QUERY_HISTORY查询snowflake_tag.py 在标签缓存加载失败时会明确提示检查摄取角色对SNOWFLAKE.ACCOUNT_USAGE.TAG_REFERENCES的访问权。如果因安全策略无法授予IMPORTED PRIVILEGES则血缘、使用统计、标签等依赖 Account Usage 的功能将不可用并在摄取日志中看到权限错误如SnowflakePermissionError见 snowflake_connection.py 中_is_permission_error对Insufficient privileges/not authorized的识别逻辑。这是取舍而非故障基础的表/视图元数据提取不受影响。2.3 血缘与统计类功能的版本前提还需注意部分功能对 Snowflake 版本有硬性要求。从 snowflake_config.py 的字段描述与 snowflake_lineage_v2.py 的注释可以看出include_table_lineage表到表、S3 到 Snowflake 表血缘与include_column_lineage列级血缘依赖snowflake.account_usage.access_history视图需要 Snowflake Enterprise Edition 或以上semantic views 属于 Cortex Analyst 功能集同样要求 Enterprise Edition 或以上配置校验器会在known_snowflake_edition被显式设置为 STANDARD 时自动关闭semantic_views.enabled并给出告警known_snowflake_edition配置项允许显式指定版本STANDARD 或 ENTERPRISE未设置时连接器通过SHOW TAGS自动推断。三、Authentication连接器的四种认证方式前置条件的第二部分是认证。原文档指出最简单的认证方式是 Snowflake 用户名 密码也可以通过authentication_type配置项使用其他方式。从 snowflake_connection.py 的_VALID_AUTH_TYPES可以看到连接器实际支持的认证类型全集_VALID_AUTH_TYPES: Dict[str, str] { DEFAULT_AUTHENTICATOR: DEFAULT_AUTHENTICATOR, # 用户名 密码 EXTERNAL_BROWSER_AUTHENTICATOR: EXTERNAL_BROWSER_AUTHENTICATOR, KEY_PAIR_AUTHENTICATOR: KEY_PAIR_AUTHENTICATOR, # 密钥对 OAUTH_AUTHENTICATOR: OAUTH_AUTHENTICATOR, # OAuth通过 oauth_config 换 token OAUTH_AUTHENTICATOR_TOKEN: OAUTH_AUTHENTICATOR, # 外部直接提供 OAuth token }配置校验器authenticator_type_is_valid会强制执行一致性约束若同时设置了private_key/private_key_path而authentication_type不是KEY_PAIR_AUTHENTICATOR会直接报错使用OAUTH_AUTHENTICATOR时必须提供oauth_config。此外连接器在get_connect_args()中默认注入CLIENT_PREFETCH_THREADS: 10与CLIENT_SESSION_KEEP_ALIVE: True以提升大结果集查询性能并避免超时同时允许通过connect_args覆盖默认值。3.1 Key Pair 认证若选择 Key Pair 认证请先在 Snowflake 侧完成三步准备生成私钥、生成公钥、将公钥绑定到 recipe 中要使用的 DataHub 用户然后在 recipe 中用以下配置替代 password。注意私钥必须保持正确的 PEM 格式——开头、结尾以及密钥内部约每 64 个字符处都要有换行符authentication_type: KEY_PAIR_AUTHENTICATOR private_key: Private key in a form of -----BEGIN PRIVATE KEY-----\nprivate-key\n-----END PRIVATE KEY----- # Optional - if using encrypted private key private_key_password: Password for your private key从源码看private_key也可以替换为private_key_path指向本地私钥文件的路径二者至少提供一个。连接器在 snowflake_connection.py 的get_connect_args()中会读取 PEM 私钥支持加密私钥通过private_key_password解密转换为 DER/PKCS8 字节后以private_keyconnect arg 交给 Snowflake Python Connector。3.2 Okta OAuthOkta OAuth 的配置大致遵循 Snowflake 官方的 Okta OAuth 接入步骤然后在 recipe 的oauth_config中传入以下字段provider: oktaclient_id:OAUTH_CLIENT_IDclient_secret:OAUTH_CLIENT_SECRETauthority_url:OKTA_OAUTH_TOKEN_ENDPOINTscopes: 你的 Okta scopes 列表即带有session:role:前缀的那些DataHub 仅支持两种 OAuth grant 类型client_credentials和password两者在 Okta 侧的准备工作略有不同。对应地oauth_config.py 中的OAuthConfiguration定义了provider目前支持microsoft与okta、authority_url、client_id、scopes、use_certificate、client_secret等字段并提供基于证书use_certificate: true时使用 base64 编码的公/私钥或基于 secret 的两种 token 获取路径token 的换取与注入逻辑在 oauth_generator.py 与get_oauth_connection()中实现。Client Credentials Grant Type较简单在 Okta 创建 App Integration 时选择类型API Services确保客户端认证方式为Client secret记下你的Client ID创建一个与 Okta client credentials 对应的 Snowflake 用户确保该用户的Login Name与 Okta 应用的Client ID一致确保该用户已被授予 DataHub 角色。Password Grant Type在 Okta 创建 App Integration 时选择类型OIDC - Native Application添加 Grant TypeResource Owner Password确保客户端认证方式为Client secret创建一个用于登录的 Okta 用户记下Username和Password创建一个与 Okta client credentials 对应的 Snowflake 用户确保该用户的Login Name与 Okta 用户的Username一致通常是邮箱确保该用户已被授予 DataHub 角色运行摄取时在oauth_config中提供client_id与client_secret并在 recipe 顶层提供 Okta 用户的Username和Password注意username和password这两个配置项不嵌套在oauth_config之下而是与account_id、warehouse等平级。四、Recipe 示例把权限与认证落到配置上完成授权与认证准备后即可编写摄取 recipe。官方示例文件位于 snowflake_recipe.yml一个最小可用配置如下变量通过环境变量注入避免明文密码source: type: snowflake config: # This option is recommended to be used to ingest all lineage on the first run. ignore_start_time_lineage: true # Coordinates account_id: abc48144 warehouse: COMPUTE_WH # Credentials username: ${SNOWFLAKE_USER} password: ${SNOWFLAKE_PASS} role: datahub_role # (Optional) Uncomment and update this section to filter ingested datasets # database_pattern: # allow: # - ^ACCOUNTING_DB$ # - ^MARKETING_DB$ profiling: # Change to false to disable profiling enabled: true # This option is recommended to reduce profiling time and costs. turn_off_expensive_profiling_metrics: true # (Optional) Uncomment and update this section to filter profiled tables # profile_pattern: # allow: # - ACCOUNTING_DB.*.* # - MARKETING_DB.*.*其中role: datahub_role即指向前文创建的专用角色account_id支持多种格式如xy12345、xy12345.us-east-2.aws、xy12345.central-us.azure、xy12345.us-west-2.privatelink等详见 snowflake_connection.py 中account_id字段描述该字段会自动去除协议头、尾斜杠与域名后缀。与前置权限章节呼应recipe 中还提供了若干按需开启的功能开关开启前请确保已授予对应权限可对照本文 2.1 节的 grant 脚本marketplace摄取 INTERNAL marketplace私有数据共享listing 为 Data Products支持marketplace_mode: consumer / provider / both三种模式provider 或 both 模式要求将imported privileges on database snowflake授予 USER而非仅授予 role因为 Snowflake 中 share 的访问是按用户级别授权的shares将导入的数据库与其来源 share/listing 关联运行SHOW SHARES与SELECT DATABASE_NAME FROM SNOWFLAKE.ACCOUNT_USAGE.DATABASES WHERE TYPEIMPORTED DATABASE可获取所需信息include_streamlits、include_stages、include_tasks、include_pipes分别摄取 Streamlit 应用Dashboard、StageContainer、TaskDataJob与 SnowpipeDataJob。默认 sink 为 datahub-rest无需额外配置如需自定义可参考仓库的 sink 文档。五、常见问题与排障要点结合源码与原文档将实践中高频出现的问题归纳如下Database/SCHEMA XXXX does not exist or not authorized最常见原因是授予了table级别权限但遗漏了database/schema的usage。补上 2.1 节中的 database 与 schema 级usagegrant 即可连接器在 snowflake_connection.py 中会将此类错误归类为SnowflakePermissionError并记录到摄取报告中。血缘 / 使用统计 / 标签功能不生效检查是否已执行grant imported privileges on database snowflake to role datahub_role若无法授予安全策略限制这些功能将按设计降级不可用且日志会出现权限错误参见 2.2 节。Key Pair 认证报错确认私钥为合法 PEM 格式起止行与约 64 字符换行确认authentication_type为KEY_PAIR_AUTHENTICATOR且private_key与private_key_path至少提供一个。OAuth 认证报错检查oauth_config.provider、client_id、client_secret、authority_url、scopes是否齐全确认 Snowflake 用户的Login Name与 Okta 侧 Client IDclient_credentials或 Usernamepassword grant严格一致username/password放在 recipe 顶层而非oauth_config内。Account Usage 查询偶发 002003 权限/不存在错误Snowflake 的 ACCOUNT_USAGE 系统视图在刷新期间可能短暂不可用。连接器在 snowflake_connection.py 中对这类错误实现了指数退避重试最多 4 次20/40/60 秒可自动缓解无需人工干预。结语Snowflake 连接器是 DataHub 元数据体系中覆盖范围最广的连接器之一而其生产可用性的起点正是前置的权限与认证配置通过本文的 grant 脚本可以按功能逐级叠加最小权限通过authentication_type与oauth_config可以安全地接入各类认证体系。完成这些前置工作后即可参考 snowflake_recipe.yml 开始正式摄取并进一步了解概念映射见 README.md与更完整的摄取参数见 snowflake_post.md。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考