kafka connect userguide【confluence】

https://docs.confluent.io/current/connect/userguide.html

本文档提供了关于如何开始使用Kafka Connect的信息。在开始之前，您应该阅读并理解Kafka Connect的概念（Kafka Connect Concepts）。本文件涵盖以下主题:

• Deployment Considerations
• Running Workers and Worker Configuration Properties
• Configuring Key and Value Converters
• Connect Producers and Consumers

部署注意事项

启动 Kafka Connect 只有一个先决条件：一组 kafka broker。这些Kafka broker可以是更早的broker版本，也可以是最新的版本，有关详细信息，请参阅跨组件兼容性（Cross-Component Compatibility）

Confluent Schema Registry

尽管模式注册表（ Schema Registry）不是Kafka Connect所必需的服务，但它使您能够轻松地使用Avro、Protobuf和JSON模式作为连接器读取和写入Kafka记录的通用数据格式。这使得编写自定义代码的需求最小化，并以灵活的格式标准化数据。

关更多信息，请参见 Using Kafka Connect with Schema Registry and Configuring Key and Value Converters.

单机模式 vs. 分布式模式

Connectors 和tasks 是工作的逻辑单元，运行在一个进程上。这个进程在Kafka Connect中被称为 worker 。运行works 有两种模式：独立模式和分布式模式。在开始之前，您应该确定哪种模式最适合您的环境

独立模式对于在本地机器上开发和测试Kafka Connect非常有用。它还可以用于通常使用单个代理的环境(例如，将web服务器日志发送到Kafka)

分布式模式在多台机器(节点)上运行Connect workers。这些组成了一个Connect cluster。Kafka Connect 把running connectors 分配到Connect cluster 中的各个节点。您可以根据需要添加更多节点或删除节点

分布式模式还具有更强的容错能力。如果一个节点意外地离开集群，Kafka Connect会自动将该节点的工作分配给集群中的其他节点。而且，因为Kafka Connect将连接器配置、状态和偏移量信息存储在Kafka集群中，并且可以安全地复制这些信息，所以丢失Connect worker运行的节点不会导致任何数据丢失

操作环境

Workers是JVM进程，可以在具有足够资源的共享机器上运行。workers 的硬件需求类似于标准Java生产者和消费者的硬件需求。资源需求主要取决于workers 操作的连接器的类型。发送大消息的环境需要更多内存。持续使用压缩需要更强大的CPU

Tip

如果在一台机器上同时运行多个worker，请确保了解资源限制(CPU和内存)。从默认堆大小设置开始，并监视内部指标和系统。验证CPU、内存和网络(10GbE或更大)对于负载是否足够

Running Workers

Standalone 模式

 独立模式通常用于开发和测试，或者用于轻量级的单代理环境(例如，将web服务器日志发送到Kafka)。下面显示了以独立模式启动worker 的示例命令

bin/connect-standalone worker.properties connector1.properties [connector2.properties connector3.properties ...]

第一个参数（worker.properties)是 worker configuration properties 文件，注意：worker.properties 是一个示例文件名

第二个参数（connect1.properties)是 connector configuration properties 文件，所有connecters 都具有由worker 加载的配置属性。如示例所示，您可以使用此命令启动多个连接器

如果您在同一台主机上运行多个 standalone workers，以下两个配置属性对于每个worker 必须是惟一的

offset.storage.file.filename：连接器偏移量的存储文件名。此文件以独立模式存储在本地文件系统上。如果两个worker使用相同的文件名，将导致偏移量值被删除或覆盖

rest.port：监听HTTP请求的端口。对于在一台主机上运行的每个worker，这必须是唯一的。

Distributed 模式

Connect在几个Kafka主题中存储connector 和task 配置、偏移量和状态。这些被称为Kafka Connect 的内部主题。这些内部主题必须具有较高的复制因子、压缩清理策略和适当的分区数量，这一点很重要。

Kafka Connect 可以在启动时自动创建内部主题，使用Connect distributed worker 配置属性为这些主题指定主题名称、复制因子和分区数量。Connect验证属性是否满足要求，并使用压缩清理策略创建所有主题。

建议允许Connect自动创建这些内部主题。但是，您可能希望手动创建主题。下面提供了手动创建这些主题的两个示例

• 出于安全考虑，可以将Broker 配置为不允许像Connect这样的客户机创建Kafka主题
• 您可能需要其他高级特定主题的设置，这些设置不是由Connect自动设置的，或者与自动创建的设置不同

下面的示例命令展示了如何在启动Connect 之前手动创建压缩和复制的Kafka主题。在输入参数时，确保遵循 distributed worker 

# config.storage.topic=connect-configs
bin/kafka-topics --create --bootstrap-server localhost:9092 --topic connect-configs --replication-factor 3 --partitions 1 --config cleanup.policy=compact

# offset.storage.topic=connect-offsets
bin/kafka-topics --create --bootstrap-server localhost:9092 --topic connect-offsets --replication-factor 3 --partitions 50 --config cleanup.policy=compact

# status.storage.topic=connect-status
bin/kafka-topics --create --bootstrap-server localhost:9092 --topic connect-status --replication-factor 3 --partitions 10 --config cleanup.policy=compact

注意：Connect cluster 中的所有workers 使用相同的内部主题。不同cluster 中的workers 必须使用不同的内部主题，Distributed Configuration Properties 查看详情。

除了加载worker 配置文件外，分布式模式没有任何其他命令行参数。新workers  将创建一个新的组，或者使用匹配的group.id 加入一个现有的组。然后Workers 与consumer groups 协调，分配要做的工作。有关如何添加new workers 的详细信息，请参阅 Distributed Configuration Properties

下面显示了以分布式模式启动worker 的示例命令

bin/connect-distributed worker.properties

在独立模式下，连接器配置属性文件被添加为commman-line参数。然而，在分布式模式中，连接器是使用REST API请求部署和管理的。要创建连接器，您需要启动worker，然后发出一个REST请求来创建连接器。

如果您在一台主机上运行多个distributed workers 进行开发和测试， rest.port属性对于每个worker必须是唯一的。这是监听HTTP请求的端口

Worker 配置属性

无论使用何种模式，Kafka Connect worker 都是通过传递 worker 配置属性文件作为第一个参数来配置的。例如

bin/connect-distributed worker.properties

示例worker配置属性文件包含在Confluent Platform中，以帮助您入门。下面列出了Avro示例文件的位置

• etc/schema-registry/connect-avro-distributed.properties
• etc/schema-registry/connect-avro-standalone.properties

使用这些文件中的一个作为入门。这些文件包含如何使用与 Schema Registry 集成的Avro converters 的必要配置属性。它们被配置为能够很好地与本地运行的Kafka和Schema Registry 服务一起工作。它们只需要运行在一个broker 上，使您可以轻松地在本地测试 Kafka Connect。

当进行生产部署时，可以修改示例配置文件，方法是为Kafka 和Schema Registry 使用正确的主机名，并为内部主题复制因子使用可接受(或默认)的值。

通用配置属性

下面是您启动时需要配置的几个常见配置属性。在 Kafka Connect Worker Configs 中提供了更多的配置选项

bootstrap.servers

Since these servers are just used for the initial connection to discover the full cluster membership (which may change dynamically), this list need not contain the full set of servers (you may want more than one though, in case a server is down)

• Type: list
• Default: [localhost:9092]
• Importance: high

host1:port1,host2:port2,...

key.converter

Converter class for key Connect data，This controls the format of the data that will be written to Kafka for source connectors or read from Kafka for sink connectors，Popular formats include Avro and JSON

• Type: class
• Default:
• Importance: high

value.converter

Converter class for value Connect data，This controls the format of the data that will be written to Kafka for source connectors or read from Kafka for sink connectors，Popular formats include Avro and JSON

• Type: class
• Default:
• Importance: high

rest.host.name

Hostname for the REST API. If this is set, it will only bind to this interface.

• Type: string
• Importance: low

rest.port

Port for the REST API to listen on.

• Type: int
• Default: 8083
• Importance: low

plugin.path

The comma-separated list of paths to directories that contain Kafka Connect plugins.

• Type: string
• Default:
• Importance: low

Distributed 配置属性

配置相同 group.id 的Distributed Workers 可以自动发现彼此的存在，从而组成一个Kafka Connect cluster，集群中的所有worker 使用相同的三个内部Kafka主题来共享连接器配置、偏移量数据和状态更新。因此，同一个 Connect cluster 中的所有worker 的配置中的config.storage.topic,offset.storage.topic, and status.storage.topic 三个属性必须一致。

• config.storage.replication.factor
• offset.storage.replication.factor
• offset.storage.partitions
• status.storage.replication.factor
• status.storage.partitions

当每个分布式worker 启动时，它使用内部的Kafka主题(如果它们已经存在)。如果没有，worker 将尝试使用worker configuration properties 创建主题。这为您提供了在启动Kafka Connect之前手动创建这些主题的选项，如果您需要特定主题的设置，或者Kafka Connect没有创建主题所需的特权。如果您手动创建主题，请确保遵循 configuration properties 列表中提供的指导原则

如果需要创建独立于现有Connect cluster 的分布式worker，则必须创建新的worker配置属性。以下配置属性必须与现有集群中使用的worker配置不同　　

• group.id
• config.storage.topic
• offset.storage.topic
• status.storage.topic

Important

• Connect clusters 间不共享Group IDs or internal topics，简单地更改 group.id不会从已有的Connect cluster 创建一个新的worker，新的 group.id必须关联唯一的internal topics（ 需要给新的group.id设置 config.storage.topicoffset.storage.topic, and status.storage.topic 这些配置属性）
• 你也必须使用不同于已存在的Connect cluster 中的connector names，因为consumer group 基于connector name 创建出来，一个Connect cluster中的每一个connector 共享同一个 consumer group

The following lists and defines the distributed worker properties:

group.id

A unique string that identifies the Connect cluster group this worker belongs to.

• Type: string
• Default: connect-cluster
• Importance: high

config.storage.topic

The name of the topic where connector and task configuration data are stored. This must be the same for all workers with the same group.id

当启动时，Kafka Connect尝试用单分区和压缩的清理策略自动创建这个主题，以避免丢失数据。它使用现有的主题(如果存在)。如果选择手动创建此主题，请始终将其创建为具有单个分区和高复制因子(3倍或更多)的压缩主题

• Type: string
• Default: “”
• Importance: high

config.storage.replication.factor

This should always be at least 3 for a production system, but cannot be larger than the number of Kafka brokers in the cluster

• Type: short
• Default: 3
• Importance: low

offset.storage.topic

The name of the topic where connector and task configuration offsets are stored. This must be the same for all workers with the same group.id

当启动时，Kafka Connect尝试用多个分区和一个紧凑的清理策略自动创建这个主题，以避免丢失数据。它使用现有的主题(如果存在)。如果您选择手动创建此主题，请始终将其创建为一个压缩的、高复制因子的(3倍或更多)主题，带有大量分区，以支持大型Kafka Connect clusters (即25或50个分区，就像Kafka内置的由consumer_offsets主题一样)

• Type: string
• Default: “”
• Importance: high

offset.storage.replication.factor

This should always be at least 3 for a production system, but cannot be larger than the number of Kafka brokers in the cluster.

• Type: short
• Default: 3
• Importance: low

offset.storage.partitions

A large value is necessary to support large Kafka Connect clusters (that is, 25 or 50 partitions like the Kafka built-in __consumer_offsets topic)

• Type: int
• Default: 25
• Importance: low

status.storage.topic

The name of the topic where connector and task configuration status updates are stored. This must be the same for all workers with the same group.id.

在启动时，Kafka Connect尝试用多个分区和一个紧凑的清理策略自动创建这个主题，以避免丢失数据。它使用现有的主题(如果存在)。如果选择手动创建此主题，请始终将其创建为具有多个分区的压缩、高复制因子(3倍或更多)的主题

• Type: string
• Default: “”
• Importance: high

status.storage.replication.factor

This should always be at least 3 for a production system, but cannot be larger than the number of Kafka brokers in the cluster.

• Type: short
• Default: 3
• Importance: low

status.storage.partitions

The number of partitions used when Connect creates the topic used to store connector and task status updates.

• Type: int
• Default: 5
• Importance: low

Standalone 配置属性

除了常见的worker配置选项之外，以下属性在独立模式下也是可用的

offset.storage.file.filename

用于存储连接器偏移量的文件。通过在磁盘上存储偏移量，可以在单个节点上停止和启动独立进程，并在之前停止的地方恢复

• Type: string
• Default: “”
• Importance: high

有关其他配置属性，请参阅以下部分

• Connect and Schema Registry: See Using Kafka Connect with Schema Registry.
• Producer configuration properties: See Kafka Producer.
• Consumer configuration properties: See Kafka Consumer.
• All Kafka configuration properties: See Confluent Platform Configuration Reference

配置Key 和 Value Converters

Confluent  平台下打包好的的converters 如下：

• AvroConverter io.confluent.connect.avro.AvroConverter: use with Schema Registry
• ProtobufConverter io.confluent.connect.protobuf.ProtobufConverter: use with Schema Registry
• JsonSchemaConverter io.confluent.connect.json.JsonSchemaConverter: use with Schema Registry
• JsonConverter org.apache.kafka.connect.json.JsonConverter (without Schema Registry): use with structured data
• StringConverter org.apache.kafka.connect.storage.StringConverter: simple string format
• ByteArrayConverter org.apache.kafka.connect.converters.ByteArrayConverter: provides a “pass-through” option that does no conversion

所有连接器的默认转换器都在worker配置中指定。但是，任何连接器都可以通过定义key, value转换器来覆盖默认转换器。建议在worker 中定义大多数连接器都可以使用的默认key, value转换器，然后在连接器的自身配置中定义自定义转换器。

Important

worker configuration 中的转换器配置属性由运行在该工作程序上的所有连接器使用，除非将转换器添加到连接器配置中

如果将转换器添加到连接器配置中，worker 配置中所有已添加的转换器配置(以 key.converter.* 和/或 value.converter.* 为前缀的那些配置) 就不会被用到了。在向连接器配置中添加转换器时要小心。

例如，如果worker配置中存在以下值转换器属性：

value.converter=io.confluent.connect.avro.AvroConverter
value.converter.schema.registry.url=http://localhost:8081

 

同时将以下属性添加到连接器配置中：

{
 "value.converter": "AvroConverter",
 "value.converter.basic.auth.credentials.source": "USER_INFO",
 "value.converter.basic.auth.user.info": "<username>:<password>"
}

 

启动连接器时将出现错误，因为所需的Schema Registry URL 属性 value.converter.schema.registry.url=http://localhost:8081 没有提供给转换器.

 下面的部分提供了转换器的描述和示例。有关这些转换器在Schema Registry 中如何工作的详细信息，参照 Using Kafka Connect with Schema Registry.

JSON (without Schema Registry)

key.converter=org.apache.kafka.connect.json.JsonConverter
value.converter=org.apache.kafka.connect.json.JsonConverter
key.converter.schemas.enable=false
value.converter.schemas.enable=false

当把属性 key.converter.schemas.enable 和 value.converter.schemas.enable设置为true，键和值不是一个简单的json对象，而是一个包含模式和值的复合json对象；当设置为false时，json对象中只包含数据 ，没有模式，这减少了不需要模式的应用的负载开销。

String格式和原生Bytes

org.apache.kafka.connect.storage.StringConverter 用来把Connect 数据转换成简单String 格式。

org.apache.kafka.connect.converters.ByteArrayConverter 不转换数据，进出Connect 的数据直接就是原生的字节流，没有任何转换。

Connect 生产者和消费者

Kafka Connect 内部使用标准的Java生产者和消费者与Kafka进行通信。Connect为这些生产者和消费者实例配置默认设置。这些设置包括确保数据有序地传递到Kafka且没有任何数据丢失的属性。

默认 Connect 生产者属性

默认情况下，Connect 为用于源连接器的Kafka 生产者配置以下重要属性：

• 将生产者的 bootstrap servers 指向连接集群使用的相同Kafka集群。
• 配置与连接器的键和值转换器一起工作的键和值序列化器。
• 基于Connector和Task生成生成者client.id，模式：connector-producer-<connectorName>-<taskId>。
• 设置 set acks=all，以确保生成的每个消息都正确写入到所有同步副本(ISRs)中。
• 对于可检索的异常，Connect将生产者配置为以下属性，以减少在无限重试期间数据重复的可能性

　　request.timeout.ms=<max>
　　max.block.ms=<max>
　　max.in.flight.requests.per.connection=1
　　delivery.timeout.ms=<max>

可以在worker 配置文件中用producer.* 类型的属性或者connector 配置文件中用producer.override.*类型的属性覆盖这些默认的属性。但是更改这些默认属性可能会降低Connect的数据投递保证。

覆盖 Producer 和 Consumer 默认属性

Worker 覆盖示例

考虑一个运行日志文件连接器的独立进程。对于正在收集的日志，您可能更喜欢低延迟、最佳工作交付。也就是说，当存在连接问题时，为了避免在客户机上进行数据缓冲，应用程序可以接受最小的数据损失。这样可以使日志收集尽可能地轻量级。

要覆盖worker控制的connectors的 producer configuration properties 和  consumer configuration properties，可以在worker配置文件中以producer. 或 consumer. 为前缀进行配置，如下所示：

producer.retries=1
consumer.max.partition.fetch.bytes=10485760

上面的示例覆盖了默认的生产者重试属性，发送消息后只重试一次。消费者覆盖将每次请求从分区获取的默认数据量增加到10 MB。

这些配置更改应用于worker 控制的所有connectors。在运行分布式模式worker 时，要小心对这些设置进行任何更改。

Per-connector 覆盖示例

默认情况下，用于连接器的生产者和消费者使用与Connect用于其自身内部主题相同的属性创建。这意味着相同的Kafka主体需要能够读写所有内部主题以及连接器使用的所有主题

For detailed information about producers and consumers, see Kafka Producer and Kafka Consumer. For a list of configuration properties, see Producer Configurations and Consumer Configurations.