為 Snowflake Horizon Catalog 設定跨雲端連線

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

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

事前準備

1. 請參閱「Lakehouse 總覽」，瞭解 Lakehouse 如何管理資料存取權。
2. 請參閱這篇文章，瞭解如何存取跨雲端資料。
3. 請查看支援的目錄，確認支援的設定。
4. 瞭解如何使用區域性 Secret Manager 密鑰。如要使用密鑰驗證機制，透過 Snowflake Horizon Catalog 設定 Lakehouse，就必須執行這項操作。
5. 選用：如果您打算透過 Google Cloud虛擬私有雲 (VPC) 網路和遠端雲端網路 (AWS VPC 或 Azure VNet) 之間的私人互連網路，轉送查詢讀取或背景中繼資料重新整理作業，請確認您在遠端供應商擁有有效帳戶、佈建專用 Cross-Cloud Interconnect 或合作夥伴 Cross-Cloud Interconnect、與 Cloud Router 建立 BGP 工作階段，並確認您在兩個雲端環境中都具備必要的 Identity and Access Management (IAM) 權限。
登入 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 透過公開網際網路轉送相應流量。如果透過公開網際網路轉送查詢讀取作業，遠端雲端服務供應商可能會收取較高的輸出費用，且效能較難預測。
• Snowflake Horizon Catalog 支援的資料表：只有 Snowflake Horizon Catalog 中的 Apache Iceberg 資料表會同步至 Lakehouse。在背景中繼資料重新整理期間，系統會忽略非 Iceberg Snowflake 資料表。
• 網路政策和輸出 IP 位址：背景中繼資料重新整理作業透過公開網際網路連線時，Lakehouse 會使用 Google 全球基礎架構輸出 IP 位址，連至 Snowflake 網際網路端點。如果您設定 Snowflake 網路政策，允許透過公開網際網路連線能力存取，請將 goog.json 中的 Google 輸出 IP 位址範圍，新增至網路政策的允許 IP 清單。透過 Cross-Cloud Interconnect 設定私人背景中繼資料重新整理時，中繼資料要求會透過虛擬私有雲網路，私下轉送至 Snowflake PrivateLink 端點。
• 唯讀：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 建立聯合目錄。
  • 以密鑰為基礎的驗證 (PAT)：使用遠端目錄憑證，在 Secret Manager 中建立密鑰。接著，在 Lakehouse 建立聯合目錄，並授予目錄服務帳戶密鑰存取權。
  • Workload Identity Federation (WIF)：在 Lakehouse 建立聯合目錄，並指定必要的 Snowflake 角色。接著，將目錄的服務帳戶 ID 連結至 Snowflake 的服務使用者。Snowflake 服務使用者必須具備遠端 Snowflake Horizon 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 執行階段目錄轉送至遠端 Snowflake Horizon 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 位址。
• 如要進行私人背景中繼資料重新整理 (遠端目錄)：在 Snowflake 中執行 SELECT SYSTEM$GET_PRIVATELINK_CONFIG();，取得 PrivateLink 服務 ID 和 .privatelink 帳戶 ID。在 AWS 上，請按照 AWS PrivateLink 和 Snowflake 的說明，在 AWS VPC 中建立介面 VPC 端點，並記下 ENI 私人 IP 位址。在 Azure 上，請按照「Azure Private Link 和 Snowflake」一文的說明，在 Azure VNet 中建立 Azure 私人端點，並記下 NIC 私人 IP 位址。
• 傳入安全性規則：確認附加至私人端點的 AWS 安全性群組或 Azure 網路安全性群組 (NSG)，允許來自 Google Cloud 虛擬私有雲 CIDR 範圍的通訊埠 443 (如果 Snowflake 設定使用 OCSP，則為通訊埠 80) 傳入 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)。
   • 如要私下重新整理背景中繼資料： 在 Snowflake 中執行 SELECT SYSTEM$GET_PRIVATELINK_CONFIG();，並按照 AWS PrivateLink 和 Snowflake 的說明建立介面 VPC 端點，或按照 Azure Private Link 和 Snowflake 的說明建立 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 聯合目錄，並連結至遠端 Snowflake Horizon Catalog。

設定驗證機制

必須設定憑證或角色，才能透過聯合功能存取遠端 Snowflake Horizon Catalog。請選擇下列其中一種方法。

Secret-based (PAT)

這個選項會使用程式輔助存取權杖 (PAT)，並以區域 Secret Manager 密鑰安全儲存。

1. 產生對目標目錄具有讀取權限的程式輔助存取權杖 (PAT)。

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

   {
     "client_secret": "SNOWFLAKE_PAT_TOKEN",
     "scope": "session:role:SNOWFLAKE_ROLE"
   }

   重要事項： 請將這個 JSON 結構儲存在密鑰中，而非原始個人存取權杖 (PAT) 字串。如果儲存原始權杖時未加上 JSON 包裝函式，背景中繼資料重新整理作業會失敗，並顯示代碼 16。

   更改下列內容：

   • SNOWFLAKE_PAT_TOKEN：Snowflake 程式輔助存取權杖 (PAT)。
   • SNOWFLAKE_ROLE：工作階段所需的特定 Snowflake 角色。例如：ICEBERG_VIEW。
   注意： Snowflake Horizon Catalog 設定不需要 client_id 參數，因為驗證是由 PAT 和範圍處理。

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

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

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

   更改下列內容：

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

4. 將酬載上傳至 Secret Manager：

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

   更改下列內容：

   • SNOWFLAKE_SECRET_NAME：Snowflake 密鑰的名稱。
   • PROJECT_ID：您的 Google Cloud 專案 ID。

Workload Identity Federation

Workload Identity Federation (WIF) 會將 Lakehouse 目錄服務帳戶直接連結至 Snowflake 服務使用者，避免使用長期密鑰。無須事先設定。繼續建立聯合目錄。

建立聯合目錄

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

控制台

如何建立聯合目錄：

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

   前往 Lakehouse

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

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

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

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

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

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

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

7. 按一下「繼續」。

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

8. 在「Remote catalog details」(遠端目錄詳細資料) 區段的「Snowflake account identifier」(Snowflake 帳戶 ID) 欄位中，輸入 Snowflake 帳戶 ID (例如 myorg-myaccount)。如果您透過 AWS PrivateLink 或 Azure Private Link 私下轉送背景中繼資料重新整理作業，請輸入 .privatelink 帳戶 ID (例如 myorg-myaccount.privatelink)。

9. 在「Snowflake warehouse」(Snowflake 倉儲) 欄位中，輸入 Snowflake 倉儲名稱。這也稱為 Snowflake Horizon Catalog 中的資料庫名稱。

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

    • 在「Secret」(密鑰) 中，輸入基於密鑰 (PAT) 的密鑰名稱。請使用下列格式：projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME。
    • 如果是 OIDC，請輸入 Workload Identity Federation 的 Snowflake 角色。例如：ICEBERG_VIEW。

11. 在「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。

12. 點選「建立」。

gcloud

Secret-based (PAT)

如果使用密鑰式驗證，則必須指定 --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="snowflake" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_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="snowflake" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_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 相同。如要盡可能縮短延遲時間：
  • 如果 Snowflake Horizon Catalog 位於 AWS，請選取最接近 AWS 區域的Google Cloud 區域。
  • 如果 Snowflake Horizon Catalog 位於 Azure，請選取最接近 Azure 區域的Google Cloud 區域。
  • 如果 Snowflake Horizon Catalog 位於 Google Cloud，請選取完全相同的區域。
• SNOWFLAKE_SECRET_NAME：Snowflake 密鑰的名稱。
• SNOWFLAKE_ACCOUNT_IDENTIFIER：您的 Snowflake 帳戶 ID (例如 myorg-myaccount)。如果您指定 --metadata-service-directory-name 透過 PrivateLink 或 Private Link 同步處理中繼資料，請使用 .privatelink 帳戶 ID (例如 myorg-myaccount.privatelink)。
• SNOWFLAKE_WAREHOUSE：要與之建立聯合查詢的 Snowflake 倉儲。這也稱為 Snowflake Horizon Catalog 中的資料庫名稱。
• REFRESH_INTERVAL：選用。指定背景中繼資料重新整理的執行頻率。請將這個值設為時間長度，例如 330s 或 5m30s。
• NAMESPACE_FILTERS：選用：以半形逗號分隔的命名空間清單，用於聯合。例如：ns1,ns2。如果省略，Lakehouse 會納入所有命名空間。
• CROSS_CLOUD_CACHE_MODE：選用，是否在聯合目錄啟用跨雲端快取 (enabled 或 disabled)。預設為 disabled。如果設為 enabled，Lakehouse 會將遠端檔案快取至目錄的Google Cloud 區域。詳情請參閱「智慧型快取」。
• 如果您使用私人互連網路 (Cross-Cloud Interconnect)，請指定下列其中一項或兩項 Service Directory 參照 (如果未透過 Cross-Cloud Interconnect 轉送該流量層，請省略任一旗標)：
  • SERVICE_DIRECTORY_NAMESPACE 和 SERVICE_NAME：您為私人查詢傳輸至遠端物件儲存庫而建立的 Service Directory 命名空間和服務名稱。
  • METADATA_SERVICE_DIRECTORY_NAMESPACE 和 METADATA_SERVICE_NAME：您為私人背景中繼資料重新整理建立的 Service Directory 命名空間和服務名稱。

Workload Identity Federation

如果使用 Workload Identity Federation，則必須指定 --snowflake-role。

公開網際網路 (無 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="snowflake" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --snowflake-role="SNOWFLAKE_ROLE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_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="snowflake" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --snowflake-role="SNOWFLAKE_ROLE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_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 命名空間和區域密鑰相同。如要盡可能縮短延遲時間：
  • 如果 Snowflake Horizon Catalog 位於 AWS，請選取最接近 AWS 區域的 Google Cloud 區域。
  • 如果 Snowflake Horizon Catalog 位於 Azure，請選取最接近 Azure 區域的 Google Cloud 區域。
  • 如果 Snowflake Horizon Catalog 位於 Google Cloud，請選取完全相同的區域。
• SNOWFLAKE_ACCOUNT_IDENTIFIER：您的 Snowflake 帳戶 ID (例如 myorg-myaccount)。如果您指定 --metadata-service-directory-name 透過 PrivateLink 或 Private Link 同步處理中繼資料，請使用 .privatelink 帳戶 ID (例如 myorg-myaccount.privatelink)。
• SNOWFLAKE_WAREHOUSE：要與之建立聯合查詢的 Snowflake 倉儲。這也稱為 Snowflake Horizon Catalog 中的資料庫名稱。
• SNOWFLAKE_ROLE：工作階段所需的特定 Snowflake 角色。例如：ICEBERG_VIEW。
• REFRESH_INTERVAL：指定背景中繼資料重新整理作業的執行頻率。請將這個值設為時間長度，例如 330s 或 5m30s。
• NAMESPACE_FILTERS：選用：以半形逗號分隔的命名空間清單，用於聯合。例如：ns1,ns2。如果省略，Lakehouse 會納入所有命名空間。
• CROSS_CLOUD_CACHE_MODE：選用，是否在聯合目錄啟用跨雲端快取 (enabled 或 disabled)。預設為 disabled。如果設為 enabled，Lakehouse 會將遠端檔案快取至目錄的Google Cloud 區域。詳情請參閱「智慧型快取」。
• 如果您使用私人互連網路 (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 (PAT)

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

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

授予聯合目錄服務帳戶存取 Secret 的權限：

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets add-iam-policy-binding SNOWFLAKE_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 SNOWFLAKE_SECRET_NAME \
    --project="PROJECT_ID" \
    --location="REGION"

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

Workload Identity Federation

建立目錄後，您必須將其服務帳戶身分連結至 Snowflake 中的服務使用者。

1. 從目錄詳細資料中擷取湖倉服務帳戶 ID (主體)。

   您可以從建立指令的 JSON 回應 (biglake-service-account-id 欄位) 取得這項資訊。

   或者，您也可以對目錄執行 describe 指令，取得這個值：

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

   在輸出內容中尋找 biglake-service-account-id。

2. 登入 Snowflake 管理執行個體，並執行下列指令碼，與 Lakehouse 服務身分建立信任關係：

   USE ROLE ACCOUNTADMIN;
   
   CREATE USER SNOWFLAKE_SERVICE_USER
     TYPE = SERVICE
     WORKLOAD_IDENTITY = (
       TYPE = GCP
       SUBJECT = 'LAKEHOUSE_SERVICE_ACCOUNT_ID'
     )
     DEFAULT_ROLE = SNOWFLAKE_ROLE
     COMMENT = 'Service user for Lakehouse cross-cloud access';
   
   -- Also explicitly GRANT permissions to the role
   GRANT ROLE SNOWFLAKE_ROLE TO USER SNOWFLAKE_SERVICE_USER;

   更改下列內容：

   • SNOWFLAKE_SERVICE_USER：Snowflake 中新服務使用者的名稱。
   • LAKEHOUSE_SERVICE_ACCOUNT_ID：在上一個步驟中擷取的服務帳戶 ID。
   • SNOWFLAKE_ROLE：Snowflake 角色 (必須與建立目錄時指定的角色相符)。

完成私人互連網路設定 (僅限 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"

3. 確認命名空間中的資料表已同步：

   gcloud biglake iceberg tables list \
     --project="PROJECT_ID" \
     --catalog="FEDERATED_CATALOG_NAME" \
     --namespace="NAMESPACE_ID"

後續步驟

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