Use AWS S3 offloader with Pulsar

本章将一步一步的指导你完成在 Pulsar 中安装和配置亚马逊 AWS S3 offloader。

安装

请按照以下步骤安装亚马逊 AWS S3 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
    2. tar xvfz apache-pulsar-offloaders-2.5.1-bin.tar.gz

  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 来支持 AWS S3 和 GCS 进行长期存储。

  1. ```
  2. tiered-storage-file-system-2.5.1.nar
  3. tiered-storage-jcloud-2.5.1.nar
  4. ```
  6. > #### Note
  7. > 
  8. > * 如果在一个裸机集群中运行 Pulsar，请确保`offloaders`安装包已经在 broker 的所有 pulsar 目录下解压缩。
  9. > 
  10. > * 如果你在 Docker 中运行 Pulsar 或者通过 Docker 镜像 (如K8s和DCOS) 部署 Pulsar，你可以使用 `apachepulsar/pulsar-all` 镜像代替 `apachepulsar/pulsar` 镜像。 `apachepulsar/pulsar-all` image has already bundled tiered storage offloaders.

Configuration

Note

在将数据从 BookKeeper 转移到 AWS S3 之前，你需要配置 AWS S3 offload 驱动程序的一些属性。

此外，你还可以配置亚马逊 AWS S3 offloader 的自动触发和手动触发机制。

配置亚马逊 AWS S3 offloader driver

你可以在配置文件 broker.conf 或 standalone.conf 中配置亚马逊 AWS offloader driver。

  • 以下为必选 配置。

    所需配置 | 说明 | 示例值 |—-|—-|—- managedLedgerOffloadDriver | Offloader driver 名称，不区分大小写。

    注意：还有第三种驱动类型，S3，它与AWS S3相同，不过S3要求你使用s3ManagedLedgerOffloadServiceEndpoint指定一个端点URL。 如果使用 S3 兼容的数据存储而不是 AWS S3，这会非常有用。 | aws-s3 offloadersDirectory | Offloader 目录 | offloaders s3ManagedLedgerOffloadBucket | Bucket | pulsar-topic-offload

  • 以下为可选 配置。

    可选配置 | 说明 | 示例值 |—-|—-|—- s3ManagedLedgerOffloadRegion | Bucket 区域

    备注：在为这个参数指定一个值之前，你需要设置以下配置。 否则，你可能会得到一个错误。

    - 设置s3ManagedLedgerOffloadServiceEndpoint。

    示例
    s3ManagedLedgerOffloadServiceEndpoint https://s3.YOUR_REGION.amazonaws.com

    - 授予用户GetBucketLocation权限。

    关于如何授予用户GetBucketLocation权限，见这里。| eu-west-3 s3ManagedLedgerOffloadReadBufferSizeInBytes | 读取数据块的大小 | 1 MB s3ManagedLedgerOffloadMaxBlockSizeInBytes | 写数据块的大小 | 64 MB managedLedgerMinLedgerRolloverTimeMinutes | 一个 Topic 的 Ledger 翻转之间的最小时间

    备注: 不建议你在生产环境中设置此配置。|2 managedLedgerMaxEntriesPerLedger | 在触发翻转之前追加到 Ledger 的最大条目数。

    注意：不建议你在生产环境中设置此配置。|5000

Bucket (必选)

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

示例

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

  1. s3ManagedLedgerOffloadBucket=pulsar-topic-offload

Bucket 地区

Bucket 地区是指 bucket 所处的区域。 如果没有指定一个 Bucket 所处的地区，则使用 默认 区域 (US East (N. Virginia))。

提示

关于亚马逊 AWS 地区和 Endpoint 的更多信息，请参阅 这里。

示例

本示例将 Bucket 的地区设置为_ europe-west-3 _。

  1. s3ManagedLedgerOffloadRegion=eu-west-3

身份验证 (必选)

To be able to access AWS S3, you need to authenticate with AWS S3.

Pulsar 没有提供任何直接的方法来配置 AWS S3 的认证。它采用了 DefaultAWSCredentialsProviderChain 的机制来提供支持。

如果你在 AWS IAM 控制台创建了一组认证证书，你可以使用以下方法配置该证书。

  • 使用 EC2 实例元数据认证证书。

    如果你在AWS实例上有一个提供证书的配置文件，并且没有提供其他机制，Pulsar 将使用这些证书。

  • 在conf/pulsar_env.sh 中设置了环境变量 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY。

    “export” 命令很重要，以便变量在生成进程的环境中可用。

    1. export AWS_ACCESS_KEY_ID=ABC123456789
    2. export AWS_SECRET_ACCESS_KEY=ded7db27a4558e2ea8bbf0bf37ae0e8521618f366c

  • 在conf/pulsar_env.sh 中添加Java系统属性 aws.accessKeyId 和 aws.secretKey到PULSAR_EXTRA_OPTS。

    1. PULSAR_EXTRA_OPTS="${PULSAR_EXTRA_OPTS} ${PULSAR_MEM} ${PULSAR_GC} -Daws.accessKeyId=ABC123456789 -Daws.secretKey=ded7db27a4558e2ea8bbf0bf37ae0e8521618f366c -Dio.netty.leakDetectionLevel=disabled -Dio.netty.recycler.maxCapacity.default=1000 -Dio.netty.recycler.linkCapacity=1024"

  • Set the access credentials in ~/.aws/credentials.

    1. [default]
    2. aws_access_key_id=ABC123456789
    3. aws_secret_access_key=ded7db27a4558e2ea8bbf0bf37ae0e8521618f366c

  • 假定一个 IAM 角色.

    本示例使用 DefaultAWSCredentialsProviderChain 来承担这个角色。

    Broker 必须重新启动，才能使 pulsar_env 中指定的证书生效。

    1. s3ManagedLedgerOffloadRole=<aws role arn>
    2. s3ManagedLedgerOffloadRoleSessionName=pulsar-s3-offload

读取/写入的数据块大小

你可以在配置文件broker.conf或standalone.conf中配置发送到亚马逊 AWS S3 或从亚马逊 AWS S3 读取的请求大小。

配置|描述|默认值 |—-|—-|—- s3ManagedLedgerOffloadReadBufferSizeInBytes|从AWS S3读回数据时，每个单独读的块的大小|1 MB s3ManagedLedgerOffloadMaxBlockSizeInBytes|在多部分上传至AWS S3时，每一部分的最大尺寸。 它不能小于5MB。 |64 MB

配置亚马逊 AWS S3 offloader 自动运行

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

阈值|动作 |—-|—-

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

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

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

broker.conf 和 standalone.conf 中的卸载配置文件，主要适用于没有命名空间级别卸载策略的命名空间中。 每个命名空间可以有自己的卸载策略。 If you want to set offload policy for each namespace, use the command pulsar-admin namespaces set-offload-policies options command.

示例

该示例使用 pulsar-admin 将亚马逊 AWS S3 offloader 的阈值大小设置为10MB。

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

提示

For more information about the pulsar-admin namespaces set-offload-threshold options command, including flags, descriptions, and default values, see here.

配置亚马逊 AWS S3 offloader 手动运行

对于每一个 topic，你可以使用下列方法来手动触发亚马逊 AWS S3 offloader：

  • 使用 REST endpoint。

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

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

示例

  • 该示例使用 pulsar-admin 手动触发了亚马逊 AWS S3 offloader 的运行。

    1. bin/pulsar-admin topics offload --size-threshold 10M my-tenant/my-namespace/topic1

    输出

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

    提示

    For more information about the pulsar-admin topics offload options command, including flags, descriptions, and default values, see here.

  • 该示例使用 pulsar-admin 检查亚马逊 AWS S3 offloader 的状态。

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

    输出

    1. Offload is currently running

    要等待亚马逊 AWS S3 offloader 完成任务，请添加 -w 参数。

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

    输出

    1. Offload was a success
  1. 如果卸载时出现错误，错误会返回到 `pulsar-admin topics offload-status` 命令。
  3. ```bash
  4. bin/pulsar-admin topics offload-status persistent://my-tenant/my-namespace/topic1
  5. ```
  7. **输出**
  1. 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= `
  1. > #### 提示
  2. > 
  3. > For more information about the `pulsar-admin topics offload-status options` command, including flags, descriptions, and default values, see [here](https://pulsar.apache.org/tools/pulsar-admin/2.6.0-SNAPSHOT/#-em-offload-status-em-).

教程

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