Important
此功能在 Beta 版中。
使用 Azure 密钥保管库为 Unity Catalog 架构提供后端支持,以便在笔记本、作业和 UDF 中使用你的 Azure 密钥保管库机密,而无需复制它们。 这些值会保留在密钥保管库中,Unity Catalog 特权控制谁可以读取或使用每个机密。
与Azure 密钥保管库支持的秘密范围不同,后者会将整个vault暴露给一个工作区,密钥保管库支持的Unity Catalog模式在连接到元存储的每个工作区中都可用,并分别授予对每个秘密的访问权限。
要比较外部机密与 Azure Databricks 管理的机密和工作区机密作用域,请参见 选择将机密存储在何处。
外部秘密的工作原理
一个架构由一个连接到你的云机密管理器的连接提供后端支持。 两个独立的控制项决定谁可以使用某个机密。 secret管理器中的服务凭证权限决定Unity Catalog可以导入和读取哪些秘密,而Unity Catalog的权限决定哪些主体可以使用这些秘密。
在为架构配置后端支持后,外部机密的行为如下:
- 每次读取都会获取当前值:你在机密管理器中轮换的值会在下一次读取时生效,无需在 Azure Databricks 中进行任何更改。 已经持有某个值的代码会保留该值,直到再次读取该秘密。 检索到的值可以像其他秘密一样缓存在请求它们的计算中。
- 在秘密管理器中管理秘密:在那里创建、更新、轮换和删除秘密。 它们在 Unity Catalog 中是只读的。 当你在机密管理器中永久删除某个机密时,Azure Databricks 会移除 Unity Catalog 机密,包括它的权限和标签。
- 列出即会导入新机密:列出架构会启动一次异步导入。 在机密管理器中添加或移除的机密,要等到下一次列出操作后才会出现在 Unity Catalog 中;对于大型存储,这可能需要几分钟。 你可以在某个 secret 出现在列表中之前按名称读取它。
- 审核日志会记录两端信息:Unity Catalog 审核日志会记录读取机密的 Azure Databricks 主体。 云端日志将访问归因于服务凭证。
要求
- 满足Unity Catalog 机密的要求。
- 必须在你的工作区中启用“外部密钥”Beta 版。 请参阅 Manage Azure Databricks 预览版。
- 你需要一个 Unity Catalog 服务凭证,以及一个使用该凭证向你的密钥管理器进行身份验证的 Unity Catalog 连接。 参见 创建服务凭证 和 创建连接。
- 要为该架构配置后端支持,你需要在目录上拥有
USE CATALOG权限、拥有该架构的所有权或在该架构上拥有MANAGE权限,并在该连接上拥有USE CONNECTION权限。 该架构不能包含任何由 Azure Databricks 管理的机密,因此在为其配置后端支持之前,请先删除所有此类机密。
配置外部密钥
创建服务凭证
连接使用 Unity Catalog 服务凭证向你的密钥管理器进行身份验证。
- 创建由托管身份或服务主体提供支持的服务凭证,详见创建服务凭证。
- 授予该标识列出和读取 密钥保管库 中机密的权限。 例如,分配 密钥保管库 Secrets 用户角色,或赋予具有“获取”和“列出”机密权限的访问策略。
创建连接
创建一个使用服务凭证并指向你的密钥管理器的 Unity Catalog 连接。 你需要在元存储上拥有 CREATE CONNECTION 权限。
目录浏览器
- 在目录资源管理器中,点击 + 菜单并选择 创建连接。
- 输入连接名称并选择 Azure 密钥保管库 连接类型。
- 选择服务凭据,并设置你的密钥保管库的保管库名称。
- 单击 “创建” 。
Databricks 命令行界面 (CLI)
要创建连接,请运行以下命令。 将 vault_name 设置为您的 密钥保管库 名称,将 credential 设置为服务凭证名称:
databricks connections create --json '{
"name": "my_key_vault_connection",
"connection_type": "AZURE_KEY_VAULT",
"options": {
"vault_name": "my-vault",
"credential": "my_key_vault_credential"
}
}'
REST API
要创建连接,请运行以下命令。 Azure Databricks 将 vault_name 解析为 https://<vault_name>.vault.azure.net:
curl -X POST \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "my_key_vault_connection",
"connection_type": "AZURE_KEY_VAULT",
"options": {
"vault_name": "my-vault",
"credential": "my_key_vault_credential"
}
}' \
"$DATABRICKS_HOST/api/2.1/unity-catalog/connections"
用该连接为架构配置后端支持
- 在目录资源管理器中,转到架构。
- 在模式详情中,找到外部秘密管理器设置并点击 启用。 在架构中不再有机密之前,启用会一直不可用。
- 选择你创建的连接,然后确认。
要将该架构指向其他连接,请单击编辑。 要将该模式返回到 Azure Databricks 管理的存储,请编辑模式并禁用外部秘密。 任一更改都会移除之前导入的秘密,包括它们的权限和标签。
验证设置
为了确认 Unity Catalog 能够列出并读取你的密钥,请在笔记本中运行以下内容:
# List the secrets in the schema. This also starts an import of new secrets.
dbutils.secrets.list(catalog="main", schema="orders_app")
# Read one secret by name
dbutils.secrets.get(catalog="main", schema="orders_app", key="example_secret")
如果列表是空的,几分钟后再运行一次。 如果读取失败,请参见 故障排除。
Unity Catalog 中的机密名称
Unity Catalog 仅在外部机密的名称满足以下规则时才会导入该机密:
- 超过255字符的名字不会导入。
- 名称不区分大小写。 如果两个机密仅大小写不同,Unity Catalog 会保留第一个导入的机密,忽略其余。
-
.变为:,/变为|。 Azure Databricks 建议避免在外部秘密名称中使用这些字符。
要在某个机密出现在列表中之前读取它,请使用其名称并进行这些替换。
Troubleshooting
- 一个机密被列出,但读取失败:身份可以列出该机密但无法读取其值,或者该机密在 密钥保管库 中被禁用。 授予 密钥保管库 Secrets 用户角色或具有“获取”权限的访问策略,或者重新启用该机密。
- 某个机密消失了:Unity Catalog 不会显示软删除的密钥保管库机密。 在密钥保管库中恢复机密。
- 没有新的机密出现:列出架构,等待几分钟,再重新列出。 检查 命名限制 和模式配额。
- 有些机密永远不会显示:一个架构最多可容纳 1,000 个机密。 当你的秘密管理器中的项超过该限制时,Unity Catalog 会按创建日期先导入最早创建的项,跳过其余的。 只暴露你在每个 schema 中需要的秘密。 请参阅按需要机密的用户进行分组。
局限性
除了适用于所有 Unity Catalog 机密的限制外,由外部后端支持的机密还具有以下限制:
- 不支持跨云访问:使用工作区所在云原生的机密管理器来为架构提供支持。
- 读取延迟和成本:每次读取都会从外部秘密管理器获取值,这会增加延迟并可能产生云服务提供商的成本。
- 无标签过滤:Azure 密钥保管库 不支持通过标签过滤导入的秘密。
注释
如果支持模式的外部秘密管理器与读取该模式的元存储或工作区处于不同区域,秘密值及其元数据会跨越区域。 Azure Databricks 不保证对外部机密进行区域内处理。
外部秘密名称和数值可能包含个人数据。 除非你的使用场景确有需要,否则你有责任确保其中不包含个人数据。
其他资源
| Resource | Description |
|---|---|
| Unity Catalog 密钥的最佳实践 | 按环境、应用或团队组织机密,让工作负载使用机密而不读取它们。 |
| Unity Catalog 中的机密 | 创建、授予和读取 Unity Catalog 密钥。 |