在 Unity 目录中配置外部秘密

本页展示了如何将 Unity Catalog 模式连接到外部秘密管理器，使其秘密值保持在 Azure 密钥保管库 中。

关于外部秘密的工作原理及其限制，请参见 Unity 目录中的外部秘密。

在您开始之前

• 满足 Unity Catalog 机密的要求。
• 必须在你的工作区中启用“外部密钥”Beta 版。
• 你想要进行外部备份的架构不得包含任何由 Azure Databricks 管理的机密。 切换后端前先删除已有的秘密。
• 你必须有连接到外部秘密管理器的 Unity Catalog 连接，以及连接用来认证的 Unity Catalog 服务凭证。 要创建这些对象，您必须在现有连接上具有 CREATE CONNECTION 权限，或者在元存储上具有 CREATE CREDENTIAL 权限以创建连接；此外，您还必须能够访问某个服务凭证，或者在元存储上具有 USE CONNECTION 权限以创建服务凭证。

• Azure 密钥保管库 支持仅在 Azure 上的 Azure Databricks 中可用，并且使用 AZURE_KEY_VAULT 连接。

配置外部密钥

创建服务凭证

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

创建一个由托管身份或服务主体支持的服务凭证，并授权其列出和读取目标 密钥保管库 中的秘密。 例如，分配 密钥保管库 Secrets 用户角色，或赋予一个等效的访问策略，并赋予获取和列表秘密权限。 有关说明，请参见 创建服务凭证。

创建连接

创建一个 Unity 目录连接，引用上一步的服务凭据，并指向你的外部秘密管理器。

目录浏览器

1. 在 Azure Databricks 中，打开目录资源管理器，点击+菜单，然后选择创建连接。
2. 输入连接名称并选择 Azure 密钥保管库 连接类型。
3. 选择用于身份验证的服务凭证，并设置 密钥保管库 的 保管库名称。
4. 单击 “创建” 。

Databricks 命令行界面 (CLI)

使用 AZURE_KEY_VAULT 连接类型传递 --json 连接正文。 将 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

使用 /api/2.1/unity-catalog/connections 端点，并采用 AZURE_KEY_VAULT 连接类型。 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"

回归一个带有连接的模式

在目录浏览器中配置架构的机密后端。

1. 在 Azure Databricks 中，打开目录资源管理器，进入 schema。

2. 在模式详情中，找到外部秘密管理器设置，点击 启用。

   该模式不得包含任何 Azure Databricks 管理的秘密。 如果是这样，请先将其移除。 启用 将保持禁用状态，直到该架构中不含任何机密信息。

3. 选择你在上一步创建的连接，然后确认。

该模式现在由你的外部秘密管理器支持，其秘密会显示在 Unity 目录中。

要将模式指向不同的连接，请使用编辑。 要将该模式返回到 Azure Databricks 管理的存储，请编辑模式并禁用外部秘密。

设置或更改架构的机密后端，要求对父目录具有 USE CATALOG、拥有该架构的所有权或对其具有 MANAGE，以及对该连接具有 USE CONNECTION。

读取外部机密

在架构由外部支持后，其密钥会显示在 Unity Catalog 中，你可以像读取任何其他 Unity Catalog 密钥一样读取它们。 列出一个模式会触发导入，因此新添加的秘密只会在下一个列表之后出现。 两个云的读取命令是一样的。

Dbutils

dbutils 采用秘密涂黑，是推荐的读取数值方式。 需要Databricks Runtime 17.3 LTS及以上版本，或无服务器环境版本4及以上。

# List the secrets in the schema
all_secrets = dbutils.secrets.list(catalog="main", schema="default")

# Read a specific secret value from the external secret manager
my_secret = dbutils.secrets.get(catalog="main", schema="default", key="example_secret")

REST API

设置 include_value=true 并读取 effective_value 字段以返回该值。 REST API 不会遮蔽返回的值，但仍会审计访问;Azure Databricks 建议dbutils改用。

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "include_value=true" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

你也可以在目录资源管理器中浏览和列出外部秘密，就像 Azure Databricks 管理的秘密一样。 参见 阅读秘密。

如果某个秘密还没有出现在Unity Catalog中，你仍然可以通过名称读取它。 请按照其在外部密钥管理器中显示的名称填写，并应用 命名限制 中的字符替换。

其他资源