啟用受控服務的客戶自控金鑰

發行項
01/23/2025

注意

若要進一步控制您的資料，您可以新增自己的金鑰，以保護並控制對某些資料類型的存取。 Azure Databricks 具有多個客戶自控金鑰功能。若要比較相關功能，請參閱適用於加密的客戶自控金鑰。

提示

這篇文章說明如何在 Azure Key Vault 保管庫中為受控服務設定您自己的金鑰。如需使用 Azure Key Vault 受控 HSM 中的金鑰的指示，請參閱啟用受控服務的 HSM 客戶自控金鑰。

Azure Databricks 控制平面中的受控服務資料會在待用時加密。您可以為受控服務新增客戶自控金鑰，以協助保護和控制對下列加密資料的存取：

Azure Databricks 控制平面中的筆記本來源。
儲存在控制平面中讓筆記本以互動方式執行 (而非作爲作業執行) 的筆記本結果。根據預設，較大的結果也會儲存在工作區根貯體中。您可以將 Azure Databricks 設定為將所有互動式筆記本結果儲存在雲端帳戶中。
秘密管理員 API 所儲存的秘密。
Databricks SQL 查詢和查詢歷史記錄。
個人存取令牌（PAT）或其他認證，用來設定 Git 與 Databricks Git 資料夾的整合。

為工作區新增客戶自控金鑰加密後，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：設定 Key Vault

您必須建立 Azure Key Vault 實例並設定其許可權。您可以透過 Azure 入口網站、CLI 或 API 來執行此操作。

重要

Key Vault 與 Azure Databricks 工作區必須位於相同的 Azure 租用戶中。

以下指示提供多個部署選項的詳細資料：

使用 Azure 入口網站
使用 Azure CLI
使用 Azure PowerShell

使用 Azure 入口網站

建立或選取金鑰保管庫：
- 若要建立 Key Vault，請移至建立 Key Vault 的 Azure 入口網站頁面。按一下 [+ 建立]。輸入資源群組名稱、Key Vault 名稱、區域和定價層。按一下 [檢閱 + 建立]，然後按一下 [建立]。
- 若要使用現有 Key Vault，請複製其 Key Vault 名稱以供下一個步驟使用。
取得 AzureDatabricks 應用程式的物件識別碼：
1. 在 Azure 入口網站中，前往 Microsoft Entra ID。
2. 從側邊欄功能表中選取 [企業應用程式]。
3. 搜尋 AzureDatabricks，然後在結果中按一下企業應用程式。
4. 從 [屬性] 中複製物件識別碼。
使用 Azure 入口網站，將存取原則新增至 Key Vault：
1. 瀏覽至您將用來為工作區的受控服務設定客戶自控金鑰的 Azure Key Vault。
2. 在左側面板中按一下 [存取原則] 索引標籤。
3. 請選擇頁面頂端的 [建立] 按鈕。
4. 在 [許可權] 索引標籤的 [密鑰許可權] 區段底下，啟用 [取得、解密密鑰，以及 加密密鑰]。
5. 按一下 [下一步] 。
6. 在 [主體] 索引標籤上，輸入 AzureDatabricks，然後滾動至應用程式 ID 為 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d 的第一個企業應用程式結果並選取它。
7. 繼續移至 [檢閱 + 建立] 索引標籤，然後按一下 b。

使用 Azure CLI

使用 Azure CLI 完成下列指示。

建立 Key Vault 或選取現有的 Key Vault：
- 若要建立 Key Vault，請使用下列 Azure CLI 命令，並將括弧中的項目取代為您的區域、Key Vault 名稱、資源群組名稱和位置：
```
az keyvault create --location <region> \
                   --name <key-vault-name> \
                   --resource-group <resource-group-name> \
                   --location <location> \
                   --enable-purge-protection
```
- 若要使用現有 Key Vault，請複製 Key Vault 名稱以供下一個步驟使用。

使用 Azure CLI 取得 AzureDatabricks 應用程式的物件識別碼。

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，或使用現有的 Key Vault。

建立 Key Vault：

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

使用現有的 Key Vault：

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

步驟 2：準備金鑰

您可以建立新的金鑰或使用現有金鑰。使用您偏好使用的任何工具：Azure 入口網站、Azure CLI 或其他工具。

使用 Azure CLI

在 Key Vault 下建立金鑰。金鑰類型必須是 RSA。

若要在 CLI 中建立金鑰，請執行此命令：

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

記下下列值，您可以從回應中 kid 屬性中的密鑰標識碼取得。您將在後續步驟中使用這些值。

Key Vault URL：包含 Key Vault 名稱之金鑰識別碼的開頭部分。其格式為 https://<key-vault-name>.vault.azure.net。
金鑰名稱：金鑰的名稱。
金鑰版本：金鑰的版本。

完整金鑰識別碼的格式通常為 https://<key-vault-name>.vault.azure.net/keys/<key-name>/<key-version>。非公用雲端中的 Azure Key Vault 金鑰具有不同的格式。

若要使用現有的金鑰，而不是建立金鑰，請取得並複製金鑰的這些值，讓您可以在後續步驟中使用它們。在繼續之前，請檢查以確認現有金鑰已啟用。

使用 Azure PowerShell

如果您打算建立金鑰，您可能需要根據建立金鑰的方式和時間來設定存取原則。例如，如果您最近使用 PowerShell 建立了 Key Vault，則新的 Key Vault 可能缺少建立金鑰所需的存取原則。下列範例會使用 EmailAddress 參數來設定原則。如需相關詳細資訊，請參閱 Microsoft 文章中有關 Set-AzKeyVaultAccessPolicy的內容。

在新的 Key Vault 上設定存取原則：
```
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>

在 Key Vault 中新增具有權限的存取原則：

$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 小工具中的 [建立]。
在 [Basics] 和 [網路] 索引標籤上輸入輸入欄位的值。
到達 [加密] 索引標籤之後：
- 若要建立工作區，請在 [受控服務] 區段中啟用 [使用您自己的金鑰]。
- 若要更新工作區，請啟用 [受控服務]。
設定加密欄位。
- 在 [密鑰標識子] 字段中，貼上 Azure Key Vault 金鑰的金鑰標識碼。
- 在 [訂用帳戶] 下拉式清單中，輸入 Azure Key Vault 金鑰的訂用帳戶名稱。
完成其餘索引標籤，然後按一下 [檢閱 + 建立] (適用於新的工作區) 或 [儲存] (適用於更新工作區)。

重要

如果您輪替金鑰，則必須保留舊的金鑰 24 小時。

在不使用範本的情况下使用 Azure CLI

使用下列命令，在 Key Vault 中新增存取原則。將 <key-vault-name> 取代為您在上一個步驟中使用的保存庫名稱，並將 <object-id> 取代為 AzureDatabricks 應用程式的物件識別碼。
```
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：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 範本會使用資源 2023-02-01 的 API 版本 Microsoft.Databricks/workspaces，透過客戶自控金鑰來建立新的工作區。在本機將此文字儲存至名為 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 入口網站中的範本來建立或更新工作區：

移至自訂部署頁面。
按一下 [Build your own template in the editor] $在編輯器中建置您自己的範本$。
在 JSON 編輯器中貼上。
按一下 [儲存]。
填入參數。

若要更新現有的工作區，請使用您用來建立工作區的相同參數。若要第一次新增索引鍵，請新增三個索引鍵相關參數。若要輪替金鑰，請變更部分或所有與金鑰相關的參數。請確定資源群組名稱和工作區名稱與您現有的工作區相同。如果相同，此命令會更新現有工作區，而不是建立新的工作區。

除了金鑰相關參數的變更以外，請使用用於建立工作區的相同參數。
按一下 [檢閱 + 建立]。
如果沒有驗證問題，請按一下 [建立]。

重要

如果您輪替金鑰，則必須保留舊的金鑰 24 小時。

如需詳細資訊，請參閱 Azure 文章快速入門：使用 Azure 入口網站建立及部署 ARM 範本。

步驟 4 (選用)：重新匯入筆記本

最初為現有工作區的受控服務新增金鑰後，只有未來的寫入作業才會使用您的金鑰。現有資料不會被重新加密。

您可以匯出所有筆記本，然後重新匯入這些筆記本，以便透過您的金鑰保護和控制用來加密資料的金鑰。您可以使用匯出和匯入工作區 API。

在稍後的時間輪替金鑰

如果您已經針對受控服務使用客戶管理的金鑰，您可以使用新的金鑰版本或全新的金鑰來更新工作區。這稱為「金鑰輪替」。

在 Key Vault 中建立新的金鑰或輪替現有金鑰。請參閱步驟 1：設定 Key Vault。

請確定新的金鑰具有適當權限。
確認您的 ARM 範本使用正確的 API 版本。該值必須大於或等於 2021-04-01-preview。
使用入口網站、CLI 或 PowerShell 以新金鑰更新工作區。請參閱步驟 3：將密鑰新增至工作區，並遵循工作區更新的指示。請確定您針對資源組名和工作區名稱使用相同的值，以便更新現有的工作區，而不是建立新的工作區。除了金鑰相關參數的變更以外，請使用用於建立工作區的相同參數。

重要

如果您輪替金鑰，則必須保留舊的金鑰 24 小時。
或者，匯出並重新匯入現有筆記本，以確保所有現有的筆記本都使用新的金鑰。

疑難排解

意外刪除金鑰

如果您在 Azure Key Vault 中刪除金鑰，工作區登入將會開始失敗，且 Azure Databricks 無法讀取筆記本。若要避免這種情況，建議您啟用虛刪除。此選項可確保金鑰遭到刪除時，可於為期 30 天內加以復原。如果已啟用虛刪除，便可以直接重新啟用金鑰以解決問題。

密鑰更新無法成功，因為 Key Vault 權限問題

如果您在建立工作區時遇到問題，請檢查 Key Vault 是否有正確的權限。從 Azure 傳回的錯誤可能無法正確指出這是根本原因。此外，所需的權限包括 get、wrapKey 和 unwrapKey。請參閱步驟 1：設定 Key Vault。

遺失的金鑰無法復原

如果您遺失金鑰且無法加以復原，則會無法復原以該金鑰加密的所有筆記本資料。

共用方式為

啟用受控服務的客戶自控金鑰

需求

步驟 1：設定 Key Vault

使用 Azure 入口網站

使用 Azure CLI

使用 Azure PowerShell

步驟 2：準備金鑰

使用 Azure CLI

使用 Azure PowerShell

步驟 3：在工作區中新增金鑰

在不使用範本的情况下使用 Azure 入口網站

在不使用範本的情况下使用 Azure CLI

在不使用範本的情况下使用 PowerShell

使用 ARM 範本套用變更

將範本套用至 Azure CLI

將範本套用至 Azure 入口網站

步驟 4 (選用)：重新匯入筆記本

在稍後的時間輪替金鑰

疑難排解

意外刪除金鑰

密鑰更新無法成功，因為 Key Vault 權限問題

遺失的金鑰無法復原

意見反應

其他資源