Unity Catalog 中的 Azure 密钥保管库 密钥

Important

此功能在 Beta 版中。

使用 Azure 密钥保管库 支持 Unity Catalog 架构,这样可以在笔记本、作业和 UDF 中使用 Azure 密钥保管库 的秘密,而无需复制它们。 这些值会保留在 密钥保管库 中,Unity 目录的权限控制谁可以读取或使用每个秘密。

与向一个工作区公开整个保管库Azure 密钥保管库支持的机密范围不同,附加到元存储的每个工作区中都提供了一个密钥保管库支持的 Unity 目录架构,并单独授予对每个机密的访问权限。

要比较外部机密与 Azure Databricks 管理的机密和工作区机密作用域,请参见 选择将机密存储在何处。

外部秘密的工作原理

一个架构由一个到你的云秘密管理器的连接提供支持。 两个独立控制决定谁可以使用某个机密。 secret管理器中的服务凭证权限决定Unity Catalog可以导入和读取哪些秘密,而Unity Catalog的权限决定哪些主体可以使用这些秘密。

每个 密钥保管库 都有自己的架构。UC 特权决定谁可以使用这些机密。

在你为一个架构提供支持后,外部机密的行为如下:

  • 每次读取都会提取当前值:在机密管理器中轮换的值对下一次读取生效,Azure Databricks没有变化。 已经持有某个值的代码会保留该值,直到再次读取该秘密。 检索到的值可以像其他秘密一样缓存在请求它们的计算中。

  • 管理机密管理器中的机密:在其中创建、更新、轮换和删除机密。 它们在 Unity Catalog 中是只读的。 当你在机密管理器中永久删除某个机密时,Azure Databricks 会移除 Unity Catalog 机密,包括它的权限和标签。

  • 列出会导入新机密:列出架构对象将启动异步导入。 在您的密钥管理器中添加或移除的密钥,会在后续列出时显示在 Unity Catalog 中,对于大型存储来说,这可能需要几分钟。 你可以在某个 secret 出现在列表中之前按名称读取它。

  • 审核日志记录双方:Unity Catalog 审核日志记录读取机密的 Azure Databricks 主体。 云端日志将访问归因于服务凭证。

Requirements

  • 满足 Unity Catalog 机密的要求。

  • 必须在你的工作区中启用“外部密钥”Beta 版。 请参阅 Manage Azure Databricks 预览版。

  • 你需要一个 Unity Catalog 服务凭证,以及一个使用该凭证向你的密钥管理器进行身份验证的 Unity Catalog 连接。 参见 创建服务凭证 和 创建连接。

  • 要备份该架构,你需要在目录上具有 USE CATALOG、对该架构拥有所有权或具有 MANAGE,以及在连接上具有 USE CONNECTION。 该模式不能包含任何 Azure Databricks 管理的机密,因此请在备份该模式之前删除所有机密。

配置外部密钥

创建服务凭证

连接使用 Unity Catalog 服务凭证向你的密钥管理器进行身份验证。

  1. 创建由托管身份或服务主体提供支持的服务凭证,详见创建服务凭证。

  2. 授予该标识列出和读取 密钥保管库 中机密的权限。 例如,分配 密钥保管库 Secrets 用户角色,或赋予具有“获取”和“列出”机密权限的访问策略。

创建连接

创建一个使用服务凭证并指向你的密钥管理器的 Unity Catalog 连接。 你需要在 Metastore 上具有 CREATE CONNECTION。

目录浏览器

  1. 在目录资源管理器中,点击 + 菜单并选择 创建连接。

  2. 输入连接名称并选择 Azure 密钥保管库 连接类型。

  3. 选择服务凭证,并设置你的 密钥保管库 保管库名称。

  4. 单击 “创建” 。

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.cn:

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"

回归一个带有连接的模式

  1. 在目录资源管理器中,转到架构。

  2. 在模式详情中,找到外部秘密管理器设置并点击 启用。 只有当架构中没有任何机密时,启用才可用。

  3. 选择你创建的连接,然后确认。

要将模式指向不同的连接,请点击 编辑。 要将该模式返回到 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 密钥保管库不支持按标记筛选导入的机密。

Note

如果支持模式的外部秘密管理器与读取该模式的元存储或工作区处于不同区域,秘密值及其元数据会跨越区域。 Azure Databricks 不保证对外部机密进行区域内处理。

外部秘密名称和数值可能包含个人数据。 除非你的使用场景确有需要,否则你有责任确保其中不包含个人数据。

其他资源

资源 Description
Unity Catalog 密钥的最佳做法 按环境、应用或团队组织机密,让工作负载使用机密而不读取它们。
Unity Catalog 中的机密 创建、授予和读取 Unity Catalog 密钥。