設定 Snowflake 無邊界湖倉

內部區域 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

以密鑰為準 (PAT)

如果是以祕密金鑰為基礎 (PAT)，您必須使用 Snowflake 產生的長期權杖「個人存取權杖 (PAT)」，以及工作階段所需的特定 Snowflake 角色。

在區域性 Secret Manager 中建立密鑰，以儲存憑證：

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

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

   更改下列內容：

   • SNOWFLAKE_PAT_TOKEN：您的 Snowflake 個人存取權杖 (PAT)。
   • SNOWFLAKE_ROLE：工作階段所需的特定 Snowflake 角色。例如：ICEBERG_VIEW。

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

   Secret Manager 預設會使用全域端點。不過，無邊界 Lakehouse 要求密碼必須與 Lakehouse 目錄儲存在相同區域。如要使用 gcloud CLI 與區域性密鑰互動，您必須覆寫目前工作階段或設定檔的預設 API 端點。為避免連線能力問題，您的 Secret 和目錄必須在同一區域建立。

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

   更改下列內容：

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

3. 將酬載上傳至 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 服務使用者，避免使用長期有效的密碼。建立目錄前，無須在 Secret Manager 中預先設定。繼續建立聯邦目錄。

控制台

如要建立聯合目錄，請按照下列步驟操作：

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

   前往 Lakehouse

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

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

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

4. 在「聯合目錄來源」中，選取「Snowflake Horizon」。

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

   • 如果 Snowflake 目錄位於 AWS，請選取最靠近 AWS 區域的Google Cloud 區域。

6. 按一下「繼續」。

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

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

8. 在「Snowflake warehouse」(Snowflake 倉儲) 欄位中，輸入 Snowflake 倉儲名稱。

9. 根據所選方法設定驗證詳細資料：

   • 以密鑰為準 (PAT)：在「Secret」(密鑰) 中輸入密鑰名稱。請使用下列格式： projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME。
   • Workload Identity Federation：在「Snowflake role」(Snowflake 角色) 欄位中，輸入 Snowflake 角色。例如：ICEBERG_VIEW。

10. 選用：在「Service directory name」(服務目錄名稱) 欄位中，輸入 Service Directory 端點或服務的路徑。如果您要設定私人互連 (Cross-Cloud Interconnect)，才需要執行這項操作。

11. 點選「建立」。

gcloud CLI

gcloud alpha 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 alpha 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/NAMESPACE/services/SERVICE_NAME/endpoints/ENDPOINT_NAME"

gcloud alpha 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 alpha 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/NAMESPACE/services/SERVICE_NAME/endpoints/ENDPOINT_NAME"

REST API

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: PROJECT_ID" \
  -d '{
    "catalog-type": "CATALOG_TYPE_FEDERATED",
    "federated-catalog-options": {
      "snowflake-catalog-info": {
        "account-identifier": "SNOWFLAKE_ACCOUNT_IDENTIFIER",
        "warehouse": "SNOWFLAKE_WAREHOUSE",
        "snowflake-role": "SNOWFLAKE_ROLE"
      },
      "refresh-options": {
        "refresh-schedule": {
          "refresh-interval": "REFRESH_INTERVAL"
        }
      }
    }
}' \
  "https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?iceberg_catalog_id=FEDERATED_CATALOG_NAME&primary_location=REGION"

以密鑰為準 (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 alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
      --project="PROJECT_ID" \
      --location="REGION" \
      --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. 從目錄詳細資料中擷取 Lakehouse 服務帳戶 ID (主體)。

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

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

   gcloud alpha 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 角色 (必須與建立目錄時指定的角色相符)。

gcloud CLI

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

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

2. 確認遠端資料庫結構定義顯示為已同步的命名空間：

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

REST API

1. 驗證目錄聯盟同步狀態：

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME"

2. 列出已同步的命名空間：

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME/namespaces"

3. 列出已同步命名空間中的資料表：

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME/namespaces/NAMESPACE_NAME/tables"