为托管服务启用客户管理的密钥

项目
11/12/2024

注意

此功能需要高级计划。

为了进一步控制数据，你可以添加自己的密钥来保护和控制对某些数据类型的访问。 Azure Databricks 具有多个客户管理的密钥功能。若要比较相关功能，请参阅用于加密的客户管理的密钥。

提示

本文介绍如何从 Azure Key Vault 保管库为托管服务配置你自己的密钥。若要了解如何使用 Azure Key Vault 托管 HSM 中的密钥，请参阅为托管服务启用 HSM 客户管理的密钥。

Azure Databricks 控制平面中的托管服务数据将静态加密。可以为托管服务添加客户管理的密钥，以帮助保护和控制对以下加密数据的访问：

Azure Databricks 控制平面中的笔记本源。
笔记本结果以交互方式（不是作为作业）运行，存储在控制平面中。默认情况下，较大的结果也存储在工作区根存储桶中。你可以将 Azure Databricks 配置为将所有交互式笔记本结果存储在云帐户中。
机密管理器 API 存储的机密。
Databricks SQL 查询和查询历史记录。
用于设置 Git 与 Databricks Git 文件夹集成的个人访问令牌 (PAT) 或其他凭据。

为工作区添加客户管理的密钥加密后，针对用于对工作区托管服务数据的未来写入操作进行加密的密钥来说，Azure Databricks 将使用你的密钥来控制对其的访问。现有数据未重新加密。数据加密密钥缓存在内存中，用于多个读写操作，并定期从内存中逐出。针对这些数据的新请求需要向云服务的密钥管理系统发出另一个请求。如果删除或撤销密钥，受保护数据的读取或写入操作将会在缓存时间间隔结束时失败。

你可以之后轮换（更新）客户管理的密钥。请参阅，稍后轮换密钥。

此功能不会对存储在控制平面之外的数据进行加密。有关其他客户管理的密钥功能，请参阅用于加密的客户管理的密钥

要求

要将 Azure CLI 用于这些任务，请安装 Azure CLI 工具并安装 Databricks 扩展：
```
az extension add --name databricks
```
要将 Powershell 用于这些任务，请安装 Azure PowerShell 并安装 Databricks Powershell 模块。此外，还必须登录：
```
Connect-AzAccount
```
要以用户身份登录到 Azure 帐户，请参阅使用 Azure Databricks 用户帐户登录 PowerShell。要以服务主体身份登录到 Azure 帐户，请参阅使用 Microsoft Entra ID 服务主体进行 PowerShell 登录。

步骤 1：设置密钥保管库

必须创建 Azure Key Vault 实例并设置其权限。可以通过 Azure 门户、CLI 或 API 执行此操作。

重要

Key Vault 必须与你的 Azure Databricks 工作区位于同一 Azure 租户中。

这些说明提供了多种部署选项的详细信息：

使用 Azure 门户
使用 Azure CLI
使用 Azure PowerShell

使用 Azure 门户

创建或选择密钥保管库：
- 若要创建密钥保管库，请转到用于创建密钥保管库的 Azure 门户页。单击“+ 创建”。输入资源组名称、密钥保管库名称、区域和定价层。依次单击“查看 + 创建”、“创建”。
- 若要使用现有的密钥保管库，请复制其密钥保管库名称以便在下一步骤中使用。
获取 AzureDatabricks 应用程序的对象 ID：
1. 在 Azure 门户中，转到 Microsoft Entra ID。
2. 在边栏菜单中选择“企业应用程序”。
3. 搜索 AzureDatabricks，并单击结果中的“企业应用程序”。
4. 从“属性”中复制对象 ID。
使用 Azure 门户添加密钥保管库的访问策略：
1. 导航到用于为工作区托管服务配置客户管理的密钥的 Azure 密钥保管库。
2. 在左侧面板中单击“访问策略”选项卡。
3. 选择页面顶部的“创建”按钮。
4. 在“权限”选项卡中的“密钥权限”部分下，启用“获取”、“解包密钥”和“包装密钥” 。
5. 单击“下一步”。
6. 在“主体”选项卡上，键入 AzureDatabricks 并滚动到第一条包含应用程序 ID 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d 的企业应用程序结果，并将它选中。
7. 转到“查看 + 创建”选项卡并单击 b。

使用 Azure CLI

使用 Azure CLI 按照以下说明操作。

创建密钥保管库或选择现有密钥保管库：
- 要创建密钥保管库，请使用以下 Azure CLI 命令，并将括号中的项目替换为所在区域、密钥保管库名称、资源组名称和位置：
```
az keyvault create --location <region> \
                   --name <key-vault-name> \
                   --resource-group <resource-group-name> \
                   --location <location> \
                   --enable-purge-protection
```
- 若要使用现有的密钥保管库，请复制密钥保管库名称以便在下一步骤中使用。

使用 Azure CLI 获取 AzureDatabricks 应用程序的对象 ID。

az ad sp show --id "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d" \
              --query "id" \
              --output tsv

确认使用正确的 Azure 订阅：

az account set --subscription {subscription_id}

使用 Azure PowerShell

可以创建新密钥保管库，也可以使用现有密钥保管库。

创建 Key Vault：

$keyVault = New-AzKeyVault -Name <key-vault-name> \
-ResourceGroupName <resource-group-name> \
-Location <location> \
-sku <sku> \
-EnablePurgeProtection

使用现有密钥保管库：

$keyVault = Get-AzKeyVault -VaultName <key-vault-name>

步骤 2：准备密钥

你可以创建密钥或使用现有密钥。使用你喜爱的任何工具：Azure 门户、Azure CLI 或其他工具。

使用 Azure CLI

在 Key Vault 下创建密钥。 KeyType 必须是 RSA。

若要在 CLI 中创建密钥，请运行以下命令：

az keyvault key create --name <key-name> \
                       --vault-name <key-vault-name> \
                       --protection software

记下以下值，可以从响应的 kid 属性中的密钥 ID 获取这些值。你将在后续步骤中使用它们：

密钥保管库 URL：包含密钥保管库名称的密钥 ID 的开头部分。其形式为 https://<key-vault-name>.vault.azure.net。
Key name：密钥的名称。
Key version：密钥的版本。

完整的密钥 ID 格式通常为 https://<key-vault-name>.vault.azure.net/keys/<key-name>/<key-version>。非公有云中的 Azure 密钥保管库密钥采用不同的格式。

要使用现有密钥而不是创建密钥，请获取并复制密钥的这些值，以便在接下来的步骤中使用它们。在继续操作之前，请检查确认已启用现有密钥。

使用 Azure PowerShell

如果打算创建密钥，则可能需要根据创建密钥的方式和时间设置访问策略。例如，如果最近使用 PowerShell 创建了密钥保管库，则新密钥保管库可能缺少创建密钥所需的访问策略。以下示例使用参数“EmailAddress”设置访问策略。有关详细信息，请参阅 Microsoft 关于 Set-AzKeyVaultAccessPolicy 文章。

在新密钥保管库上设置访问策略：
```
Set-AzKeyVaultAccessPolicy \
-VaultName $keyVault.VaultName \
-PermissionsToKeys all \
-EmailAddress <email-address>
```

可以创建密钥或检索现有密钥：

创建密钥：

$key = Add-AzKeyVaultKey \
-VaultName $keyVault.VaultName \
-Name <key-name> \
-Destination 'Software'

检索现有密钥：

$key = Get-AzKeyVaultKey \
-VaultName $keyVault.VaultName \
-Name <key-name>

将具有权限的访问策略添加到密钥保管库：

$managedService = Get-AzureADServicePrincipal \
-Filter "appId eq '2ff814a6-3304-4ab8-85cb-cd0e6f879c1d'"

Set-AzKeyVaultAccessPolicy -VaultName $keyVault.VaultName \
-ObjectId $managedService.ObjectId \
-PermissionsToKeys wrapkey,unwrapkey,get

步骤 3：将密钥添加到工作区

可以使用客户管理的密钥为托管服务部署新的工作区，或将密钥添加到现有工作区。可以使用 Azure CLI、Powershell、ARM 模板、Azure 门户或其他工具同时执行这两项操作。本节包括多个部署选项的详细信息：

使用 Azure 门户（无模板）
使用 Azure CLI（无模板）
使用 Powershell（无模板）
使用 ARM 模板应用更改

使用 Azure 门户（无模板）

转到 Azure 门户主页。
单击页面左上角的“创建资源”。
在搜索栏中键入 Azure Databricks，然后单击“Azure Databricks”选项。
在 Azure Databricks 小组件中单击“创建”。
在“基本信息”和“网络”选项卡上的输入字段中输入值。
进入“加密”选项卡后：
- 要创建工作区，请在“托管服务”部分启用“使用你自己的密钥”。
- 要更新工作区，请启用“托管服务”。
设置加密字段。
- 在“密钥标识符”字段中，粘贴你的 Azure 密钥保管库密钥的密钥标识符。
- 在“订阅”下拉列表中，输入你的 Azure 密钥保管库密钥的订阅名称。
填写剩余的选项卡，然后单击“查看 + 创建”（若要新建工作区）或“保存”（若要更新工作区）。

重要

如果轮换密钥，则必须保留旧密钥 24 小时。

使用 Azure CLI（无模板）

使用以下命令添加密钥保管库的访问策略。将 <key-vault-name> 替换为在上一步中使用的保管库名称，并将 <object-id> 替换为 AzureDatabricks 应用程序的对象 ID。
```
az keyvault set-policy -n <key-vault-name> \
                       --key-permissions get wrapKey unwrapKey  \
                       --object-id <object-id>
```

创建或更新工作区：

对于创建和更新，请将这些字段添加到命令中：

managed-services-key-name：密钥名称
managed-services-key-vault：密钥保管库 URI
managed-services-key-version：密钥版本。使用特定的密钥版本，而不是 latest。

使用这些字段创建工作区的示例：

az databricks workspace create --name <workspace-name> \
--resource-group <resource-group-name> \
--location <location> \
--sku premium \
--managed-services-key-name <key-name> \
--managed-services-key-vault <key-vault-uri> \
--managed-services-key-version <key-version>

使用这些字段更新工作区的示例：

az databricks workspace update --name <workspace-name> \
--resource-group <resource-group-name> \
--managed-services-key-name <key-name> \
--managed-services-key-vault <key-vault-uri> \
--managed-services-key-version <key-version>

重要

如果轮换密钥，则必须保留旧密钥 24 小时。

使用 Powershell（无模板）

若要创建或更新工作区，请将以下参数添加到新密钥的命令中：

ManagedServicesKeyVaultPropertiesKeyName：密钥名称
ManagedServicesKeyVaultPropertiesKeyVaultUri：密钥 URI
ManagedServicesKeyVaultPropertiesKeyVersion：密钥版本。使用特定的密钥版本，而不是 latest。

使用这些字段创建工作区的示例：

New-AzDatabricksWorkspace -Name <workspace-name> \
-ResourceGroupName <resource-group-name> \
-location $keyVault.Location \
-sku premium \
-ManagedServicesKeyVaultPropertiesKeyName $key.Name \
-ManagedServicesKeyVaultPropertiesKeyVaultUri $keyVault.VaultUri \
-ManagedServicesKeyVaultPropertiesKeyVersion $key.Version

使用这些字段更新工作区的示例：

Update-AzDatabricksWorkspace -Name <workspace-name> \
-ResourceGroupName <resource-group-name> \
-sku premium \
-ManagedServicesKeyVaultPropertiesKeyName $key.Name \
-ManagedServicesKeyVaultPropertiesKeyVaultUri $keyVault.VaultUri \
-ManagedServicesKeyVaultPropertiesKeyVersion $key.Version

重要

如果轮换密钥，则必须保留旧密钥 24 小时。

使用 ARM 模板应用更改

以下 ARM 模板利用资源 Microsoft.Databricks/workspaces 的 API 版本 2023-02-01，使用客户管理的密钥创建新工作区。将此文本本地保存到名为 databricks-cmk-template.json 的文件。

此示例模板不包括所有可能的 Azure Databricks 功能，例如提供你自己的 VNet 以在其中部署工作区。

重要

如果已使用模板，则可以将此模板的其他参数、资源和输出合并到现有模板中。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "workspaceName": {
      "type": "string",
      "metadata": {
        "description": "The name of the Azure Databricks workspace to create."
      }
    },
    "pricingTier": {
      "type": "string",
      "defaultValue": "premium",
      "allowedValues": [
        "standard",
        "premium"
      ],
      "metadata": {
        "description": "The pricing tier of workspace."
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    },
    "apiVersion": {
      "type": "string",
      "defaultValue": "2023-02-01",
      "allowedValues":[
        "2023-02-01",
        "2021-04-01-preview"
      ],
      "metadata": {
        "description": "The api version to create the workspace resources"
      }
    },
    "keyvaultUri": {
      "type": "string",
      "metadata": {
        "description": "The Key Vault URI for customer-managed key for managed services"
      }
    },
    "keyName": {
      "type": "string",
      "metadata": {
        "description": "The key name used for customer-managed key for managed services"
      }
    },
    "keyVersion": {
      "type": "string",
      "metadata": {
        "description": "The key version used for customer-managed key for managed services. Use the specific key version and not `latest`."
      }
    }
  },
  "variables": {
    "managedResourceGroupName": "[concat('databricks-rg-', parameters('workspaceName'), '-', uniqueString(parameters('workspaceName'), resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Databricks/workspaces",
      "name": "[parameters('workspaceName')]",
      "location": "[parameters('location')]",
      "apiVersion": "[parameters('apiVersion')]",
      "sku": {
        "name": "[parameters('pricingTier')]"
      },
      "properties": {
        "ManagedResourceGroupId": "[concat(subscription().id, '/resourceGroups/', variables('managedResourceGroupName'))]",
        "encryption": {
          "entities": {
             "managedServices": {
                "keySource": "Microsoft.Keyvault",
                "keyVaultProperties": {
                   "keyVaultUri": "[parameters('keyvaultUri')]",
                   "keyName": "[parameters('keyName')]",
                   "keyVersion": "[parameters('keyVersion')]"
                }
             }
          }
        }
      }
    }
  ],
  "outputs": {
    "workspace": {
      "type": "object",
      "value": "[reference(resourceId('Microsoft.Databricks/workspaces', parameters('workspaceName')))]"
    }
  }
}

如果已使用另一个模板，可以将此模板的参数、资源和输出合并到现有模板中。

若要使用此模板创建或更新工作区，请选择以下部署选项之一：

使用 Azure CLI 应用模板
使用 Azure 门户应用模板

使用 Azure CLI 应用模板

若要使用 Azure CLI 创建新的工作区，请运行以下命令：

az deployment group create --resource-group <resource-group-name>  \
                           --template-file <file-name>.json \
                           --parameters workspaceName=<new-workspace-name> \
                           keyvaultUri=<keyvaultUrl> \
                           keyName=<keyName> keyVersion=<keyVersion>

注意

使用特定的密钥版本，而不是 latest。

若要使用 Azure CLI 更新现有工作区以使用客户管理的密钥工作区（或轮换现有密钥），请执行以下操作：

如果部署了工作区的 ARM 模板从未添加客户管理的密钥，请添加 resources.properties.encryption 部分及其相关参数。请参阅本文前面的模板。
1. 从模板添加 resources.properties.encryption 节。
2. 在 parameters 部分中，从模板添加三个新参数，keyvaultUri、keyName 和 keyVersion。
3. 在 parameters 部分中移除了模板中的 "type": "string",。
运行与用于创建新工作区相同的命令。只要资源组名称和工作区名称与现有工作区完全相同，此命令就会更新现有工作区，而不是创建新的工作区。
```
az deployment group create --resource-group <existing-resource-group-name>  \
                           --template-file <file-name>.json \
                           --parameters workspaceName=<existing-workspace-name> \
                           keyvaultUri=<keyvaultUrl> \
                           keyName=<keyName> keyVersion=<keyVersion>
```
除了密钥相关参数的更改之外，请使用用于创建工作区的相同参数。

重要

如果轮换密钥，则必须保留旧密钥 24 小时。

使用 Azure 门户应用模板

若要使用 Azure 门户中的模板创建或更新工作区：

转到自定义部署页。
单击“在编辑器中生成自己的模板”。
在 JSON 中粘贴。
单击“保存” 。
填写这些参数。

若要更新现有工作区，请使用与用于创建工作区相同的参数。若要首次添加密钥，请添加三个与密钥相关的参数。若要轮换密钥，请更改部分或全部密钥相关参数。确保资源组名称和工作区名称与现有工作区相同。如果它们相同，则此命令将更新现有工作区，而不是创建新的工作区。

除了密钥相关参数的更改之外，请使用用于创建工作区的相同参数。
单击“查看 + 创建”。
如果没有验证问题，请单击“创建”。

重要

如果轮换密钥，则必须保留旧密钥 24 小时。

有关更多详细信息，请参阅 Azure 文章快速入门：使用 Azure 门户创建和部署 ARM 模板。

步骤 4（可选）：重新导入笔记本

一开始为现有工作区的托管服务添加密钥后，只有未来的写入操作会使用该密钥。现有数据未重新加密。

可以导出所有笔记本，然后将其重新导入，以便加密数据的密钥受到密钥的保护和控制。可以使用导出和导入工作区 API。

稍后轮换密钥

如果已对托管服务使用客户管理的密钥，则可以使用新的密钥版本或全新密钥更新工作区。这称为密钥轮换。

在 Key Vault 中创建新密钥或轮换现有密钥。请参阅步骤 1：设置密钥保管库。

确保新密钥具有适当权限。
确认模板使用正确的 API 版本。版本必须为 2021-04-01-preview 或更高。
使用门户、CLI 或 PowerShell 使用新密钥更新工作区。请参阅步骤 3：向工作区添加密钥，并按照说明更新工作区。确保为资源组名称和工作区名称使用相同的值，以便它更新现有工作区，而不是创建新的工作区。除了密钥相关参数的更改之外，请使用用于创建工作区的相同参数。

重要

如果轮换密钥，则必须保留旧密钥 24 小时。
也可以导出和重新导入现有笔记本，以确保所有现有笔记本都使用新密钥。

疑难解答

意外删除密钥

如果在 Azure Key Vault 中删除密钥，则工作区登录就会开始失败，Azure Databricks 将无法读取任何笔记本。为避免出现这种情况，建议启用软删除。此选项可确保一个密钥被删除后，可以在 30 天内恢复。如果启用了软删除，只需重新启用密钥即可解决该问题。

密钥保管库权限问题导致密钥更新失败

如果在创建工作区时遇到问题，请检查密钥保管库是否具有正确的权限。从 Azure 返回的错误可能无法正确指明这是根本原因。此外，所需的权限为 get、wrapKey 和 unwrapKey。请参阅步骤 1：设置密钥保管库。

丢失的密钥不可恢复

如果丢失了密钥并且无法恢复它，则使用该密钥加密的所有笔记本数据都将无法恢复。

通过

为托管服务启用客户管理的密钥

要求

步骤 1：设置密钥保管库

使用 Azure 门户

使用 Azure CLI

使用 Azure PowerShell

步骤 2：准备密钥

使用 Azure CLI

使用 Azure PowerShell

步骤 3：将密钥添加到工作区

使用 Azure 门户（无模板）

使用 Azure CLI（无模板）

使用 Powershell（无模板）

使用 ARM 模板应用更改

使用 Azure CLI 应用模板

使用 Azure 门户应用模板

步骤 4（可选）：重新导入笔记本

稍后轮换密钥

疑难解答

意外删除密钥

密钥保管库权限问题导致密钥更新失败

丢失的密钥不可恢复

反馈

其他资源