Kafka Connect官网说明

Posted 2021-08-13 顧棟

文章目录

• Kafka Connect
• • Overview
  • 运行Kafka Connect
  • 配置 Connectors
  • Transformations
  • REST API

Kafka Connect

原文地址：http://kafka.apache.org/11/documentation.html#connect

Overview

Kafka Connect 是一种用于在 Apache Kafka 和其他系统之间可扩展且可靠地流式传输数据的工具。 它使快速定义将大量数据移入和移出 Kafka 的连接器变得简单。 Kafka Connect 可以摄取整个数据库或从所有应用程序服务器收集指标到 Kafka 主题中，使数据可用于低延迟的流处理。 导出作业可以将数据从 Kafka 主题传送到二级存储和查询系统或批处理系统进行离线分析。

Kafka Connect 功能包括：

• Kafka 连接器的通用框架 - Kafka Connect 标准化了其他数据系统与 Kafka 的集成，简化了连接器的开发、部署和管理
• 分布式和独立模式 - 向上扩展为支持整个组织的大型集中管理服务，或向下扩展为开发、测试和小型生产部署
• REST 接口 - 通过易于使用的 REST API 提交和管理到 Kafka Connect 集群的连接器
• 自动偏移管理 - 只需来自连接器的少量信息，Kafka Connect 就可以自动管理偏移提交过程，因此连接器开发人员无需担心连接器开发中这个容易出错的部分
• 默认情况下分布式和可扩展 - Kafka Connect 建立在现有的组管理协议上。可以添加更多工作人员来扩展 Kafka Connect 集群。
• 流/批处理集成 - 利用 Kafka 的现有功能，Kafka Connect 是桥接流和批处理数据系统的理想解决方案

运行Kafka Connect

Kafka Connect 目前支持两种执行模式：独立（单进程）和分布式。

在独立模式下，所有工作都在单个进程中执行。 此配置更易于设置和入门，并且在只有一个 worker 有意义的情况下可能很有用（例如收集日志文件），但它无法从 Kafka Connect 的某些功能（例如容错）中受益。 您可以使用以下命令启动独立进程：

> bin/connect-standalone.sh config/connect-standalone.properties connector1.properties [connector2.properties ...]

第一个参数是worker的配置。 这包括诸如 Kafka 连接参数、序列化格式以及提交偏移的频率等设置。 提供的示例应该适用于使用config/server.properties提供的默认配置运行的本地集群。 它需要调整以用于不同的配置或生产部署。 所有workers（独立的和分布式的）都需要一些配置：

• bootstrap.servers: 用于引导到 Kafka 的连接的 Kafka 服务器列表
• key.converter:Converter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化格式之间进行转换。 这控制了写入 Kafka 或从 Kafka 读取的消息中密钥的格式，并且由于它独立于连接器，因此它允许任何连接器使用任何序列化格式。 常见格式的示例包括 JSON 和 Avro。
• value.converter:Converter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化格式之间进行转换。 这控制了写入 Kafka 或从 Kafka 读取的消息中值的格式，并且由于它独立于连接器，因此它允许任何连接器使用任何序列化格式。 常见格式的示例包括 JSON 和 Avro。

特定于独立模式的重要配置选项是：

offset.storage.file.filename:用于存储偏移数据的文件

此处配置的参数供Kafka Connect 使用的生产者和消费者访问配置、偏移和状态主题。 配置Kafka源任务使用的生产者和Kafka接收任务使用的消费者，可以使用相同的参数，但需要分别加上前缀producer. 和consumer.。 唯一从工作配置中没有前缀继承的 Kafka 客户端参数是bootstrap.servers，这在大多数情况下就足够了，因为同一个集群通常用于所有目的。 一个值得注意的例外是安全集群，它需要额外的参数来允许连接。 这些参数最多需要在 worker 配置中设置三次，一次用于管理访问，一次用于 Kafka sources ，一次用于 Kafka sinks。

其余参数是连接器配置文件。 您可以根据需要包含任意数量的内容，但所有内容都将在同一进程中（在不同线程上）执行。

分布式模式处理工作的自动平衡，允许您动态扩展（或缩减），并在活动任务以及配置和偏移提交数据中提供容错。 执行与独立模式非常相似：

> bin/connect-distributed.sh config/connect-distributed.properties

不同之处在于启动的类和更改 Kafka Connect 进程如何决定存储配置、如何分配工作以及存储偏移量和任务状态的配置参数。 在分布式模式下，Kafka Connect 将偏移量、配置和任务状态存储在 Kafka 主题中。 建议手动创建偏移、配置和状态的主题，以达到所需的分区数和复制因子。 如果在启动 Kafka Connect 时尚未创建主题，将使用默认分区数和复制因子自动创建主题，这可能不适合其使用。

特别是，除了上面提到的常用设置之外，以下配置参数在启动集群之前设置至关重要：

group.id(default connect-cluster):集群的唯一名称，用于形成 Connect 集群组； 请注意，这不能与消费者组 ID 冲突

config.storage.topic (default connect-configs) :用于存储连接器和任务配置的主题； 请注意，这应该是单个分区、高度复制、压缩的主题。 您可能需要手动创建主题以确保正确配置，因为自动创建的主题可能有多个分区或自动配置为删除而不是压缩

offset.storage.topic (default connect-offsets) :用于存储偏移量的主题； 这个主题应该有很多分区，被复制，并被配置为压缩

status.storage.topic (default connect-status):用于存储状态的主题； 这个主题可以有多个分区，并且应该被复制并配置为压缩

请注意，在分布式模式下，连接器配置不会在命令行上传递。 相反，使用下面描述的 REST API 来创建、修改和销毁连接器。

配置 Connectors

连接器配置是简单的键值映射。 对于独立模式，这些在属性文件中定义并通过命令行传递给 Connect 进程。 在分布式模式下，它们将包含在创建（或修改）连接器的请求的 JSON 负载中。

大多数配置都依赖于连接器，因此无法在此处进行概述。 但是，有一些常见的选项：

• name - 连接器的唯一名称。 尝试使用相同名称再次注册将失败。
• connector.class - 连接器的 Java 类
• tasks.max - 应为此连接器创建的最大任务数。 如果连接器无法达到这种并行度级别，它可能会创建更少的任务。
• key.converter - (optional) 覆盖设置的默认key转换器。
• value.converter - (optional) 覆盖设置的默认value 转换器。

connector.class 配置支持多种格式：此连接器的类的全名或别名。 如果连接器是 org.apache.kafka.connect.file.FileStreamSinkConnector，则可以指定此全名或使用 FileStreamSink 或 FileStreamSinkConnector 使配置更短一些。

Sink connectors also have a few additional options to control their input. Each sink connector must set one of the following:

Sink 连接器还有一些额外的选项来控制它们的输入。 每个 sink connector必须设置以下之一：

• topics - 用作此连接器输入的主题的逗号分隔列表
• topics.regex - 用作此连接器输入的主题的 Java 正则表达式

对于任何其他选项，您应该查阅connector的文档。

Transformations

连接器可以配置转换以进行轻量级的消息一次修改。 它们可以方便地进行数据按摩和事件路由。

可以在连接器配置中指定转换链。

• transforms - 转换的别名列表，指定应用转换的顺序。
• transforms.$alias.type -转换的完全限定类名
• transforms.$alias.$transformationSpecificConfig 转换的配置属性

例如，让我们使用内置的文件源连接器并使用转换来添加静态字段。

在整个示例中，我们将使用无模式 JSON 数据格式。 为了使用无模式格式，我们将connect-standalone.properties中的以下两行从 true 更改为 false：

        key.converter.schemas.enable
        value.converter.schemas.enable

文件源连接器将每一行作为字符串读取。 我们将每一行包装在一个 Map 中，然后添加第二个字段来标识事件的来源。 为此，我们使用两个转换：

• HoistField 将输入行放置一个Map中
• InsertField 添加静态字段。 在此示例中，我们将指示记录来自文件连接器

After adding the transformations, connect-file-source.properties file looks as following:

        name=local-file-source
        connector.class=FileStreamSource
        tasks.max=1
        file=test.txt
        topic=connect-test
        transforms=MakeMap, InsertSource
        transforms.MakeMap.type=org.apache.kafka.connect.transforms.HoistField$Value
        transforms.MakeMap.field=line
        transforms.InsertSource.type=org.apache.kafka.connect.transforms.InsertField$Value
        transforms.InsertSource.static.field=data_source
        transforms.InsertSource.static.value=test-file-source

All the lines starting with transforms were added for the transformations. You can see the two transformations we created: “InsertSource” and “MakeMap” are aliases that we chose to give the transformations. The transformation types are based on the list of built-in transformations you can see below. Each transformation type has additional configuration: HoistField requires a configuration called “field”, which is the name of the field in the map that will include the original String from the file. InsertField transformation lets us specify the field name and the value that we are adding.

所有以 transforms 开头的行都是为转换添加的。 您可以看到我们创建的两个转换：“InsertSource”和“MakeMap”是我们为转换选择的别名。 转换类型基于您可以在下面看到的内置转换列表。 每个转换类型都有额外的配置：HoistField 需要一个名为“字段”的配置，它是映射中字段的名称，它将包含文件中的原始字符串。 InsertField 转换让我们指定要添加的字段名称和值。

When we ran the file source connector on my sample file without the transformations, and then read them using kafka-console-consumer.sh, the results were:

当我们在没有转换的示例文件上运行文件源连接器，然后使用 kafka-console-consumer.sh 读取它们时，结果是：

        "foo"
        "bar"
        "hello world"

We then create a new file connector, this time after adding the transformations to the configuration file. This time, the results will be:

然后我们创建一个新的文件连接器，这次是在将转换添加到配置文件之后。 这一次，结果将是：

        {"line":"foo","data_source":"test-file-source"}
        {"line":"bar","data_source":"test-file-source"}
        {"line":"hello world","data_source":"test-file-source"}

You can see that the lines we’ve read are now part of a JSON map, and there is an extra field with the static value we specified. This is just one example of what you can do with transformations.

您可以看到我们读取的行现在是 JSON 映射的一部分，并且有一个带有我们指定的静态值的额外字段。 这只是您可以使用转换执行的操作的一个示例。

Several widely-applicable data and routing transformations are included with Kafka Connect:

Kafka Connect 包含几个广泛适用的数据和路由转换：

• InsertField - Add a field using either static data or record metadata 使用静态数据或记录元数据添加字段
• ReplaceField - Filter or rename fields 过滤或重命名字段
• MaskField - Replace field with valid null value for the type (0, empty string, etc) 将字段替换为类型的有效空值（0、空字符串等）
• ValueToKey
• HoistField - Wrap the entire event as a single field inside a Struct or a Map 将整个事件包装为 Struct 或 Map 中的单个字段
• ExtractField - Extract a specific field from Struct and Map and include only this field in results 从 Struct 和 Map 中提取特定字段并在结果中仅包含该字段
• SetSchemaMetadata - 修改schema名称或者版本
• TimestampRouter - Modify the topic of a record based on original topic and timestamp. Useful when using a sink that needs to write to different tables or indexes based on timestamps 根据原始主题和时间戳修改记录的主题。 在使用需要根据时间戳写入不同表或索引的接收器时很有用
• RegexRouter - modify the topic of a record based on original topic, replacement string and a regular expression 根据原始主题、替换字符串和正则表达式修改记录的主题

下面列出了有关如何配置每个转换的详细信息：

org.apache.kafka.connect.transforms.InsertField

org.apache.kafka.connect.transforms.ReplaceField

org.apache.kafka.connect.transforms.MaskField

org.apache.kafka.connect.transforms.ValueToKey

org.apache.kafka.connect.transforms.HoistField

org.apache.kafka.connect.transforms.ExtractField

org.apache.kafka.connect.transforms.SetSchemaMetadata

org.apache.kafka.connect.transforms.TimestampRouter

org.apache.kafka.connect.transforms.RegexRouter

org.apache.kafka.connect.transforms.Flatten

org.apache.kafka.connect.transforms.Cast

org.apache.kafka.connect.transforms.TimestampConverter

REST API

由于 Kafka Connect 旨在作为服务运行，因此它还提供了用于管理连接器的 REST API。 可以使用listeners配置选项配置 REST API 服务器。 此字段应包含以下格式的侦听器列表：protocol://host:port,protocol2://host2:port2。 当前支持的协议是 http 和 https。

        listeners=http://localhost:8080,https://localhost:8443

默认情况下，如果未指定listeners，则 REST 服务器使用 HTTP 协议在端口 8083 上运行。 使用 HTTPS 时，配置必须包含 SSL 配置。 默认情况下，它将使用 ssl.* 设置。 如果需要为 REST API 使用不同的配置而不是连接到 Kafka 代理，这些字段可以以listeners.https 为前缀。 使用前缀时，只会使用带前缀的选项，没有前缀的 ssl.* 选项将被忽略。 以下字段可用于为 REST API 配置 HTTPS：

• ssl.keystore.location
• ssl.keystore.password
• ssl.keystore.type
• ssl.key.password
• ssl.truststore.location
• ssl.truststore.password
• ssl.truststore.type
• ssl.enabled.protocols
• ssl.provider
• ssl.protocol
• ssl.cipher.suites
• ssl.keymanager.algorithm
• ssl.secure.random.implementation
• ssl.trustmanager.algorithm
• ssl.endpoint.identification.algorithm
• ssl.client.auth

REST API 不仅被用户用来监控/管理 Kafka Connect。 它也用于 Kafka Connect 跨集群通信。 在follower 节点 REST API 上收到的请求将转发到领导者节点 REST API。 如果给定主机可达的 URI 与其侦听的 URI 不同，则可以使用配置选项 rest.advertised.host.name、rest.advertised.port 和 rest.advertised.listener 来更改 URI 将被follower 节点用于与leader连接。 当同时使用 HTTP 和 HTTPS 侦听器时，rest.advertised.listener 选项还可用于定义将用于跨集群通信的侦听器。 当使用 HTTPS 进行节点之间的通信时，将使用相同的ssl.* 或listeners.https 选项来配置 HTTPS 客户端。

以下是当前支持的 REST API :

REST API	说明
GET /connectors	返回活动连接器列表
POST /connectors	创建一个新的连接器； 请求正文应该是一个 JSON 对象，其中包含一个字符串name字段和一个带有连接器配置参数的对象config字段
GET /connectors/{name}	获取有关特定连接器的信息
GET /connectors/{name}/config	获取特定连接器的配置参数
PUT /connectors/{name}/config	更新特定连接器的配置参数
GET /connectors/{name}/status	获取连接器的当前状态，包括它是否正在运行、失败、暂停等，它被分配给哪个worker ，如果失败则错误信息，以及其所有任务的状态
GET /connectors/{name}/tasks	获取当前为连接器运行的任务列表
GET /connectors/{name}/tasks/{taskid}/status	获取任务的当前状态，包括它是否正在运行、失败、暂停等，它被分配给哪个worker ，如果失败则错误信息
PUT /connectors/{name}/pause	暂停连接器及其任务，这会停止消息处理，直到连接器恢复
PUT /connectors/{name}/resume	恢复暂停的连接器（如果连接器未暂停，则不执行任何操作）
POST /connectors/{name}/restart	重新启动连接器（通常是因为它失败了）
POST /connectors/{name}/tasks/{taskId}/restart	重新启动单个任务（通常是因为它失败了）
DELETE /connectors/{name}	删除连接器，停止所有任务并删除其配置

Kafka Connect 还提供了一个 REST API 来获取有关连接器插件的信息：

• GET /connector-plugins 返回安装在 Kafka Connect 集群中的连接器插件列表。 请注意，API 仅检查处理请求的工作线程上的连接器，这意味着您可能会看到不一致的结果，尤其是在滚动升级期间，如果您添加新的连接器 jar

• PUT /connector-plugins/{connector-type}/config/validate 根据配置定义验证提供的配置值。 此 API 执行每个配置验证，在验证期间返回建议值和错误消息。