Use GCS offloader with Pulsar

本章将一步一步的指导你完成在 Pulsar 中安装和配置 GCS offloader。

安装

请按照以下步骤安装 GCS offloader。

前提条件

  • Pulsar：2.4.2 或更高版本

步骤

下列示例将使用 Pulsar 2.5.1。

  1. 使用下列方式下载 Pulsar 压缩包：

    • 从 Apache 镜像下载

    • 从 Pulsar 官网 下载页 下载

    • 使用 wget 命令下载：

      1. wget https://archive.apache.org/dist/pulsar/pulsar-2.5.1/apache-pulsar-2.5.1-bin.tar.gz

  2. 下载并解压 Pulsar offloaders 程序包。

    1. wget https://downloads.apache.org/pulsar/pulsar-2.5.1/apache-pulsar-offloaders-2.5.1-bin.tar.gz
    3. tar xvfz apache-pulsar-offloaders-2.5.1-bin.tar.gz

    Note

    • 如果在一个裸机集群中运行 Pulsar，请确保offloaders安装包已经在 broker 的所有 pulsar 目录下解压缩。

    • 如果你在 Docker 中运行 Pulsar 或者通过 Docker 镜像 (如K8s和DCOS) 部署 Pulsar，你可以使用 apachepulsar/pulsar-all 镜像代替 apachepulsar/pulsar 镜像。 apachepulsar/pulsar-all image has already bundled tiered storage offloaders.

  3. 将 Pulsar offloaders 作为offloaders复制到Pulsar目录中。

    1. mv apache-pulsar-offloaders-2.5.1/offloaders apache-pulsar-2.5.1/offloaders
    3. ls offloaders

    输出

    如下中所示，Pulsar 使用 Apache jclouds 来支持 GCS 和AWS S3 进行长期存储。

  1. ```
  2. tiered-storage-file-system-2.5.1.nar
  3. tiered-storage-jcloud-2.5.1.nar
  4. ```

Configuration

Note

在将数据从 BookKeeper 卸载到 GCS 之前，你需要配置 GCS offloader driver 的一些属性。

此外，你还可以配置 GCS offloader 的自动触发和手动触发机制。

配置 GCS offloader driver

你可以在配置文件 broker.conf 或 standalone.conf 中配置 GCS offloader driver。

  • 以下为必选 配置。

    必填 配置 | 描述 | 示例值 |—-|—-|—- managedLedgerOffloadDriver|Offloader driver 名称，不区分大小写|google-cloud-storage offloadersDirectory|Offloader 目录|offloaders gcsManagedLedgerOffloadBucket|Bucket|pulsar-topic-offload gcsManagedLedgerOffloadRegion|Bucket 区域|europe-west3 gcsManagedLedgerOffloadServiceAccountKeyFile|认证 |/Users/user-name/Downloads/project-804d5e6a6f33.json

  • 以下为可选 配置。

    可选配置|描述|示例值 |—-|—-|—- gcsManagedLedgerOffloadReadBufferSizeInBytes|读取数据块的大小|1 MB gcsManagedLedgerOffloadMaxBlockSizeInBytes|写数据块的大小|64 MB managedLedgerMinLedgerRolloverTimeMinutes|一个 Topic 的 Ledger 翻转之间的最小时间|2 managedLedgerMaxEntriesPerLedger|在触发翻转之前追加到 Topic ledger 的最大条目数。|5000

Bucket (必选)

一个 bucket 就是一个存储数据的基本容器。 你存储在 GCS 中的所有东西必须包含在一个 bucket 中。 您可以使用 bucket 来管理数据并控制对数据的访问，但与目录和文件夹不同，你不能嵌套 bucket。

示例

该示例将 bucket 命名为 pulsar-topic-offload。

  1. gcsManagedLedgerOffloadBucket=pulsar-topic-offload

Bucket 区域 (必填)

Bucket 区域是指 Bucket 所处的区域。 如果没有指定 Bucket 区域，则使用默认区域 (us multi-regional location)。

提示

关于 Bucket 位置的更多信息，见这里。

示例

本示例将 Bucket 的区域设置为_ europe-west3 _。

  1. gcsManagedLedgerOffloadRegion=europe-west3

身份验证 (必选)

为了使 broker 访问GCS，你需要在配置文件broker.conf中配置gcsManagedLedgerOffloadServiceAccountKeyFile。

gcsManagedLedgerOffloadServiceAccountKeyFile 是一个JSON文件，它包含一个服务账户的GCS凭证。

示例

要生成服务帐户凭据或查看你已经生成的公共凭据，请遵循以下步骤：

  1. 打开 服务账户页面。

  2. 选择一个项目或创建一个新项目。

  3. Click Create service account.

  4. 在 Create service account 窗口中，输入服务账户的名称并选择 Furnish a new private key。

    如果你想给服务账号 授予 G Suire domain-wide 权限 ，选择 Enable G Suite Domain-wide Delegation。

  5. Click Create.

    Note

    确保你创建的服务账号拥有操作 GCS 的权限，你需要在 这里给你的服务账号指定Storage Admin 权限。

  6. 你可以获得以下信息，并在broker.conf中设置。

    1. gcsManagedLedgerOffloadServiceAccountKeyFile="/Users/user-name/Downloads/project-804d5e6a6f33.json"

    提示

    • 关于如何创建gcsManagedLedgerOffloadServiceAccountKeyFile的更多信息，请参阅这里。

    • 有关Google Cloud IAM的更多信息，请参见这里。

读取/写入的数据块大小

你可以在配置文件 broker.conf 中配置发送到 GCS 或从 GCS 读取的请求大小。

配置|描述 |—-|—- gcsManagedLedgerOffloadReadBufferSizeInBytes| 当从GCS读回数据时，每个数据块大小。

默认值是1 MB。 gcsManagedLedgerOffloadMaxBlockSizeInBytes|在向GCS上传多部分时，”部分 “的最大尺寸。

它不能小于5MB。

默认值为64MB。

配置 GCS offloader 自动运行

命名空间策略可以配置成一旦到达阈值就自动卸载数据。 该阈值基于一个 topic 在 Pulsar 集群的数据存储大小而定。 一旦 topic 到达阈值，就自动触发卸载操作。

阈值|动作 |—-|—-

0 | 如果 topic 存储达到其阈值，它就会触发 offloading 操作。 = 0| 它使 broker 竭尽全力地 offload 数据。 < 0 | 它将禁用自动 offloading 操作。

当一个新 segment 添加到 topic 日志后会自动运行卸载。 如果你在命名空间上设置了阈值，但向该 topic 生产的消息很少，offloader 将会停止工作，直至当前 segment 达到饱和。

你可以通过命令行工具（CLI）设置阈值大小，比如 pulsar-admin。

broker.conf 和 standalone.conf 中的卸载配置文件，主要适用于没有命名空间级别卸载策略的命名空间中。 每个命名空间可以有自己的卸载策略。 如果您想为每个命名空间设置卸载策略，请使用命令 pulsar-admin namespaces set-offload-policies options 。

示例

该示例使用 pulsar-admin 将 GCS offloader 的阈值大小设置为10MB。

  1. pulsar-admin namespaces set-offload-threshold --size 10M my-tenant/my-namespace

提示

关于 pulsar-admin namespaces set-offload-threshold options 命令的更多信息，包括标志、描述、默认值和速记方法，见这里。

配置 GCS offloader 手动运行

对于每一个 topic，你可以使用下列方法来手动触发 GCS offloader：

  • 使用 REST endpoint。

  • 使用命令行工具(例如 pulsar-admin)。

    要想用命令行工具触发 GCS，你需要指定一个 Topic 应该保留在 Pulsar 集群中的最大数据量(阈值)。 如果 Pulsar 集群上 topic 的数据大小超过了这个阈值，那么该 topic 下的 segment 将会被陆续被卸载到 GCS 上，直到不再超过这个阈值。 优先移动旧的 segment。

示例

  • 此示例使用 pulsar-admin 命令 pulsar-admin topics offload (topic-name) (threshold) 手动触发了 GCS offloader 运行。

    1. pulsar-admin topics offload persistent://my-tenant/my-namespace/topic1 10M

    输出

    1. Offload triggered for persistent://my-tenant/my-namespace/topic1 for messages before 2:0:-1

    提示

    关于pulsar-admin topics offload-status options命令的更多信息，包括标志、描述、默认值和速记方法，见这里。

  • 这个例子使用 pulsar-admin 检查 GCS offloader 的状态，命令是 pulsar-admin topics offload-status options。

    1. pulsar-admin topics offload-status persistent://my-tenant/my-namespace/topic1

    输出

    1. Offload is currently running

    要等待 GCS 完成任务，请添加 -w 参数。

    1. pulsar-admin topics offload-status -w persistent://my-tenant/my-namespace/topic1

    输出

    1. Offload was a success

    如果卸载时出现错误，错误会返回到 pulsar-admin topics offload-status 命令。

    1. pulsar-admin topics offload-status persistent://my-tenant/my-namespace/topic1

    输出

    1. Error in offload
    2. null
    4. Reason: Error offloading: org.apache.bookkeeper.mledger.ManagedLedgerException: java.util.concurrent.CompletionException: com.amazonaws.services.s3.model.AmazonS3Exception: Anonymous users cannot initiate multipart uploads.  Please authenticate. (Service: Amazon S3; Status Code: 403; Error Code: AccessDenied; Request ID: 798758DE3F1776DF; S3 Extended Request ID: dhBFz/lZm1oiG/oBEepeNlhrtsDlzoOhocuYMpKihQGXe6EG8puRGOkK6UwqzVrMXTWBxxHcS+g=), S3 Extended Request ID: dhBFz/lZm1oiG/oBEepeNlhrtsDlzoOhocuYMpKihQGXe6EG8puRGOkK6UwqzVrMXTWBxxHcS+g=

    提示

    关于pulsar-admin topics offload-status options命令的更多信息，包括标志、描述、默认值和速记方法，见这里。

教程

有关如何在 Pulsar 中使用 GCS offloader 的完整和分解讲解，请参阅这里。