8.4. 部署 Debezium SQL Server 连接器

流程

1. 登录 OpenShift 集群。

2. 为连接器创建 Debezium KafkaConnect 自定义资源(CR)，或修改现有的资源。例如，创建一个名为 dbz-connect.yaml 的 KafkaConnect CR，用于指定 metadata.annotations 和 spec.build 属性。以下示例显示了来自 dbz-connect.yaml 文件的摘录，该文件描述了 KafkaConnect 自定义资源。
   

   例 8.1. dbz-connect.yaml 文件，该文件定义包含 Debezium 连接器的 KafkaConnect 自定义资源

   在以下示例中，自定义资源被配置为下载以下工件：

   • Debezium SQL Server 连接器存档。
   • Service Registry 归档。Service Registry 是一个可选组件。只有在打算在连接器中使用 Avro 序列化时，才添加 Service Registry 组件。
   • Debezium 脚本 SMT 归档以及您要与 Debezium 连接器一起使用的关联脚本引擎。SMT 归档和脚本语言依赖项是可选组件。只有在打算使用 Debezium 是 基于内容的路由 SMT 或 过滤 SMT 时，才添加这些组件。

   apiVersion: kafka.strimzi.io/v1beta2
   kind: KafkaConnect
   metadata:
     name: debezium-kafka-connect-cluster
     annotations:
       strimzi.io/use-connector-resources: "true" 1
   spec:
     version: 3.3.1
     build: 2
       output: 3
         type: imagestream  4
         image: debezium-streams-connect:latest
       plugins: 5
         - name: debezium-connector-sqlserver
           artifacts:
             - type: zip 6
               url: https://maven.repository.redhat.com/ga/io/debezium/debezium-connector-sqlserver/2.1.4.Final-redhat-00001/debezium-connector-sqlserver-2.1.4.Final-redhat-00001-plugin.zip  7
             - type: zip
               url: https://maven.repository.redhat.com/ga/io/apicurio/apicurio-registry-distro-connect-converter/2.3.0.Final-redhat-<build-number>/apicurio-registry-distro-connect-converter-2.3.0.Final-redhat-<build-number>.zip  8
             - type: zip
               url: https://maven.repository.redhat.com/ga/io/debezium/debezium-scripting/2.1.4.Final-redhat-00001/debezium-scripting-2.1.4.Final-redhat-00001.zip 9
             - type: jar
               url: https://repo1.maven.org/maven2/org/codehaus/groovy/groovy/3.0.11/groovy-3.0.11.jar  10
             - type: jar
               url: https://repo1.maven.org/maven2/org/codehaus/groovy/groovy-jsr223/3.0.11/groovy-jsr223-3.0.11.jar
             - type: jar
               url: https://repo1.maven.org/maven2/org/codehaus/groovy/groovy-json3.0.11/groovy-json-3.0.11.jar
   
     bootstrapServers: debezium-kafka-cluster-kafka-bootstrap:9093
   
     ...

   表 8.14. Kafka Connect 配置设置的描述

   项	描述
   1	将 strimzi.io/use-connector-resources 注解设置为 "true"，以便 Cluster Operator 使用 KafkaConnector 资源在此 Kafka Connect 集群中配置连接器。
   2	spec.build 配置指定构建镜像的位置，并列出要在镜像中包含的插件，以及插件工件的位置。
   3	build.output 指定存储新构建镜像的 registry。
   4	指定镜像输出的名称和镜像名称。output.type 的有效值是 docker，可推送到容器 registry，如 Docker Hub 或 Quay，或将镜像推送到内部 OpenShift ImageStream 的镜像流。要使用 ImageStream，必须将 ImageStream 资源部署到集群中。有关在 KafkaConnect 配置中指定 build.output 的更多信息，请参阅在 OpenShift 中配置 AMQ Streams 中的 AMQ Streams Build schema 参考。
   5	插件配置 列出了您要包含在 Kafka Connect 镜像中的所有连接器。对于列表中的每个条目，指定一个插件名称，以及有关构建连接器所需的工件的信息。另外，对于每个连接器插件，您还可以包含您要与连接器一起使用的其他组件。例如，您可以添加 Service Registry 工件或 Debezium 脚本组件。
   6	artifacts.type 的值指定 artifacts.url 中指定的工件的文件类型。有效类型是 zip、tgz 或 jar。Debezium 连接器存档以 .zip 文件格式提供。type 值必须与 url 字段中引用的文件类型匹配。
   7	artifacts.url 的值指定 HTTP 服务器的地址，如 Maven 存储库，用于存储连接器工件的文件。Debezium 连接器工件位于 Red Hat Maven 存储库中。OpenShift 集群必须有权访问指定的服务器。
   8	（可选）指定下载 Service Registry 组件的工件 类型和 url。包括 Service Registry 工件，只有在您希望连接器使用 Apache Avro 与 Service Registry 序列化事件键和值时，而不是使用默认的 JSON converter。
   9	（可选）指定 Debezium 脚本 SMT 归档的工件 类型和 url，以用于 Debezium 连接器。只有在打算使用 Debezium 基于内容的路由 SMT 或 过滤 SMT 时使用脚本 SMT 时，才包含脚本 SMT，您必须部署 JSR 223 兼容脚本实施，如 groovy。
   10	（可选）为 JSR 223 兼容脚本实现的 JAR 文件指定工件 类型和 url，这是 Debezium 脚本 SMT 所需的。 重要 如果您使用 AMQ Streams 将连接器插件合并到 Kafka Connect 镜像中，每个所需脚本语言组件 artifacts.url 必须指定 JAR 文件的位置，而 artifacts.type 的值还必须设置为 jar。无效的值会导致连接器在运行时失败。 要启用使用带有脚本 SMT 的 Apache Groovy 语言，示例中的自定义资源会检索以下库的 JAR 文件： groovy Groovy-jsr223 （协调代理） Groovy-json （用于解析 JSON 字符串的模块） 作为替代方案，Debebe 脚本 SMT 还支持使用 GraalVM JavaScript 的 JSR 223 实现。

3. 输入以下命令将 KafkaConnect 构建规格应用到 OpenShift 集群：

   oc create -f dbz-connect.yaml

   根据自定义资源中指定的配置，Streams Operator 会准备要部署的 Kafka Connect 镜像。
   构建完成后，Operator 将镜像推送到指定的 registry 或 ImageStream，并启动 Kafka Connect 集群。您配置中列出的连接器工件在集群中可用。

4. 创建一个 KafkaConnector 资源来定义您要部署的每个连接器的实例。
   例如，创建以下 KafkaConnector CR，并将它保存为 sqlserver-inventory-connector.yaml

   例 8.2. 为 Debezium 连接器定义 KafkaConnector 自定义资源的 sqlserver-inventory-connector.yaml 文件

       apiVersion: kafka.strimzi.io/v1beta2
       kind: KafkaConnector
       metadata:
         labels:
           strimzi.io/cluster: debezium-kafka-connect-cluster
         name: inventory-connector-sqlserver 1
       spec:
         class: io.debezium.connector.sqlserver.SqlServerConnector 2
         tasksMax: 1  3
         config:  4
           schema.history.internal.kafka.bootstrap.servers: debezium-kafka-cluster-kafka-bootstrap.debezium.svc.cluster.local:9092
           schema.history.internal.kafka.topic: schema-changes.inventory
           database.hostname: sqlserver.debezium-sqlserver.svc.cluster.local 5
           database.port: 1433   6
           database.user: debezium  7
           database.password: dbz  8
           topic.prefix: inventory-connector-sqlserver 9
           table.include.list: dbo.customers  10
   
           ...

   表 8.15. 连接器配置设置的描述

   项	描述
   1	使用 Kafka Connect 集群注册的连接器名称。
   2	连接器类的名称。
   3	可同时运行的任务数量。
   4	连接器的配置。
   5	主机数据库实例的地址。
   6	数据库实例的端口号。
   7	Debezium 用于连接到数据库的帐户名称。
   8	Debezium 用于连接到数据库用户帐户的密码。
   9	数据库实例或集群的主题前缀。 指定的名称只能从字母数字字符或下划线括起。 由于主题前缀用作从这个连接器接收更改事件的任何 Kafka 主题的前缀，所以名称必须在集群中的连接器之间唯一。 此命名空间也用于相关的 Kafka Connect 模式的名称，如果您将连接器与 Avro 连接器集成，则对应的 Avro 模式的命名空间也用于。
   10	连接器从中捕获更改事件的表列表。

5. 运行以下命令来创建连接器资源：

   oc create -n <namespace> -f <kafkaConnector>.yaml

   例如，

   oc create -n debezium -f sqlserver-inventory-connector.yaml

   连接器注册到 Kafka Connect 集群，并开始针对 KafkaConnector CR 中的 spec.config.database.dbname 指定的数据库运行。连接器 pod 就绪后，Debezium 正在运行。

流程

1. 为 Kafka Connect 创建 Debezium SQL Server 容器：

   1. 创建一个 Dockerfile，它使用 registry.redhat.io/amq7/amq-streams-kafka-32-rhel8:2.2.0-12 作为基础镜像。例如，在终端窗口中输入以下命令：

      cat <<EOF >debezium-container-for-sqlserver.yaml 1
      FROM registry.redhat.io/amq7/amq-streams-kafka-32-rhel8:2.2.0-12
      USER root:root
      RUN mkdir -p /opt/kafka/plugins/debezium 2
      RUN cd /opt/kafka/plugins/debezium/ \
      && curl -O https://maven.repository.redhat.com/ga/io/debezium/debezium-connector-sqlserver/2.1.4.Final-redhat-00001/debezium-connector-sqlserver-2.1.4.Final-redhat-00001-plugin.zip \
      && unzip debezium-connector-sqlserver-2.1.4.Final-redhat-00001-plugin.zip \
      && rm debezium-connector-sqlserver-2.1.4.Final-redhat-00001-plugin.zip
      RUN cd /opt/kafka/plugins/debezium/
      USER 1001
      EOF

      项	描述
      1	您可以指定您想要的任何文件名。
      2	指定 Kafka Connect 插件目录的路径。如果您的 Kafka Connect 插件目录位于不同的位置，请将这个路径替换为您的目录的实际路径。

      该命令在当前目录中创建一个名为 debezium-container-for-sqlserver.yaml 的 Dockerfile。

   2. 从您在上一步中创建的 debezium-container-for-sqlserver.yaml Docker 文件中构建容器镜像。在包含该文件的目录中，打开终端窗口并输入以下命令之一：

      podman build -t debezium-container-for-sqlserver:latest .

      docker build -t debezium-container-for-sqlserver:latest .

      上述命令使用名称 debezium-container-for-sqlserver 构建容器镜像。

   3. 将自定义镜像推送到容器 registry，如 quay.io 或内部容器 registry。容器 registry 必须可供部署镜像的 OpenShift 实例使用。输入以下命令之一：

      podman push <myregistry.io>/debezium-container-for-sqlserver:latest

      docker push <myregistry.io>/debezium-container-for-sqlserver:latest

   4. 创建新的 Debezium SQL Server KafkaConnect 自定义资源(CR)。例如，创建一个名为 dbz-connect.yaml 的 KafkaConnect CR，用于指定 注解和 镜像 属性。以下示例显示了来自 dbz-connect.yaml 文件的摘录，该文件描述了 KafkaConnect 自定义资源。
      

      apiVersion: kafka.strimzi.io/v1beta2
      kind: KafkaConnect
      metadata:
        name: my-connect-cluster
        annotations:
          strimzi.io/use-connector-resources: "true" 1
      spec:
        #...
        image: debezium-container-for-sqlserver  2
      
        ...

      项	描述
      1	metadata.annotations 表示 KafkaConnector 资源用于配置在这个 Kafka Connect 集群中使用的 Cluster Operator。
      2	spec.image 指定您为运行 Debezium 连接器而创建的镜像名称。此属性覆盖 Cluster Operator 中的 STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE 变量。

   5. 输入以下命令将 KafkaConnect CR 应用到 OpenShift Kafka Connect 环境：

      oc create -f dbz-connect.yaml

      命令添加一个 Kafka Connect 实例，用于指定您为运行 Debezium 连接器而创建的镜像名称。

2. 创建一个 KafkaConnector 自定义资源来配置 Debezium SQL Server 连接器实例。

   您可以在 .yaml 文件中配置 Debezium SQL Server 连接器，该文件指定连接器的配置属性。连接器配置可能会指示 Debezium 为 schema 和表的子集生成事件，或者可能会设置属性，以便 Debezium 忽略敏感、太大或不需要的指定栏中的值。

   以下示例配置 Debezium 连接器，该连接器连接到端口 1433 上的 SQL 服务器主机 192.168.99.100。此主机有一个名为 testDB 的数据库，名为 customer 的表，inventory-connector-sqlserver 是服务器的逻辑名称。

   SQL Server inventory-connector.yaml

   apiVersion: kafka.strimzi.io/v1beta2
   kind: KafkaConnector
   metadata:
     name: inventory-connector-sqlserver 1
     labels:
       strimzi.io/cluster: my-connect-cluster
     annotations:
       strimzi.io/use-connector-resources: 'true'
   spec:
     class: io.debezium.connector.sqlserver.SqlServerConnector 2
     config:
       database.hostname: 192.168.99.100 3
       database.port: 1433 4
       database.user: debezium 5
       database.password: dbz 6
       database.names: testDB1,testDB2 7
       topic.prefix: inventory-connector-sqlserver 8
       table.include.list: dbo.customers 9
       schema.history.internal.kafka.bootstrap.servers: my-cluster-kafka-bootstrap:9092 10
       schema.history.internal.kafka.topic: schemahistory.fullfillment 11
       database.ssl.truststore: path/to/trust-store 12
       database.ssl.truststore.password: password-for-trust-store 13

   表 8.16. 连接器配置设置的描述

   项	描述
   1	在将连接器注册到 Kafka Connect 服务时，它的名称。
   2	此 SQL Server 连接器类的名称。
   3	SQL Server 实例的地址。
   4	SQL Server 实例的端口号。
   5	SQL Server 用户的名称。
   6	SQL Server 用户的密码。
   7	要从中捕获更改的数据库名称。
   8	SQL Server instance/cluster 的主题前缀，它组成一个命名空间，用于连接器写入的 Kafka 主题、Kafka Connect 模式名称和相应 Avro 模式的命名空间。
   9	连接器仅捕获 dbo.customers 表中的更改。
   10	此连接器用来向数据库架构历史记录主题写入和恢复 DDL 语句的 Kafka 代理列表。
   11	连接器将编写和恢复 DDL 语句的数据库架构历史记录主题的名称。本主题仅用于内部使用，不应供消费者使用。
   12	存储服务器的 signer 证书的 SSL 信任存储的路径。除非禁用数据库加密，否则此属性是必需的(database.encrypt=false)。
   13	SSL 信任存储密码。除非禁用数据库加密，否则此属性是必需的(database.encrypt=false)。

3. 使用 Kafka Connect 创建连接器实例。例如，如果您将 KafkaConnector 资源保存到 inventory-connector.yaml 文件中，您将运行以下命令：

   oc apply -f inventory-connector.yaml

   上述命令注册 inventory-connector，连接器开始针对 KafkaConnector CR 中定义的 testDB 数据库运行。

流程

1. 使用以下方法之一检查 KafkaConnector 资源的状态：

   • 在 OpenShift Container Platform Web 控制台中：

     1. 导航到 Home Search。
     2. 在 Search 页面中，点 Resources 以打开 Select Resource 复选框，然后键入 KafkaConnector。
     3. 在 KafkaConnectors 列表中，点您要检查的连接器的名称，如 inventory-connector-sqlserver。
     4. 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。

   • 在一个终端窗口中：

     1. 使用以下命令：

        oc describe KafkaConnector <connector-name> -n <project>

        例如，

        oc describe KafkaConnector inventory-connector-sqlserver -n debezium

        该命令返回类似以下输出的状态信息：

        例 8.3. KafkaConnector 资源状态

        Name:         inventory-connector-sqlserver
        Namespace:    debezium
        Labels:       strimzi.io/cluster=debezium-kafka-connect-cluster
        Annotations:  <none>
        API Version:  kafka.strimzi.io/v1beta2
        Kind:         KafkaConnector
        
        ...
        
        Status:
          Conditions:
            Last Transition Time:  2021-12-08T17:41:34.897153Z
            Status:                True
            Type:                  Ready
          Connector Status:
            Connector:
              State:      RUNNING
              worker_id:  10.131.1.124:8083
            Name:         inventory-connector-sqlserver
            Tasks:
              Id:               0
              State:            RUNNING
              worker_id:        10.131.1.124:8083
            Type:               source
          Observed Generation:  1
          Tasks Max:            1
          Topics:
            inventory-connector-sqlserver.inventory
            inventory-connector-sqlserver.inventory.addresses
            inventory-connector-sqlserver.inventory.customers
            inventory-connector-sqlserver.inventory.geom
            inventory-connector-sqlserver.inventory.orders
            inventory-connector-sqlserver.inventory.products
            inventory-connector-sqlserver.inventory.products_on_hand
        Events:  <none>

2. 验证连接器是否已创建 Kafka 主题：

   • 通过 OpenShift Container Platform Web 控制台。

     1. 导航到 Home Search。
     2. 在 Search 页面中，点 Resources 打开 Select Resource 复选框，然后键入 KafkaTopic。
     3. 在 KafkaTopics 列表中，点您要检查的主题的名称，例如 inventory-connector-sqlserver.inventory.orders--ac5e98ac6a5d91e04d8ec0dc9078a1ece439081d。
     4. 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。

   • 在一个终端窗口中：

     1. 使用以下命令：

        oc get kafkatopics

        该命令返回类似以下输出的状态信息：

        例 8.4. KafkaTopic 资源状态

        NAME                                                                    CLUSTER               PARTITIONS   REPLICATION FACTOR   READY
        connect-cluster-configs                                                 debezium-kafka-cluster   1            1                    True
        connect-cluster-offsets                                                 debezium-kafka-cluster   25           1                    True
        connect-cluster-status                                                  debezium-kafka-cluster   5            1                    True
        consumer-offsets---84e7a678d08f4bd226872e5cdd4eb527fadc1c6a             debezium-kafka-cluster   50           1                    True
        inventory-connector-sqlserver--a96f69b23d6118ff415f772679da623fbbb99421                               debezium-kafka-cluster   1            1                    True
        inventory-connector-sqlserver.inventory.addresses---1b6beaf7b2eb57d177d92be90ca2b210c9a56480          debezium-kafka-cluster   1            1                    True
        inventory-connector-sqlserver.inventory.customers---9931e04ec92ecc0924f4406af3fdace7545c483b          debezium-kafka-cluster   1            1                    True
        inventory-connector-sqlserver.inventory.geom---9f7e136091f071bf49ca59bf99e86c713ee58dd5               debezium-kafka-cluster   1            1                    True
        inventory-connector-sqlserver.inventory.orders---ac5e98ac6a5d91e04d8ec0dc9078a1ece439081d             debezium-kafka-cluster   1            1                    True
        inventory-connector-sqlserver.inventory.products---df0746db116844cee2297fab611c21b56f82dcef           debezium-kafka-cluster   1            1                    True
        inventory-connector-sqlserver.inventory.products_on_hand---8649e0f17ffcc9212e266e31a7aeea4585e5c6b5   debezium-kafka-cluster   1            1                    True
        schema-changes.inventory                                                debezium-kafka-cluster   1            1                    True
        strimzi-store-topic---effb8e3e057afce1ecf67c3f5d8e4e3ff177fc55          debezium-kafka-cluster   1            1                    True
        strimzi-topic-operator-kstreams-topic-store-changelog---b75e702040b99be8a9263134de3507fc0cc4017b  debezium-kafka-cluster  1   1    True

3. 检查主题内容。

   • 在终端窗口中输入以下命令：

   oc exec -n <project>  -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \
   >     --bootstrap-server localhost:9092 \
   >     --from-beginning \
   >     --property print.key=true \
   >     --topic=<topic-name>

   例如，

   oc exec -n debezium  -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \
   >     --bootstrap-server localhost:9092 \
   >     --from-beginning \
   >     --property print.key=true \
   >     --topic=inventory-connector-sqlserver.inventory.products_on_hand

   指定主题名称的格式与 oc describe 命令的格式在第 1 步中返回，例如 inventory-connector-sqlserver.inventory.addresses。

   对于主题中的每个事件，命令会返回类似以下输出的信息：

   例 8.5. Debezium 更改事件的内容

   {"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.sqlserver.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.1.4.Final-redhat-00001","connector":"sqlserver","name":"inventory-connector-sqlserver","ts_ms":1638985247805,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"sqlserver-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"transaction":null}}

   在上例中，有效负载 值显示连接器快照从表 inventory.products_on_hand 中生成一个读取("op" ="r")事件。product_id 记录的 "before" 状态为 null，这表示记录没有之前的值。"after" 状态对于 product_id 为 101 的项目的 quantity 显示为 3。