為 Databricks Unity Catalog 設定跨雲端連線

透過跨雲端連線，連至 Amazon Web Services (AWS)、Microsoft Azure 或 Google Cloud 上的 Databricks Unity Catalog，即可直接在 Google Cloud中查詢該目錄的資料。這項功能可將外部資料來源與現有Google Cloud 環境整合，統一資料分析作業。

設定連線後，您可以在無邊界 Lakehouse 中管理聯合資料的存取權。

事前準備

1. 請參閱「Lakehouse 總覽」，瞭解 Lakehouse 如何管理資料存取權。
2. 請參閱這篇文章，瞭解如何存取跨雲端資料。
3. 請查看支援的目錄，確認支援的設定。
4. 瞭解如何使用區域性 Secret Manager 密鑰。如要使用密鑰驗證機制，透過 Databricks Unity Catalog 設定 Lakehouse，就必須提供這項資訊。
5. 選用：如果您打算透過 Google Cloud虛擬私有雲 (VPC) 網路和遠端雲端網路 (AWS VPC 或 Azure VNet) 之間的私人互連網路，轉送查詢讀取或背景中繼資料重新整理作業，請確認您在遠端供應商擁有有效帳戶、佈建專用 Cross-Cloud Interconnect 或合作夥伴 Cross-Cloud Interconnect、與 Cloud Router 建立 BGP 工作階段，並確認您在兩個雲端環境中都具備必要的 Identity and Access Management (IAM) 權限。
6. 選用：如果您打算使用使用者身分聯盟，在查詢中傳播使用者身分，請確認：
   • 您的識別資訊提供者 (IdP) 已設為在驗證權杖中，將使用者的 email 附加資訊做為 sub 主體附加資訊核發。
   • Databricks 帳戶已設為根據電子郵件地址辨識使用者，因此 Databricks 可以辨識使用者。如要在 Databricks 中設定使用者，您可以使用 SCIM 從識別資訊提供者同步處理使用者 (建議做法)，或在 Databricks 帳戶控制台中手動新增使用者。
登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake, Secret Manager APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake, Secret Manager APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

必要的角色

如要取得設定跨雲端存取權所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• 管理 Lakehouse 目錄：BigLake 管理員 (roles/biglake.admin)
• 管理密鑰 (如果使用密鑰驗證)：Secret Manager 管理員 (roles/secretmanager.admin)
• 透過私人互連網路轉送流量 (使用者)：Compute 網路管理員 (roles/compute.networkAdmin)
• 透過專屬互連網路轉送流量 (目錄服務帳戶)：
  • Service Directory 檢視者 (roles/servicedirectory.viewer)
  • Service Directory PSC 授權服務 (roles/servicedirectory.pscAuthorizedService)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

注意： 如果使用密鑰驗證，為遵循最小權限原則，並避免授予專案中所有密鑰的存取權，請要求 Secret Manager 管理員為您建立密鑰，並授予您僅修改 Lakehouse 特定密鑰的權限。

限制和注意事項

本節列出存取跨雲端資料的限制和注意事項。

• VPC Service Controls：如果含有聯合目錄端點或基礎 Cloud Storage bucket 的專案位於 VPC Service Controls 服務範圍內，則必須設定輸出或輸入規則。詳情請參閱「搭配使用 VPC Service Controls 與聯合目錄端點」。
• Cross-Cloud Interconnect 支援的雲端服務供應商：AWS 和 Azure 支援使用私人互連網路轉送查詢傳輸、背景中繼資料重新整理，或兩者。您可以使用專屬 Cross-Cloud Interconnect (適用於 AWS 或 Azure) 或合作夥伴 Cross-Cloud Interconnect。
• 網路轉送：如果您未設定私人互連網路來傳輸查詢或重新整理背景中繼資料，系統會使用 TLS 透過公開網際網路轉送相應流量。如果透過公開網際網路轉送查詢讀取作業，遠端雲端服務供應商可能會收取較高的輸出費用，且效能較難預測。
• Databricks Unity Catalog 設定：
  • 僅支援使用 AWS 外部位置、Azure 外部位置或 Google Cloud外部位置的 Databricks Unity Catalog。不支援使用 AWS 預設儲存空間、Azure 預設儲存空間或 Google Cloud預設儲存空間的 Unity Catalog。
  • 您必須在 Unity Catalog 使用的 metastore 上啟用外部資料存取權，這項功能預設為停用。
  • 您必須將目標結構定義或目錄的 EXTERNAL USE SCHEMA 權限授予 Databricks 服務主體，才能啟用外部資料存取的憑證販售功能。如果沒有這項權限，背景中繼資料重新整理和查詢憑證販售作業就會失敗。
• 唯讀：Lakehouse 中的聯合目錄是遠端目錄的唯讀檢視畫面。不支援資源操作 (例如建立、更新或刪除資源)，必須直接在遠端目錄中執行。
• 資料更新間隔：聯合目錄的 --refresh-interval 旗標會決定中繼資料的同步頻率。這個值必須是 0s (停用) 或至少 300s (5 分鐘)。目錄的背景中繼資料重新整理作業可能需要較長的時間，具體取決於命名空間和資料表資源的數量。如果前一次重新整理作業逾時，系統會略過目前的重新整理作業，並排定在下一個間隔時間執行。查詢會使用最近同步處理的目錄中繼資料，因此在遠端目錄中所做的變更 (例如新資料表、結構定義更新或新提交的資料)，要等到下次背景中繼資料重新整理完成後，才會顯示在 Lakehouse 中。
• Lakehouse 快取：跨雲端快取預設為停用 (--cross-cloud-cache=disabled)。您可以在聯合目錄或連結層級啟用或停用快取。快取不支援客戶自行管理的加密金鑰 (CMEK)；快取檔案會使用 Google-owned and Google-managed encryption keys加密。如果查詢中的資料表強制執行 constraints/gcp.restrictNonCmekServices 組織政策限制，系統會自動停用該查詢的快取功能。詳情請參閱「智慧型快取」。
• 資料落地和法規遵循：在聯合目錄或連線上啟用跨雲端快取功能時，Lakehouse 會將快取的靜態檔案暫時儲存在 Google Cloud 執行查詢的區域。如果遠端雲端檔案位於不同的管轄區，請先確認跨區域快取符合貴組織的資料落地和法規遵循要求，再啟用這項功能。

一般工作流程

如要存取跨雲端資料，請按照下列一般步驟操作：

• 設定 Cross-Cloud Interconnect (選用)：設定 Google Cloud 虛擬私有雲網路與遠端雲端服務供應商之間的私人連線。
• 設定聯合：設定驗證機制，並在 Lakehouse 建立聯合目錄。
  • 基本驗證 (必要)：設定 OpenID Connect (OIDC) (建議) 或密鑰驗證，允許 Lakehouse 使用目錄的服務帳戶執行背景中繼資料重新整理。
  • 使用者身分聯盟 (選用)：啟用使用者身分聯盟 (--federated-catalog-identity-mode="user-identity-federation")，允許使用已驗證的使用者身分執行查詢。這樣一來，Databricks Unity Catalog 就能將查詢歸因於使用者、強制執行權限，以及產生稽核記錄。
• 驗證連線：確認 Lakehouse 可連線至遠端目錄。
• 查詢資料：使用 BigQuery 或 Managed Service for Apache Spark，對聯合資料執行查詢。您也可以在聯合目錄啟用跨雲端快取，降低跨雲端輸出費用，並加快後續查詢速度。詳情請參閱「查詢遠端資料」。
• 設定權限：使用 IAM 管理可查看及查詢聯合資料的人員。

設定 Cross-Cloud Interconnect (選用)

根據預設，查詢資料讀取和背景中繼資料重新整理作業，都會透過公開網際網路使用 TLS 傳輸。為強化網路隔離、提供可預測的延遲時間，並降低資料移轉費用，您可以在 Google Cloud虛擬私有雲網路和遠端雲端網路 (AWS 虛擬私有雲或 Azure 虛擬網路 (VNet)) 之間設定私人互連網路。

您可以佈建下列任一私人互連網路選項：

• 專用 Cross-Cloud Interconnect：與 AWS 或 Azure 之間的專用實體連線。
• 合作夥伴 Cross-Cloud Interconnect：透過支援的服務供應商連線至 AWS。

在 Google Cloud中的 Cloud Router 和遠端雲端網路之間建立 BGP 工作階段，以便交換路徑。

您可以根據安全性和成本需求，為下列其中一項或兩項流量路徑，設定透過 Cross-Cloud Interconnect 的私人轉送：

• 查詢傳輸 (--service-directory-name)：將 BigQuery 或開放原始碼引擎的查詢讀取作業，轉送至遠端物件儲存庫 (Amazon S3 或 Azure Data Lake Storage Gen2 (ADLS Gen2))，降低跨雲端輸出費用，並確保查詢延遲時間可預測。
• 背景中繼資料重新整理 (--metadata-service-directory-name)：將 Lakehouse 執行階段目錄的控制層背景中繼資料重新整理和驗證要求，轉送至遠端 Databricks Unity Catalog 私人端點，例如遠端目錄限制公開網路連線能力時。

如果您透過 Cross-Cloud Interconnect 轉送查詢傳輸和背景中繼資料重新整理作業，請分別為遠端儲存空間端點和遠端目錄端點，完成私人端點、轉送和 Service Directory 服務步驟。這兩項 Service Directory 服務必須與聯合目錄位於相同的 Google Cloud 區域，且可共用相同的僅限 Proxy 子網路和 Service Directory 命名空間。

您可以使用下列任一架構流程，將流量從 Service Directory 轉送至遠端私人端點：

• 內部區域性 Proxy 網路負載平衡器轉送：使用 Google Cloud內部區域性 Proxy 網路負載平衡器，將要求分配至混合式連線網路端點群組 (NEG)，這些群組會指向遠端私人端點 IP 位址 (AWS 彈性網路介面 (ENI) 或 Azure 私人端點網路介面 (NIC))。合作夥伴 Cross-Cloud Interconnect 必須採用這個流程，而專屬 Cross-Cloud Interconnect 則建議採用這個流程，以利負載平衡、擴充性和高可用性。
• 直接端點轉送：將 Service Directory 直接連結至單一遠端私人端點 IP 位址。這項流程僅適用於專屬 Cross-Cloud Interconnect，不支援合作夥伴 Cross-Cloud Interconnect。

請根據架構需求，選取相應的設定流程：

內部區域性 Proxy 網路負載平衡器

如要設定內部區域性 Proxy 網路負載平衡器，將要求分配至遠端私人端點 IP 位址，請按照下列步驟操作：

設定遠端雲端私人端點

在遠端網路和子網路中建立私人端點，並透過 Cross-Cloud Interconnect 連線至 Google Cloud 虛擬私有雲網路，然後記下指派給各端點的私人 IP 位址：

• 私人查詢傳輸 (遠端物件儲存庫)：在 AWS 上，於 AWS VPC 中建立 Amazon S3 的介面 VPC 端點 (com.amazonaws.AWS_REGION.s3)，並記下 ENI 私人 IP 位址。在 Azure 上，建立適用於 Azure 儲存體的 Azure 私人端點，並指定 Azure VNet 中的 ADLS Gen2 儲存體帳戶 (dfs 或 blob)，然後記下 NIC 私人 IP 位址。
• 如要私人背景中繼資料重新整理 (遠端目錄)： 在 AWS 上，於 AWS VPC 中為 Databricks 工作區設定 AWS PrivateLink 介面端點，並記下 ENI 私人 IP 位址。在 Azure 上，於 Azure VNet 中建立指定 Azure Databricks 工作區的 Azure 私人端點，並記下 NIC 私人 IP 位址。
• 傳入安全性規則：確認附加至私人端點的 AWS 安全性群組或 Azure 網路安全性群組 (NSG)，允許來自 Google Cloud 虛擬私有雲 CIDR 範圍的通訊埠 443 傳入 TCP 流量。請加入 Google Cloud 僅限 Proxy 子網路的 CIDR 範圍，允許健康狀態檢查和轉送的流量。

設定 Google Cloud 網路

重要事項： 您必須在 Cross-Cloud Interconnect VLAN 連結所在的區域，部署本節中的所有 Google Cloud 資源 (健康狀態檢查、混合式 NEG、後端服務和負載平衡器)。如果兩者位於不同區域，流量就無法轉送至遠端端點。

執行下列指令，設定內部負載平衡器。如果您透過 Cross-Cloud Interconnect 轉送查詢傳輸和背景中繼資料重新整理，請為儲存空間端點和目錄端點設定個別的後端服務、目標 TCP Proxy 和轉送規則。如需進階設定，請參閱「為混合式端點設定內部區域性 Proxy 網路負載平衡器」。

注意： 開始之前，請確認您已在該區域的虛擬私有雲網路中，設定僅限 Proxy 的子網路。如果沒有，請建立一個：

gcloud compute networks subnets create PROXY_SUBNET_NAME \
    --purpose=REGIONAL_MANAGED_PROXY \
    --role=ACTIVE \
    --region=REGION \
    --network=VPC_NETWORK \
    --range=PROXY_SUBNET_RANGE

更改下列內容：

• PROXY_SUBNET_NAME：僅限 Proxy 子網路的名稱。
• PROXY_SUBNET_RANGE：虛擬私有雲網路中未使用的 CIDR 範圍 (例如 10.129.0.0/23)。

重要事項： Cloud Router 不會使用 BGP 自動 advertise 僅限 Proxy 子網路。您必須手動設定 Cloud Router，使用自訂路由 advertising 向遠端網路 advertise PROXY_SUBNET_RANGE，這樣遠端端點的回應流量才能路由回負載平衡器。

1. 建立區域性 TCP 健康狀態檢查：

   gcloud compute health-checks create tcp HEALTH_CHECK_NAME \
       --region=REGION \
       --port=443

   更改下列內容：

   • HEALTH_CHECK_NAME：健康狀態檢查的名稱。
   • REGION： Google Cloud 區域 (例如 us-east4)。

2. 建立混合式連線網路端點群組 (NEG) 並新增端點：

   為每個可用區建立混合式 NEG (NON_GCP_PRIVATE_IP_PORT)：

   gcloud compute network-endpoint-groups create NEG_NAME \
       --network-endpoint-type=NON_GCP_PRIVATE_IP_PORT \
       --zone=ZONE \
       --network=VPC_NETWORK

   將遠端端點 ENI 或 NIC 的私人 IP 位址新增至混合式 NEG：

   gcloud compute network-endpoint-groups update NEG_NAME \
       --zone=ZONE \
       --add-endpoint="ip=REMOTE_ENDPOINT_IP,port=443"

   更改下列內容：

   • NEG_NAME：混合式 NEG 的名稱。
   • ZONE： Google Cloud 可用區 (例如 us-east4-a)。這個可用區必須位於 Cross-Cloud Interconnect VLAN 連結的區域內。
   • VPC_NETWORK：虛擬私有雲網路的名稱。
   • REMOTE_ENDPOINT_IP：該可用區中遠端儲存空間或遠端目錄私人端點的私人 IP 位址。

   如果遠端端點有多個私人 IP 位址，且分布在不同可用區，請重複執行這些指令，建立混合型 NEG 並為每個可用區新增端點。

3. 建立及設定後端服務：

   建立具備內部代管負載平衡功能的區域性後端服務：

   gcloud compute backend-services create BACKEND_SERVICE_NAME \
       --load-balancing-scheme=INTERNAL_MANAGED \
       --protocol=TCP \
       --region=REGION \
       --health-checks=HEALTH_CHECK_NAME \
       --health-checks-region=REGION

   將混合型 NEG 新增至後端服務：

   gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
       --region=REGION \
       --network-endpoint-group=NEG_NAME \
       --network-endpoint-group-zone=ZONE \
       --balancing-mode=CONNECTION \
       --max-connections=MAX_CONNECTIONS

   更改下列內容：

   • BACKEND_SERVICE_NAME：後端服務的名稱。
   • NEG_NAME：您在上一個步驟中建立的混合型 NEG 名稱。
   • ZONE： Google Cloud 可用區 (例如 us-east4-a)。
   • MAX_CONNECTIONS：後端的並行連線數量上限 (例如 100)。

   針對您建立的每個混合式 NEG，重複執行 add-backend 指令。

4. 設定負載平衡器前端：

   建立目標 TCP Proxy：

   gcloud compute target-tcp-proxies create TARGET_PROXY_NAME \
       --backend-service=BACKEND_SERVICE_NAME \
       --region=REGION

   建立轉送規則，將流量轉送至目標 Proxy：

   gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
       --load-balancing-scheme=INTERNAL_MANAGED \
       --network=VPC_NETWORK \
       --subnet=VPC_SUBNET \
       --ports=443 \
       --region=REGION \
       --target-tcp-proxy=TARGET_PROXY_NAME \
       --target-tcp-proxy-region=REGION \
       --allow-global-access

   更改下列內容：

   • TARGET_PROXY_NAME：目標 Proxy 的名稱。
   • FORWARDING_RULE_NAME：轉送規則的名稱。
   • VPC_SUBNET：虛擬私有雲子網路的名稱。

為負載平衡器建立轉送規則後，請記下指派給該規則的內部 IP 位址。這是您的ILB_IP_ADDRESS。

設定 Service Directory

在 Service Directory 中註冊內部負載平衡器的 IP 位址，讓 Lakehouse 能透過私人管道探索及轉送至該位址。如果您為查詢傳輸和背景中繼資料重新整理設定了不同的負載平衡器轉送規則，請為每個轉送規則 IP 位址建立不同的 Service Directory 服務和端點。

1. 為遠端私人端點建立命名空間：

   gcloud service-directory namespaces create NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   更改下列內容：

   • NAMESPACE：命名空間的專屬 ID。
   • PROJECT_ID：您的 Google Cloud 專案 ID。
   • REGION： Google Cloud 區域 (例如 us-east4)。這必須與聯合目錄的區域相同。

2. 在 Service Directory 命名空間中建立服務：

   gcloud service-directory services create SERVICE_NAME \
       --namespace=NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   更改下列內容：

   • SERVICE_NAME：服務的專屬 ID (註冊背景中繼資料重新整理端點時，請建立獨立的服務名稱，例如 METADATA_SERVICE_NAME)。

3. 在服務中為負載平衡器轉送規則建立端點：

   gcloud service-directory endpoints create ENDPOINT_NAME \
       --project=PROJECT_ID \
       --namespace=NAMESPACE \
       --service=SERVICE_NAME \
       --location=REGION \
       --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK \
       --address=ILB_IP_ADDRESS \
       --port=443

   更改下列內容：

   • ENDPOINT_NAME：端點的專屬 ID。
   • PROJECT_NUMBER：您的 Google Cloud專案編號。在 --network 旗標中使用專案編號。
   • ILB_IP_ADDRESS：負載平衡器轉送規則的內部 IP 位址。

直接端點

如要設定 Service Directory，透過專屬 Cross-Cloud Interconnect 將流量直接轉送至單一遠端私人端點 IP 位址，請按照下列步驟操作：

1. 在遠端雲端網路中建立私人端點：

   • 如要使用私人查詢傳輸： 請在 AWS 虛擬私有雲中建立 Amazon S3 的介面虛擬私有雲端點，或在 Azure VNet 中建立 Azure Storage 的 Azure 私人端點 (dfs 或 blob)。
   • 如要進行私人背景中繼資料重新整理： 請在 AWS VPC 中為 Databricks 工作區建立 AWS PrivateLink 介面端點，或在 Azure VNet 中建立指定 Azure Databricks 工作區的 Azure 私人端點。

   請記下每個端點的私人 IP 位址和通訊埠 (443)，並確認 AWS 安全性群組或 Azure NSG 允許來自 Google Cloud 虛擬私有雲網路的傳入 TCP 流量，透過通訊埠 443 傳輸。

2. 為遠端私人端點建立命名空間：

   gcloud service-directory namespaces create NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   更改下列內容：

   • NAMESPACE：命名空間的專屬 ID。
   • PROJECT_ID：您的 Google Cloud 專案 ID。
   • REGION： Google Cloud 區域 (例如 us-east4)。這必須與聯合目錄的區域相同。

3. 在 Service Directory 命名空間中建立服務 (如果您要透過私人連線轉送查詢傳輸和背景中繼資料重新整理，請為每個端點建立個別服務)：

   gcloud service-directory services create SERVICE_NAME \
       --namespace=NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   更改下列內容：

   • SERVICE_NAME：服務的專屬 ID (註冊背景中繼資料重新整理端點時，請建立獨立的服務名稱，例如 METADATA_SERVICE_NAME)。

4. 使用遠端私人端點的私人 IP 位址和通訊埠，在服務中建立端點：

   gcloud service-directory endpoints create ENDPOINT_NAME \
       --service=SERVICE_NAME \
       --namespace=NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION \
       --address=REMOTE_ENDPOINT_IP \
       --port=REMOTE_ENDPOINT_PORT \
       --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK

   更改下列內容：

   • ENDPOINT_NAME：端點的專屬 ID。
   • REMOTE_ENDPOINT_IP：遠端儲存空間或遠端目錄私人端點的私人 IP 位址 (例如 10.0.1.45)。
   • REMOTE_ENDPOINT_PORT：遠端私人端點的通訊埠編號 (例如 443)。
   • PROJECT_NUMBER：您的 Google Cloud專案編號。在 --network 旗標中使用專案編號。
   • VPC_NETWORK：與私人互連網路相關聯的 Google Cloud虛擬私有雲網路名稱。

設定聯盟

如要查詢資料，您必須設定 Lakehouse 聯合目錄，並連結至遠端 Databricks Unity Catalog。

設定驗證機制

如要使用聯盟功能，必須以 Databricks 服務主體的身分，向目標目錄進行驗證。選擇下列其中一種驗證選項：

OIDC

OpenID Connect (OIDC) 可讓您透過 Databricks OAuth 權杖聯盟設定無密鑰驗證。

1. 在 Databricks 帳戶中建立服務主體，並授予 EXTERNAL USE SCHEMA 權限，使其具備目標 Databricks Unity Catalog 及其資源的讀取權限。
2. 儲存服務主體的應用程式 ID (UUID)。後續步驟會用到。

Secret-based

這個選項會使用 OAuth 用戶端 ID 和用戶端密鑰，並以區域 Secret Manager 密鑰安全儲存。

1. 在 Databricks 帳戶中建立服務主體，並授予 EXTERNAL USE SCHEMA 權限，使其具備目標 Databricks Unity Catalog 及其資源的讀取權限。

2. 為服務主體產生 OAuth 密鑰。

3. 建立名為 credentials.json 的 JSON 檔案，並加入酬載：

   {
       "client_id": "CLIENT_ID",
       "client_secret": "CLIENT_SECRET"
   }

   更改下列內容：

   • CLIENT_ID：Databricks 服務主體的 OAuth 用戶端 ID。
   • CLIENT_SECRET：Databricks 服務主體的 OAuth 用戶端密鑰。

4. 設定 Secret Manager 的區域端點：

   Secret Manager 預設會使用全域端點。不過，Lakehouse 要求密鑰必須儲存在與 Lakehouse 目錄相同的區域。如要使用 Google Cloud CLI 與區域性密鑰互動，您必須覆寫目前工作階段或設定檔的預設 API 端點。例如：secretmanager.us-east4.rep.googleapis.com。

   gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/

   更改下列內容：

   • REGION：儲存 Secret Manager 密鑰的 Google Cloud 區域。例如：us-east4。為避免連線能力問題，請務必在相同區域建立 Secret 和目錄。

5. 將酬載上傳至 Secret Manager：

   gcloud secrets create DATABRICKS_SECRET_NAME \
     --location="REGION" \
     --project="PROJECT_ID" \
     --data-file=credentials.json

   更改下列內容：

   • DATABRICKS_SECRET_NAME： Databricks 密鑰的名稱。
   • PROJECT_ID：您的 Google Cloud 專案 ID。

建立聯合目錄

使用 Google Cloud 控制台或 gcloud CLI 建立聯合目錄。

注意事項：

• 僅支援使用 AWS 外部位置、Azure 外部位置或 Google Cloud外部位置的 Databricks Unity Catalog。不支援使用 AWS 預設儲存空間、Azure 預設儲存空間或 Google Cloud預設儲存空間的 Databricks Unity 目錄。

• 您必須在 Unity Catalog 使用的中繼存放區啟用外部資料存取權，這項功能預設為停用。

• 您必須將目標目錄及其資源的 EXTERNAL USE SCHEMA 權限授予 Databricks 服務主體，才能啟用憑證販售功能，以便存取外部資料。如果沒有這項權限，背景中繼資料重新整理和查詢憑證販售作業將會失敗。

控制台

如何建立聯合目錄：

1. 前往 Google Cloud 控制台的「Lakehouse」Lakehouse。

   前往 Lakehouse

2. 按一下「 建立目錄」。

3. 按一下「聯合目錄」。

   「Catalog configuration」(目錄設定) 區段隨即顯示。

4. 在「Federated catalog source」(聯合目錄來源) 部分，選取「Databricks (Unity)」。

5. 在「Data location」(資料位置) 部分，選取要建立聯合目錄的 Lakehouse 區域。例如：us-east4。如要盡可能縮短延遲時間 (即使是透過公開網際網路)，請在選取區域時執行下列操作：

   • 如果 Unity Catalog 位於 AWS，請選取最靠近 AWS 區域的Google Cloud 區域。
   • 如果 Unity Catalog 位於 Azure，請選取最接近 Azure 區域的Google Cloud 區域。
   • 如果 Unity Catalog 位於 Google Cloud，請選取完全相同的區域。

6. 選用：在「Cross-cloud caching」(跨雲端快取) 下方，選取「Enable cross-cloud caching」(啟用跨雲端快取)，將遠端檔案快取至目錄的 Google Cloud區域，並加快查詢效能。日後也可以編輯目錄詳細資料，更新這項設定。如要進一步瞭解快取運作方式、保留和定價，請參閱「智慧型快取」。

7. 按一下「繼續」。

   「Connection details」(連線詳細資料) 區段隨即顯示。

8. 在「Remote catalog details」(遠端目錄詳細資料) 區段的「Unity instance name」(Unity 執行個體名稱) 欄位中，輸入目標 Databricks 工作區主機名稱 (例如 AWS 上的 abcd.cloud.databricks.com 或 Azure 上的 adb-1234567890123456.7.azuredatabricks.net)。

9. 在「Unity catalog name」(Unity Catalog 名稱) 欄位中，輸入要聯合的目標目錄名稱。

10. 選取「Authentication Method」(驗證方式) 選項：

    • 在「OIDC」OIDC部分，輸入服務主體的應用程式 ID。
    • 在「Secret」(密鑰) 中輸入密鑰名稱。請使用下列格式：projects/PROJECT_ID/locations/REGION/secrets/DATABRICKS_SECRET_NAME。

11. 選用步驟：在「Identity mode」(身分模式) 部分，選取下列其中一個選項：

    • 服務身分 (預設)：以 Lakehouse 服務帳戶的身分執行查詢。
    • 使用者身分：查詢會使用已驗證的使用者身分執行，並傳播至目標目錄。目標目錄中必須設定身分聯盟。

12. 在「Transport layer」(傳輸層) 下方，選取「Public internet」(公開網際網路) 或「Dedicated private interconnect」(專屬私人互連網路)。如果選取「Dedicated private interconnect」(專屬私人互連網路)，請設定下列欄位：

    • 在「Service directory name」(服務目錄名稱) 欄位中，按照 projects/PROJECT_ID/locations/REGION/namespaces/SERVICE_DIRECTORY_NAMESPACE/services/SERVICE_NAME 格式輸入傳輸 Service Directory 服務的目錄服務路徑。
    • 選用：如要透過 Cross-Cloud Interconnect 私下同步處理目錄中繼資料，請在「Metadata service directory name」(中繼資料 Service Directory 名稱) 欄位中，輸入中繼資料 Service Directory 服務的路徑，格式為 projects/PROJECT_ID/locations/REGION/namespaces/METADATA_SERVICE_DIRECTORY_NAMESPACE/services/METADATA_SERVICE_NAME。

13. 點選「建立」。

gcloud

OIDC

如果使用 OIDC，則必須指定 --unity-service-principal-application-id。

公開網際網路 (無 CCI)

如未設定 Cross-Cloud Interconnect，連線會透過公開網際網路使用 TLS 傳輸。

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --unity-service-principal-application-id="UNITY_SERVICE_PRINCIPAL_APPLICATION_ID" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_MODE" \
    --federated-catalog-identity-mode="IDENTITY_MODE"

客戶擁有 (CCI)

如果您設定了私人互連網路 (專屬或合作夥伴 Cross-Cloud Interconnect)，請提供私人查詢傳輸 (--service-directory-name)、私人背景中繼資料重新整理 (--metadata-service-directory-name) 或兩者的 Service Directory 服務參照。您也可以執行 gcloud biglake iceberg catalogs update，在現有目錄中新增或更新任一標記。

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --unity-service-principal-application-id="UNITY_SERVICE_PRINCIPAL_APPLICATION_ID" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_MODE" \
    --federated-catalog-identity-mode="IDENTITY_MODE" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/SERVICE_DIRECTORY_NAMESPACE/services/SERVICE_NAME" \
    --metadata-service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/METADATA_SERVICE_DIRECTORY_NAMESPACE/services/METADATA_SERVICE_NAME"

更改下列內容：

• FEDERATED_CATALOG_NAME：聯合目錄的名稱。
• PROJECT_ID：您的 Google Cloud 專案 ID。
• REGION：建立聯合目錄的 Lakehouse 區域。這個區域必須與 Service Directory 命名空間和區域 Secret 相同。如要盡可能縮短延遲時間：
  • 如果 Unity Catalog 位於 AWS，請選取最靠近 AWS 區域的Google Cloud 區域。
  • 如果 Unity Catalog 位於 Azure，請選取最接近 Azure 區域的Google Cloud 區域。
  • 如果 Unity Catalog 位於 Google Cloud，請選取完全相同的區域。
• UNITY_SERVICE_PRINCIPAL_APPLICATION_ID：Databricks 服務主體的應用程式 ID (UUID)。
• UNITY_INSTANCE_NAME：目標 Databricks 工作區主機名稱 (例如 AWS 上的 abcd.cloud.databricks.com 或 Azure 上的 adb-1234567890123456.7.azuredatabricks.net)。
• UNITY_CATALOG_NAME：要建立聯合查詢的目標目錄名稱。
• REFRESH_INTERVAL：指定背景中繼資料重新整理作業的執行頻率。請將這個值設為時間長度，例如 330s 或 5m30s。
• NAMESPACE_FILTERS：選用：以半形逗號分隔的清單，列出要建立聯盟的命名空間。例如，ns1,ns2。如未提供，Lakehouse 會納入所有命名空間。
• CROSS_CLOUD_CACHE_MODE：選用，是否在聯合目錄啟用跨雲端快取 (enabled 或 disabled)。預設為 disabled。如果設為 enabled，Lakehouse 會將遠端檔案快取至目錄的Google Cloud 區域。詳情請參閱「智慧型快取」。
• IDENTITY_MODE：選用。指定目錄的身分模式。設為 user-identity-federation，即可在查詢中傳播使用者身分，或設為 service-identity，即可透過目錄的服務帳戶執行查詢。如省略，則預設為 service-identity。
• 如果您使用私人互連網路 (Cross-Cloud Interconnect)，請指定下列其中一項或兩項 Service Directory 參照 (如果未透過 Cross-Cloud Interconnect 轉送該流量層，請省略任一旗標)：
  • SERVICE_DIRECTORY_NAMESPACE 和 SERVICE_NAME：您為私人查詢傳輸至遠端物件儲存庫而建立的 Service Directory 命名空間和服務名稱。
  • METADATA_SERVICE_DIRECTORY_NAMESPACE 和 METADATA_SERVICE_NAME：您為私人背景中繼資料重新整理建立的 Service Directory 命名空間和服務名稱。

Secret-based

如果使用密鑰式驗證，則必須指定 --secret-name。

公開網際網路 (無 CCI)

如未設定 Cross-Cloud Interconnect，連線會透過公開網際網路使用 TLS 傳輸。

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/DATABRICKS_SECRET_NAME" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_MODE" \
    --federated-catalog-identity-mode="IDENTITY_MODE"

客戶擁有 (CCI)

如果您設定了私人互連網路 (專屬或合作夥伴 Cross-Cloud Interconnect)，請提供私人查詢傳輸 (--service-directory-name)、私人背景中繼資料重新整理 (--metadata-service-directory-name) 或兩者的 Service Directory 服務參照。您也可以執行 gcloud biglake iceberg catalogs update，在現有目錄中新增或更新任一標記。

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/DATABRICKS_SECRET_NAME" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_MODE" \
    --federated-catalog-identity-mode="IDENTITY_MODE" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/SERVICE_DIRECTORY_NAMESPACE/services/SERVICE_NAME" \
    --metadata-service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/METADATA_SERVICE_DIRECTORY_NAMESPACE/services/METADATA_SERVICE_NAME"

更改下列內容：

• FEDERATED_CATALOG_NAME：聯合目錄的名稱。
• PROJECT_ID：您的 Google Cloud 專案 ID。
• REGION：建立聯合目錄的 Lakehouse 區域。這個區域必須與 Service Directory 命名空間和區域 Secret 相同。如要盡可能縮短延遲時間：
  • 如果 Unity Catalog 位於 AWS，請選取最靠近 AWS 區域的Google Cloud 區域。
  • 如果 Unity Catalog 位於 Azure，請選取最接近 Azure 區域的Google Cloud 區域。
  • 如果 Unity Catalog 位於 Google Cloud，請選取完全相同的區域。
• DATABRICKS_SECRET_NAME：Databricks 密鑰名稱。
• UNITY_INSTANCE_NAME：目標 Databricks 工作區主機名稱 (例如 AWS 上的 abcd.cloud.databricks.com 或 Azure 上的 adb-1234567890123456.7.azuredatabricks.net)。
• UNITY_CATALOG_NAME：要建立聯合查詢的目標目錄名稱。
• REFRESH_INTERVAL：指定背景中繼資料重新整理作業的執行頻率。請將這個值設為時間長度，例如 330s 或 5m30s。
• NAMESPACE_FILTERS：選用：以半形逗號分隔的清單，列出要建立聯盟的命名空間。例如，ns1,ns2。如未提供，Lakehouse 會納入所有命名空間。
• CROSS_CLOUD_CACHE_MODE：選用，是否在聯合目錄啟用跨雲端快取 (enabled 或 disabled)。預設為 disabled。如果設為 enabled，Lakehouse 會將遠端檔案快取至目錄的Google Cloud 區域。詳情請參閱「智慧型快取」。
• IDENTITY_MODE：選用。指定目錄的身分模式。設為 user-identity-federation，即可在查詢中傳播使用者身分，或設為 service-identity，即可透過目錄的服務帳戶執行查詢。如省略，則預設為 service-identity。
• 如果您使用私人互連網路 (Cross-Cloud Interconnect)，請指定下列其中一項或兩項 Service Directory 參照 (如果未透過 Cross-Cloud Interconnect 轉送該流量層，請省略任一旗標)：
  • SERVICE_DIRECTORY_NAMESPACE 和 SERVICE_NAME：您為私人查詢傳輸至遠端物件儲存庫而建立的 Service Directory 命名空間和服務名稱。
  • METADATA_SERVICE_DIRECTORY_NAMESPACE 和 METADATA_SERVICE_NAME：您為私人背景中繼資料重新整理建立的 Service Directory 命名空間和服務名稱。

完成驗證設定

使用所選驗證類型完成驗證程序。

OIDC

建立目錄時，Lakehouse 會為其佈建專屬服務帳戶。您必須擷取服務帳戶的專屬數字 ID，並用來設定 Databricks 服務主體的同盟政策。

1. 擷取 Lakehouse 目錄服務帳戶的專屬 ID：

   gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
       --project="PROJECT_ID" \
       --format='value(biglake-service-account-id)'

2. 在 Databricks 帳戶中，為先前建立的服務主體設定聯合政策。請使用下列值：

   • 核發者網址：https://accounts.google.com
   • Subject：上一步擷取的 Lakehouse 目錄服務帳戶專屬數字 ID。
   • 目標對象：https://accounts.cloud.databricks.com

   請務必授予 EXTERNAL USE SCHEMA 權限，讓 Databricks 服務主體具備目標目錄及其資源的讀取權限。

Secret-based

建立目錄時，Lakehouse 會為其佈建專屬服務帳戶 (在資源說明中傳回為 biglake-service-account)。

您必須授予這個服務帳戶權限，才能存取先前建立的密鑰。請注意，IAM 政策可能需要幾分鐘才能傳播。

授予目錄服務帳戶存取密鑰的權限：

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets add-iam-policy-binding DATABRICKS_SECRET_NAME \
  --project="PROJECT_ID" \
  --location="REGION" \
  --member="serviceAccount:$(gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
      --project="PROJECT_ID" \
      --format='value(biglake-service-account)')" \
  --role="roles/secretmanager.secretAccessor"

執行下列指令，確認聯合目錄服務帳戶有權存取密鑰：

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets get-iam-policy DATABRICKS_SECRET_NAME \
     --project="PROJECT_ID" \
     --location="REGION"

在輸出內容中，確認 biglake-service-account 服務帳戶已獲派 roles/secretmanager.secretAccessor 角色。

請務必授予 EXTERNAL USE SCHEMA 權限，讓 Databricks 服務主體具備目標目錄及其資源的讀取權限。

完成私人互連網路設定 (僅限 Cross-Cloud Interconnect)

如果您透過私人互連網路 (Dedicated 或合作夥伴 Cross-Cloud Interconnect) 轉送查詢傳輸、背景中繼資料重新整理，或兩者皆有，則必須授予 Lakehouse 目錄服務帳戶權限，以便透過 Service Directory 探索及授權連線。如果傳輸 Service Directory 服務和中繼資料 Service Directory 服務託管於不同的 Google Cloud 專案，請在託管 Service Directory 服務的各個專案授予這些角色。

注意： 目錄服務帳戶是內部 Google Cloud 服務代理。這個帳戶可能不會顯示在Google Cloud 控制台的專案服務帳戶清單中，但您可以手動指派角色。

控制台

1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

   前往「IAM」頁面

2. 按一下「授予存取權」 (或「新增」)。

3. 在「新增主體」欄位，輸入 Lakehouse 目錄服務帳戶電子郵件地址。您可以透過描述目錄來擷取這個電子郵件地址 (請參閱「gcloud」gcloud分頁)。

4. 在「Role」(角色) 選單中，選取「Service Directory Viewer」(Service Directory 檢視者) (roles/servicedirectory.viewer)。

5. 按一下「Add another role」(新增其他角色)，然後選取「Service Directory PSC Authorized Service」(Service Directory PSC 授權服務) (roles/servicedirectory.pscAuthorizedService)。

6. 按一下「儲存」。

gcloud

在託管 Service Directory 服務的專案中，將必要角色授予目錄的服務帳戶：

# Grant Service Directory Viewer
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='value(biglake-service-account)')" \
--role="roles/servicedirectory.viewer"

# Grant Service Directory PSC Authorized Service
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='value(biglake-service-account)')" \
--role="roles/servicedirectory.pscAuthorizedService"

驗證連線

確認目錄背景中繼資料重新整理週期已順利完成，且命名空間已同步。

1. 確認重新整理狀態顯示成功：

   gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
     --project="PROJECT_ID"

2. 確認命名空間已同步：

   gcloud biglake iceberg namespaces list \
     --project="PROJECT_ID" \
     --catalog="FEDERATED_CATALOG_NAME"

設定使用者身分聯盟 (選用)

如果您為聯合目錄設定了使用者身分聯盟，則必須在 Databricks 中設定帳戶層級聯盟政策。

背景中繼資料重新整理作業會以目錄的服務帳戶執行，該帳戶已設定基本驗證 (OIDC 或 Secret)，但使用者身分聯合需要這項帳戶層級政策，Databricks 才能驗證 Google Cloud 在互動式查詢期間產生的使用者身分權杖。這樣一來，Databricks 就能將查詢歸因於使用者、強制執行權限，以及產生稽核記錄。

1. (選用) 更新現有目錄：

   如果現有的聯合目錄是以預設服務身分模式設定，您可以將其更新為使用者身分聯合，而不必重新建立目錄：

   控制台

   1. 前往 Google Cloud 控制台的「Lakehouse」Lakehouse。

      前往 Lakehouse

   2. 在目錄清單中，按一下聯合目錄的名稱。

      「Catalog details」(目錄詳細資料) 頁面隨即顯示。

   3. 按一下「 編輯目錄」。

   4. 在「Identity mode」(身分模式) 部分，選取「User identity」(使用者身分)。

   5. 按一下「儲存」。

   gcloud

   執行 gcloud biglake iceberg catalogs update 指令：

   gcloud biglake iceberg catalogs update FEDERATED_CATALOG_NAME \
       --project="PROJECT_ID" \
       --federated-catalog-identity-mode="user-identity-federation"

2. 從目錄中擷取 OIDC 憑證：

   執行下列指令，擷取 Databricks 所需的權杖宣告：

   gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
       --project="PROJECT_ID" \
       --format='yaml(federated-catalog-options.user-identity-federation-oidc)'

   輸出看起來類似以下內容：

   federated-catalog-options:
     user-identity-federation-oidc:
       audience: databricks-12345678-abcd-1234-efgh-1234567890ab
       issuer-url: https://www.gstatic.com/biglake/federation/organizations/123456789012

   請注意下列有關聲明可用性的事項：

   • issuer-url：衍生自 Google Cloud 組織 (https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID)，在建立目錄後即可使用。
   • audience：範圍限定為目標 Databricks metastore (databricks-METASTORE_ID)，並衍生自 Unity Catalog metastore。這個值是由背景中繼資料重新整理功能填入，因此必須完成基本驗證，且背景中繼資料重新整理功能必須處於啟用狀態 (未設為 0)。請參閱「驗證連線」一節，確認背景中繼資料重新整理功能已正確設定。

3. 設定 Databricks 帳戶層級聯合政策：

   1. 在 Databricks 帳戶控制台中，依序前往「Account settings」>「Security」>「Identity provider setup」。
   2. 在「Federation policies」(聯合政策) 區段中，按一下「Create policy」(建立政策)。
   3. 在政策設定對話方塊中，設定下列欄位：
      • Issuer URL：輸入上一步擷取的 issuer-url 值 (例如 https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID)。
      • 目標對象：輸入上一步擷取的 metastore 範圍 audience 值 (例如 databricks-METASTORE_ID)。
      • Subject claim：留空 (Databricks 預設為包含使用者電子郵件地址的 sub 宣告)。Databricks 會使用這個電子郵件地址，比對 Databricks 帳戶中設定的使用者。
   4. 按一下「儲存」。

4. 驗證使用者身分聯盟和稽核記錄：

   如要驗證使用者歸因查詢執行和稽核記錄，請按照下列步驟操作：

   1. 按照「查詢遠端資料」一文的說明，在 BigQuery 中對聯合資料表執行查詢。

   2. 在 Databricks 中，確認查詢存取事件已記錄在 Databricks 稽核記錄中。在 Databricks SQL 編輯器中查詢 system.access.audit 系統資料表 (請參閱 Databricks 稽核記錄參考資料)。請注意，可稽核事件可能需要 15 分鐘以上，才會顯示在 Databricks 稽核記錄中：

      SELECT
        *
      FROM
        system.access.audit
      WHERE
        service_name = 'accounts'
        AND action_name IN ('oidcTokenAuthorization')
        AND event_time >= NOW() - INTERVAL 30 MINUTE
        AND user_identity.email = 'USER_EMAIL'
      ORDER BY
        event_time DESC
      LIMIT 10;

後續步驟

• 查詢遠端資料。
• 搭配使用 VPC Service Controls 與聯合目錄端點。
• 排解 Databricks Unity Catalog 的跨雲端資料存取問題。