為 Snowflake Horizon Catalog 設定跨雲端連線

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

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

設定 AWS 網路

首先，建立 Amazon S3 VPC 介面端點 (AWS PrivateLink)：

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

接著，設定安全性群組：

• 請確認附加至 Amazon S3 端點 ENI 的安全性群組，允許來自 Google Cloud 虛擬私有雲的傳入 TCP 流量透過通訊埠 443傳輸。這項設定必須包含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 VPC 端點 (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 介面虛擬私有雲端點 IP 位址，請按照下列步驟操作：

1. 在 AWS VPC 中，為 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 介面虛擬私有雲端點的轉送資訊：

   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 介面虛擬私有雲端點的 IP 位址。例如：10.0.1.45。
   • S3_VPCE_PORT：Amazon S3 介面虛擬私有雲端點的通訊埠編號。例如：443。
   • PROJECT_NUMBER：您的 Google Cloud專案編號。在 --network 旗標中使用專案編號。
   • VPC_NETWORK：與私密互連網路相關聯的 Google Cloud 虛擬私有雲網路名稱。

Secret-based (PAT)

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

1. 產生程式輔助存取權杖 (PAT)，並授予目標目錄的讀取權限。

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

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

   更改下列內容：

   • SNOWFLAKE_PAT_TOKEN：Snowflake 程式輔助存取權杖 (PAT)。
   • SNOWFLAKE_ROLE：工作階段所需的特定 Snowflake 角色。例如：ICEBERG_VIEW。

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

   Secret Manager 預設會使用全域端點。不過，Lakehouse 要求密鑰必須與 Lakehouse 目錄儲存在相同區域。如要使用 gcloud 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 服務使用者，避免使用長期密鑰。無須預先設定。繼續建立聯合目錄。

控制台

如何建立聯合目錄：

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

   前往 Lakehouse

2. 按一下「add_box Create catalog」(建立目錄)。

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

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

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

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

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

6. 按一下「繼續」。

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

7. 在「Remote catalog details」(遠端目錄詳細資料) 區段的「Snowflake account identifier」(Snowflake 帳戶 ID) 欄位中，輸入 Snowflake 帳戶 ID。例如：my_org-my_account。

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

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

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

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

11. 點選「建立」。

gcloud

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"

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

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"

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

Secret-based (PAT)

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

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

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

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 federation over WIF';
   
   -- 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 角色 (必須與建立目錄時指定的角色相符)。

控制台

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

   前往「IAM」頁面

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

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

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

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

6. 按一下 [儲存]。

gcloud

將必要角色授予目錄的服務帳戶：

# 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"