跳到主要内容
版本：3.0

配置 GCS 认证信息

认证方式介绍​

StarRocks 从 3.0 版本起支持通过以下认证方式访问 Google Cloud Storage（简称 GCS）：

  • 基于 VM 认证鉴权

    使用 Google Cloud Compute Engine 上绑定的凭证对 GCS 进行认证和鉴权。

  • 基于 Service Account 认证鉴权

    使用 Service Account 对 GCS 进行认证和鉴权。

  • 基于 Impersonation 认证鉴权

    使用一个 Service Account 或 VM 实例模拟另一个 Service Account，从实现对 GCS 的认证和鉴权。

应用场景​

StarRocks 支持在以下场景中集成 GCS：

  • 从 GCS 批量导入数据。
  • 从 GCS 备份数据、或把数据恢复到 GCS。
  • 查询 GCS 中的 Parquet 或 ORC 格式的数据文件。
  • 查询 GCS 中的 Hive、Iceberg、Hudi、或 Delta Lake 表。

本文档以 Hive catalog、文件外部表 和 Broker Load 为例，介绍 StarRocks 在各应用场景下如何集成 GCS。有关下面示例中出现的 StorageCredentialParams 详解，参见本文档“参数配置”小节。

说明

由于 Broker Load 只支持通过 gs 协议访问 Google GCS，因此当从 Google GCS 导入数据时，必须确保文件路径中传入的目标文件的 GCS URI 使用 gs:// 作为前缀。

External Catalog​

通过 CREATE EXTERNAL CATALOG 语句创建一个 Hive Catalog hive_catalog_gcs，用以查询 GCS 中的数据文件：

CREATE EXTERNAL CATALOG hive_catalog_gcs
PROPERTIES
(
    "type" = "hive", 
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    StorageCredentialParams
);

文件外部表​

通过 CREATE EXTERNAL TABLE 语句创建一个文件外部表 external_table_gcs，用以查询 GCS 中的数据文件 test_file_external_tbl（GCS 未配置元数据服务）：

CREATE EXTERNAL TABLE external_table_gcs
(
    id varchar(65500),
    attributes map<varchar(100), varchar(2000)>
) 
ENGINE=FILE
PROPERTIES
(
    "path" = "gs:////test-gcs/test_file_external_tbl",
    "format" = "ORC",
    StorageCredentialParams
);

Broker load​

通过 LOAD LABEL 语句创建一个 Broker Load 作业，作业标签为 test_db.label000，用以把 GCS 中的数据批量导入 StarRocks 表 target_table：

LOAD LABEL test_db.label000
(
    DATA INFILE("gs://bucket_gcs/test_brokerload_ingestion/*")
    INTO TABLE target_table
    FORMAT AS "parquet"
)
WITH BROKER
(
    StorageCredentialParams
);

参数配置​

StorageCredentialParams 用于指定 StarRocks 访问 GCS 的相关参数配置。具体包含哪些参数，需要根据所使用的认证方式来确定。

基于 VM 认证鉴权​

如果您将 StarRocks 部署在 Google Cloud Platform（简称 GCP）上的 VM 实例的同时，基于 VM 对 GCS 进行认证和鉴权，请按如下配置 StorageCredentialParams：

"gcp.gcs.use_compute_engine_service_account" = "true"

StorageCredentialParams 包含如下参数。

参数默认值取值样例说明
gcp.gcs.use_compute_engine_service_accountfalsetrue是否直接使用 Compute Engine 上面绑定的 Service Account。

基于 Service Account 认证鉴权​

如果您使用某个 Service Account 对 GCS 进行认证和鉴权，请按如下配置 StorageCredentialParams：

"gcp.gcs.service_account_email" = "<google_service_account_email>",
"gcp.gcs.service_account_private_key_id" = "<google_service_private_key_id>",
"gcp.gcs.service_account_private_key" = "<google_service_private_key>"

StorageCredentialParams 包含如下参数。

参数默认值取值样例说明
gcp.gcs.service_account_email"""user@hello.iam.gserviceaccount.com"创建 Service Account 时生成的 JSON 文件中的 Email。
gcp.gcs.service_account_private_key_id"""61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"创建 Service Account 时生成的 JSON 文件中的 Private Key ID。
gcp.gcs.service_account_private_key"""-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"创建 Service Account 时生成的 JSON 文件中的 Private Key。

基于 Impersonation 认证鉴权​

使用一个 VM 实例模拟一个 Service Account​

如果您将 StarRocks 部署在 GCP 上的 VM 实例的同时，使用该 VM 实例模拟一个 Service Account，从而使 StarRocks 继承该 Service Account 访问 GCS 的权限，请按如下配置 StorageCredentialParams：

"gcp.gcs.use_compute_engine_service_account" = "true",
"gcp.gcs.impersonation_service_account" = "<assumed_google_service_account_email>"

StorageCredentialParams 包含如下参数。

参数默认值取值样例说明
gcp.gcs.use_compute_engine_service_accountfalsetrue是否直接使用 Compute Engine 上面绑定的 Service Account。
gcp.gcs.impersonation_service_account"""hello"需要模拟的目标 Service Account。

使用一个 Service Account 模拟另外一个 Service Account​

如果您使用一个 Service Account（暂时命名为“Meta Service Account”）模拟另外一个 Service Account（暂时命名为“Data Service Account”），从而使 StarRocks 继承该 Data Service Account 访问 GCS 的权限，请按如下配置 StorageCredentialParams：

"gcp.gcs.service_account_email" = "<google_service_account_email>",
"gcp.gcs.service_account_private_key_id" = "<meta_google_service_account_email>",
"gcp.gcs.service_account_private_key" = "<meta_google_service_account_email>",
"gcp.gcs.impersonation_service_account" = "<data_google_service_account_email>"

StorageCredentialParams 包含如下参数。

参数默认值取值样例说明
gcp.gcs.service_account_email"""user@hello.iam.gserviceaccount.com"创建 Meta Service Account 时生成的 JSON 文件中的 Email。
gcp.gcs.service_account_private_key_id"""61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"创建 Meta Service Account 时生成的 JSON 文件中的 Private Key ID。
gcp.gcs.service_account_private_key"""-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"创建 Meta Service Account 时生成的 JSON 文件中的 Private Key。
gcp.gcs.impersonation_service_account"""hello"需要模拟的目标 Data Service Account。