為 Databricks Unity Catalog 設定無邊界 Lakehouse

本文說明如何設定無邊界的 Lakehouse，直接在Google Cloud中查詢 Databricks Unity Catalog 目錄的資料。這項功能可將外部資料來源與現有Google Cloud 環境整合，統一資料分析作業。

之後，您可以使用 Lakehouse for Apache Iceberg 管理同盟資料的存取權。

事前準備

  1. 請參閱 Lakehouse 總覽，瞭解 Lakehouse 如何管理資料存取權。
  2. 請參閱「無邊界 Lakehouse 簡介」，瞭解運作方式。
  3. 請參閱支援的目錄，確認外部位置規定和支援的設定。
  4. 瞭解如何使用區域性 Secret Manager 密鑰。如要使用以密碼為基礎的驗證，透過 Databricks Unity Catalog 設定無邊界的 Lakehouse，就必須執行這項操作。
  5. 在遠端目錄供應商中產生 OAuth 服務主體 (用戶端 ID 和用戶端密鑰，後者為選用)，該主體必須具備目標目錄的讀取權限。這個程序不在本文的討論範圍內。
  6. 選用：如果您打算透過 Google Cloud 虛擬私有雲和遠端雲端供應商虛擬私有雲 (例如 AWS) 之間的私有互連網路，傳送查詢，請確認您在遠端供應商擁有有效帳戶、佈建專屬跨雲端互連或合作夥伴跨雲端互連、與 Cloud Router 建立 BGP 工作階段，並確認您在兩個雲端環境中都擁有必要的 IAM 權限。
  7. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the BigLake, Secret Manager APIs.

    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

  10. Verify that billing is enabled for your Google Cloud project.

  11. Enable the BigLake, Secret Manager APIs.

    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

    12.

必要的角色

如要取得設定無邊界 Lakehouse 所需的權限，請要求管理員授予您專案的下列 IAM 角色：

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

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

支援的目錄詳細資料

本指南提供相關操作說明，協助您在 Amazon Web Services (AWS) 或 Google Cloud上，使用 Databricks Unity Catalog 目錄設定無邊界 Lakehouse。如要進一步瞭解外部位置需求和支援的設定，請參閱「支援的目錄」。

限制和注意事項

本節列出使用無邊界 Lakehouse 的限制和注意事項。

  • 支援的雲端供應商：使用私人互連與無邊界 Lakehouse 搭配使用時，支援下列遠端雲端供應商：Amazon Web Services (AWS)。您可以使用專屬 Cross-Cloud Interconnect 或合作夥伴 Cross-Cloud Interconnect。
  • 系統僅支援使用AWS 外部位置或 Google Cloud外部位置的 Databricks Unity Catalog 目錄。使用 AWS 預設儲存空間或 Google Cloud預設儲存空間的 Unity Catalog 目錄不支援。
  • 您必須在 Unity Catalog 使用的 Metastore 上啟用外部資料存取權，這項功能預設為停用。
  • 網路轉送：如果未設定私人互連網路 (例如專屬 CCI 或合作夥伴 CCI)，查詢會透過公用網際網路轉送。這可能會導致遠端雲端供應商收取較高的輸出費用，且效能較難預測。
  • 資料更新間隔：聯盟目錄的 --refresh-interval 標記會決定中繼資料的同步頻率。間隔越短，資料越新，但可能會產生額外的遠端目錄供應商 API 費用。
  • Iceberg 指標回報： Iceberg 指標回報不適用於聯邦目錄。存取同盟目錄時，請在 Iceberg 用戶端中將 rest-metrics-reporting-enabled 屬性設為 false。

一般工作流程

如要設定及使用無邊界 Lakehouse，請按照下列一般步驟操作：

  • 設定跨雲端互連 (選用)：設定 Google Cloud VPC 與遠端雲端供應商之間的私人連線。
  • 設定聯盟：設定驗證，並在 Lakehouse 中建立聯合目錄。
    • OpenID Connect (OIDC) (建議)：在 Lakehouse 中建立聯盟目錄，指定遠端服務主體應用程式 ID，然後使用 Lakehouse 目錄服務帳戶的唯一 ID，在 Databricks 中設定聯盟政策。
    • 以密鑰為基礎的驗證：在 Secret Manager 中使用遠端目錄憑證建立密鑰。然後在 Lakehouse 中建立聯合目錄，並授予目錄服務帳戶密鑰存取權。
  • 驗證連線：確認 Lakehouse 能順利連線至遠端目錄。
  • 查詢資料：使用 BigQuery 或 Managed Service for Apache Spark，對聯合資料執行查詢。詳情請參閱「使用無邊界 Lakehouse」。
  • 設定權限：使用 Identity and Access Management (IAM) 管理可查看及查詢同盟資料的使用者。

設定 Cross-Cloud Interconnect (選用)

根據預設，對遠端目錄的查詢會透過公開網際網路傳輸。為協助提升安全性及法規遵循能力、提供可預測的效能，以及降低資料傳輸費用，請使用私有互連。這會在您的 Google Cloud虛擬私有雲 (VPC) 與遠端雲端供應商的網路 (例如 AWS) 之間，建立專屬的私人網路連線。

您可以在 Google Cloud 虛擬私有雲和遠端雲端供應商的虛擬私有雲 (例如 AWS) 之間，佈建及設定下列任一私人互連選項：

在 Cloud Router Google Cloud 和遠端雲端供應商的 VPC 之間建立 BGP 工作階段，確保路徑交換。

如要啟用私下查詢，您必須透過私有互連，設定從 Lakehouse 到遠端儲存空間值區 (例如 AWS Amazon S3 值區) 的路徑。您可以按照兩種架構流程設定這項路徑：

  • 內部區域 Proxy 網路負載平衡器轉送：這個流程會使用Google Cloud 內部區域 Proxy 網路負載平衡器，將要求分配至指向多個 AWS 彈性網路介面 (ENI) 的混合式連線網路端點群組 (NEG)。這個流程對於負載平衡、擴充性和高可用性至關重要。合作夥伴 CCI 必須使用此功能，建議專屬 CCI 也使用此功能，以利負載平衡、擴充及高可用性。
  • 直接端點路由：這個流程會將 Service Directory 直接連至單一 AWS 介面 VPC 端點 IP 位址。這個流程僅適用於專屬 CCI，不支援合作夥伴 CCI。

選取符合架構需求的設定流程：

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

如要設定內部區域 Proxy 網路負載平衡器，將要求分配到多個 AWS ENI，以達到高可用性和負載平衡，請按照下列步驟操作：

設定 AWS 網路

首先，請建立 Amazon S3 虛擬私有雲介面端點 (AWS PrivateLink)：

  1. 在 AWS VPC 控制台中，為 Amazon S3 建立介面端點。
  2. 指定服務名稱為 com.amazonaws.AWS_REGION.s3。
  3. 選取透過 Direct Connect 連線至 Google Cloud VPC 的 VPC 和子網路。
  4. 將安全性群組附加至端點，控管連入存取權。
  5. 這會在每個選取的子網路中佈建彈性網路介面 (ENI)。記下這些 ENI 的私人 IP 位址。

接著，請設定安全群組：

  • 確認附加至 Amazon S3 端點 ENI 的安全性群組允許來自 Google Cloud 虛擬私有雲的通訊埠 443 輸入 TCP 流量。這必須包含Google Cloud 僅限 Proxy 子網路的 CIDR 範圍，才能允許健康狀態檢查和轉送的流量。

設定 Google Cloud 網路

為簡化設定，請執行下列指令來設定內部負載平衡器。如需進階設定或更多詳細資料，請參閱「為混合式端點設定內部區域 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)。

  1. 建立地區健康狀態檢查：

    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

    將 AWS ENI 的私有 IP 位址新增至對應的混合 NEG：

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

    更改下列內容：

    • NEG_NAME：混合式 NEG 的名稱。
    • ZONE： Google Cloud 區域 (例如 us-east4-a)。這個區域必須位於 Cross-Cloud Interconnect VLAN 連結的區域內。
    • VPC_NETWORK：虛擬私有雲網路的名稱。
    • AWS_S3_IP：該區域中 AWS Amazon S3 虛擬私有雲端點 (ENI) 的私有 IP 位址。

    如果 AWS ENI 分散在多個可用區，請重複執行這些指令，為其他可用區建立 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 中註冊 ILB 的 IP 位址，讓 Lakehouse 能夠探索該位址。

  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。

  3. 在服務中建立 ILB 的端點：

    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：ILB 轉送規則的內部 IP 位址。

直接端點

如要設定 Service Directory，將流量直接轉送至單一 AWS 介面 VPC 端點 IP 位址，請按照下列步驟操作：

  1. 在 AWS 虛擬私有雲中，為 Amazon S3 建立介面 VPC 端點。記下這個端點的 IP 位址和通訊埠。

  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。

  4. 在服務中建立端點，內含 Amazon S3 介面 VPC 端點的路徑資訊：

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

    更改下列內容：

    • ENDPOINT_NAME：端點的專屬 ID。
    • S3_VPCE_IP_ADDRESS：Amazon S3 介面 VPC 端點的 IP 位址。例如：10.0.1.45。
    • S3_VPCE_PORT：Amazon S3 介面 VPC 端點的通訊埠編號。例如：443。
    • PROJECT_NUMBER：您的 Google Cloud專案編號。在 --network 標記中使用專案編號。
    • VPC_NETWORK：與私有互連相關聯的虛擬私有雲網路名稱。 Google Cloud

設定聯盟

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

設定驗證機制

如要進行同盟，必須以 Databricks 服務主體身分驗證遠端目錄。選擇下列其中一個驗證選項：

OIDC

OpenID Connect (OIDC) 可透過 Databricks OAuth 權杖聯盟進行無密碼驗證。

  1. 在 Databricks 帳戶中建立服務主體，並授予目標 Unity Catalog 目錄的讀取權限。
  2. 儲存服務主體的應用程式 ID (UUID)。後續步驟會用到這項資訊。

以密鑰為基礎

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

  1. 建立名為 credentials.json 的 JSON 檔案，其中包含您的酬載：

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

    更改下列內容：

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

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

    Secret Manager 預設會使用全域端點。不過，無邊界 Lakehouse 要求密鑰必須與 Lakehouse 目錄位於相同區域。如要使用 gcloud 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。 為避免連線問題，請在相同區域建立密鑰和目錄。例如 secretmanager.us-east4.rep.googleapis.com。

  3. 將酬載上傳至 Secret Manager：

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

    更改下列內容：

    • DATABRICKS_SECRET_NAME：Databricks 密鑰的名稱。

建立聯合目錄

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

注意事項：

控制台

如要使用以密鑰為準的驗證方式建立同盟目錄，請按照下列步驟操作：

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

    前往 Lakehouse

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

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

    系統會顯示「目錄設定」詳細資料。

  4. 在「聯合目錄來源」中，選取「Unity (Databricks)」。

  5. 針對「Data location」(資料位置)，選取要建立聯邦目錄的 Lakehouse 區域。例如：us-east4。如要盡可能縮短延遲時間 (即使透過公開網際網路)，請在選取區域時採取下列做法：

    • 如果 Unity Catalog 目錄位於 AWS，請選取最靠近 AWS 區域的Google Cloud 區域。
    • 如果 Unity Catalog 目錄已開啟 Google Cloud，請選取完全相同的區域。

  6. 按一下「繼續」。

    系統會顯示「連線詳細資料」。

  7. 在「Remote catalog details」(遠端目錄詳細資料) 部分的「Unity instance name」(Unity 執行個體名稱) 欄位中，輸入目標 Databricks 執行個體名稱。例如：abcd.cloud.databricks.com。

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

  9. 選取「驗證方式」選項：

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

  10. 選用：在「Service directory name」(服務目錄名稱) 欄位中，輸入 Service Directory 服務的路徑。例如：projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME。只有在設定 Cross-Cloud Interconnect 時，才需要執行這項操作。

  11. 點選「建立」。

gcloud CLI

OIDC

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

公開網際網路 (無 CCI)

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"

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • REGION：建立聯合目錄的 Lakehouse 區域。例如，us-east4。如要盡量縮短延遲時間，請在選取區域時採取下列做法：
    • 如果 Unity Catalog 目錄位於 AWS，請選取最靠近 AWS 區域的Google Cloud 區域。
    • 如果 Unity Catalog 目錄已開啟 Google Cloud，請選取完全相同的區域。
  • UNITY_SERVICE_PRINCIPAL_APPLICATION_ID：Databricks 服務主體的應用程式 ID (UUID)。
  • UNITY_INSTANCE_NAME：目標 Databricks 執行個體名稱。例如：abcd.cloud.databricks.com。
  • UNITY_CATALOG_NAME：要聯合的目標 Databricks Unity Catalog 目錄名稱。
  • REFRESH_INTERVAL：選用：指定更新目錄資訊的頻率。將這個值設為時間長度，例如 330s 或 5m30s。間隔時間越短，資料更新頻率越高，但 API 呼叫費用可能也會增加。時間間隔越長，費用可能越低，但查詢到的資料可能無法反映最新的資料集。如果省略或將值設為 0s，系統就不會啟動背景中繼資料重新整理。除非將重新整理間隔更新為正值，否則這項功能會維持停用狀態。
  • NAMESPACE_FILTERS：選用：以半形逗號分隔的命名空間清單，用於同盟。例如，ns1,ns2。如省略，則會納入所有命名空間。

客戶擁有 (CCI)

如果您已設定私人互連網路 (例如專屬 CCI 或合作夥伴 CCI)，請提供 Service Directory 服務參照，讓 Lakehouse 私下轉送流量。

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" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME"

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • PROJECT_NUMBER：您的 Google Cloud 專案編號。
  • REGION：建立聯合目錄的 Lakehouse 區域。例如，us-east4。如要盡量縮短延遲時間，請在選取區域時採取下列做法：
    • 如果 Unity Catalog 目錄位於 AWS，請選取最靠近 AWS 區域的Google Cloud 區域。
    • 如果 Unity Catalog 目錄已開啟 Google Cloud，請選取完全相同的區域。注意：這個區域必須與 Service Directory 命名空間和區域密鑰相同。
  • UNITY_SERVICE_PRINCIPAL_APPLICATION_ID：Databricks 服務主體的應用程式 ID (UUID)。
  • UNITY_INSTANCE_NAME：目標 Databricks 執行個體名稱。例如：abcd.cloud.databricks.com。
  • UNITY_CATALOG_NAME：要聯合的目標 Databricks Unity Catalog 目錄名稱。
  • REFRESH_INTERVAL：選用：指定更新目錄資訊的頻率。將這個值設為時間長度，例如 330s 或 5m30s。間隔時間越短，資料更新頻率越高，但 API 呼叫費用可能也會增加。時間間隔越長，費用可能越低，但查詢到的資料可能無法反映最新的資料集。如果省略或將值設為 0s，系統就不會啟動背景中繼資料重新整理。除非將重新整理間隔更新為正值，否則這項功能會維持停用狀態。
  • NAMESPACE_FILTERS：選用：以半形逗號分隔的命名空間清單，用於同盟。例如，ns1,ns2。如省略，則會納入所有命名空間。
  • NAMESPACE：您在設定私人互連時建立的 Service Directory 命名空間。
  • SERVICE_NAME：您在設定私人互連時建立的 Service Directory 服務名稱。

以密鑰為基礎

如果您使用以密鑰為基礎的驗證，則必須指定 secret-name。

公開網際網路 (無 CCI)

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"

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • REGION：建立聯合目錄的 Lakehouse 區域。例如，us-east4。如要盡量縮短延遲時間，請在選取區域時採取下列做法：
    • 如果 Unity Catalog 目錄位於 AWS，請選取最靠近 AWS 區域的Google Cloud 區域。
    • 如果 Unity Catalog 目錄已開啟 Google Cloud，請選取完全相同的區域。
  • DATABRICKS_SECRET_NAME：Databricks Secret 的名稱。
  • UNITY_INSTANCE_NAME：目標 Databricks 執行個體名稱。例如：abcd.cloud.databricks.com。
  • UNITY_CATALOG_NAME：要聯合的目標 Databricks Unity Catalog 目錄名稱。
  • REFRESH_INTERVAL：選用：指定更新目錄資訊的頻率。將這個值設為時間長度，例如 330s 或 5m30s。間隔時間越短，資料更新頻率越高，但 API 呼叫費用可能也會增加。時間間隔越長，費用可能越低，但查詢到的資料可能無法反映最新的資料集。如果省略或將值設為 0s，系統就不會啟動背景中繼資料重新整理。除非將重新整理間隔更新為正值，否則這項功能會維持停用狀態。
  • NAMESPACE_FILTERS：選用：以半形逗號分隔的命名空間清單，用於同盟。例如，ns1,ns2。如省略，則會納入所有命名空間。

客戶擁有 (CCI)

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" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME"

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • PROJECT_NUMBER：您的 Google Cloud 專案編號。
  • REGION：建立聯合目錄的 Lakehouse 區域。例如，us-east4。如要盡量縮短延遲時間，請在選取區域時採取下列做法：
    • 如果 Unity Catalog 目錄位於 AWS，請選取最靠近 AWS 區域的Google Cloud 區域。
    • 如果 Unity Catalog 目錄已開啟 Google Cloud，請選取完全相同的區域。注意：這個區域必須與 Service Directory 命名空間和區域密鑰相同。
  • DATABRICKS_SECRET_NAME：Databricks Secret 的名稱。
  • UNITY_INSTANCE_NAME：目標 Databricks 執行個體名稱。例如：abcd.cloud.databricks.com。
  • UNITY_CATALOG_NAME：要聯合的目標 Databricks Unity Catalog 目錄名稱。
  • REFRESH_INTERVAL：選用：指定更新目錄資訊的頻率。將這個值設為時間長度，例如 330s 或 5m30s。間隔時間越短，資料更新頻率越高，但 API 呼叫費用可能也會增加。時間間隔越長，費用可能越低，但查詢到的資料可能無法反映最新的資料集。如果省略或將值設為 0s，系統就不會啟動背景中繼資料重新整理。除非將重新整理間隔更新為正值，否則這項功能會維持停用狀態。
  • NAMESPACE_FILTERS：選用：以半形逗號分隔的命名空間清單，用於同盟。例如，ns1,ns2。如省略，則會納入所有命名空間。
  • NAMESPACE：您在設定私人互連時建立的 Service Directory 命名空間。
  • SERVICE_NAME：您在設定私人互連時建立的 Service Directory 服務名稱。

完成驗證設定

根據所選的驗證選項完成設定：

OIDC

建立目錄時，Lakehouse 會為目錄佈建專屬服務帳戶。您必須擷取服務帳戶的數字唯一 ID，並使用該 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
    • 主體：在上一個步驟中擷取的 Lakehouse 目錄服務帳戶專屬數字 ID。
    • 目標對象：https://accounts.cloud.databricks.com

    請確認 Databricks 服務主體具備目標目錄和工作區的讀取權限。

以密鑰為基礎

建立目錄時，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 角色。

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

如果透過私人互連網路 (專屬或合作夥伴 CCI) 轉送流量，您必須授予 Lakehouse 目錄服務帳戶權限，才能透過 Service Directory 探索及授權連線。

控制台

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

    前往「IAM」頁面

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

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

  4. 在「角色」下拉式選單中，選取「Service Directory Viewer」 (roles/servicedirectory.viewer)。

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

  6. 按一下 [儲存]。

gcloud CLI

將必要角色指派給目錄的服務帳戶：

# Grant Service Directory Viewer
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(gcloud alpha 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 alpha 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"

後續步驟