Important
這項功能位於 測試版 (Beta) 中。
讓 Unity Catalog 結構描述使用 Azure Key Vault,讓你在筆記本、工作和 UDF 中使用 Azure Key Vault 的祕密,而不必複製它們。 這些值會保留在 金鑰保存庫,Unity Catalog 的權限則控制誰可以讀取或使用每個密碼。
與 Azure Key Vault 支援的保密範圍(將整個 Vault 暴露於一個工作區)不同,金鑰保存庫 支援的 Unity Catalog 結構描述可在每個連接到元商店的工作區中取得,並分別授予每個秘密的存取權限。
若要比較外部秘密與 Azure Databricks 管理的秘密及工作空間秘密範圍,請參閱選擇存放秘密的位置。
外部秘密的運作原理
結構描述由一個與您的雲端秘密管理器建立的連線作為後盾。 兩個獨立控制單位決定誰可以使用密鑰。 秘密管理器中的服務憑證權限決定 Unity 目錄可以匯入和讀取哪些秘密,而 Unity 目錄的權限則決定哪些主體可以使用這些秘密。
在你備份結構描述後,外部 Secrets 的行為如下:
- 每次讀取都會取得目前的值:你在秘密管理器中輪換的值會在下一次讀取時生效,而無需變更 Azure Databricks。 已經持有某個值的程式碼會保留該值,直到再次讀取祕密。 取回的值可能會如同其他機密資料一樣,快取在發出要求的運算資源上。
- 在 Secret Manager 中管理秘密:在那裡建立、更新、輪換和刪除秘密。 它們在 Unity Catalog 中是唯讀的。 當你在祕密管理器中永久刪除某個祕密時,Azure Databricks 會移除 Unity Catalog 的祕密,包括它的權限和標籤。
- 列出會匯入的新密碼:列出結構描述會啟動非同步匯入。 新增至或從密碼管理員移除的密碼,會在之後再次列出清單時才顯示於 Unity Catalog 中;對大型秘密儲存區而言,這可能需要幾分鐘。 你可以在密鑰出現在列表中之前,先依名稱讀取它。
- 審計日誌會記錄雙方:Unity Catalog 的審計日誌會記錄讀取密碼的 Azure Databricks 主體身分。 雲端日誌將存取權歸因於服務憑證。
需求規格
- 符合 Unity Catalog 密碼的要求。
- 您的工作區必須啟用外部密鑰 Beta 版。 請參閱 管理 Azure Databricks 預覽。
- 你需要一個 Unity Catalog 服務認證,以及一個使用它來向你的祕密管理服務進行驗證的 Unity Catalog 連線。 請參閱 建立服務憑證 與 建立連線。
- 若要備份結構描述,你需要目錄上的
USE CATALOG、結構描述的擁有權或其上的MANAGE,以及連線上的USE CONNECTION。 結構描述中不能包含任何 Azure Databricks 管理的密碼,所以在備份前請刪除任何密碼。
設定外部機密
建立服務憑證
連線會使用 Unity Catalog 服務憑證向你的秘密管理器進行驗證。
- 建立由受控識別或服務主體支援的服務憑證,詳見建立服務憑證。
- 授權身分識別在 金鑰保存庫 中列出並讀取祕密。 例如,指派 金鑰保存庫 Secrets 使用者角色,或具備取得及列出秘密權限的存取原則。
建立連結
建立一個使用服務認證並指向你的秘密管理器的 Unity Catalog 連線。 你需要在 metastore 上具備 CREATE CONNECTION。
目錄檢視器
- 在 Catalog Explorer 中,點選 + 選單並選擇 建立連線。
- 輸入一個連線名稱,並選擇 Azure Key Vault 連線類型。
- 選擇服務憑證,並設定你的 金鑰保存庫 保存庫名稱。
- 點擊 建立。
Databricks 命令行介面
要建立連線,請執行下列內容。 設定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 會先依建立日期匯入最舊的項目,並跳過其餘項目。 只在每個結構描述中揭露你需要的密鑰。 請參閱依需求者將密碼分組。
Limitations
除了 所有 Unity 目錄秘密的限制外,外部備份的秘密還有以下限制:
- 不支援跨雲端存取:請使用工作空間所在雲端原生的祕密管理器作為結構描述的後端。
- 讀取延遲與成本:每次讀取都會從外部秘密管理器取得數值,這會增加延遲並可能產生雲端服務提供者的成本。
- 無標籤過濾:Azure Key Vault 不支援依標籤過濾匯入的秘密。
Note
如果支撐結構的外部秘密管理器與讀取該架構的元儲存庫或工作區處於不同區域,秘密值及其元資料會跨越區域。 Azure Databricks 並不保證外部秘密能在區域內處理。
外部秘密名稱和值可能包含個人資料。 除非你的使用情境需要,否則你有責任將個人資料排除在外。
其他資源
| 資源 | Description |
|---|---|
| Unity Catalog 密鑰的最佳實務 | 依環境、應用程式或團隊來整理機密,讓工作負載使用機密而無須檢視其內容。 |
| Unity 目錄中的秘密 | 建立、授予並讀取 Unity Catalog 的祕密。 |