// Module included in the following assemblies:
//
// assembly-deploy-kafka-connect-with-plugins.adoc

[id='creating-new-image-from-base-{context}']
= Building custom Kafka Connect images with connector plugins

[role="_abstract"]
Create a custom Docker image with connector plugins from the Kafka Connect base image.
Add the custom image to the `/opt/kafka/plugins` directory.

You can use the Kafka container image on {DockerRepository} as a base image for creating your own custom image with additional connector plugins.
At startup, the Strimzi version of Kafka Connect loads any third-party connector plugins contained in `/opt/kafka/plugins`.

Use the `KafkaConnect.spec.image` property to scope the custom image to a single Kafka Connect cluster.
Editing the `STRIMZI_KAFKA_CONNECT_IMAGES` environment variable in the Cluster Operator instead applies the image globally to all Connect clusters.

This procedure shows how to do the following:

* Build a custom image from the Kafka Connect base.
* Push the image to your registry.
* Reference the image by setting `KafkaConnect.spec.image`.

NOTE: When you specify a custom image, coordinate upgrades to keep the image and the Kafka version aligned.

.Prerequisites

* xref:deploying-cluster-operator-str[The Cluster Operator must be deployed.]

.Procedure

. Create a new `Dockerfile` using `{DockerKafkaConnect}` as the base image:
+
[source,subs="+quotes,attributes"]
----
FROM {DockerKafkaConnect}
USER root:root
COPY ./_my-plugins_/ /opt/kafka/plugins/
USER {DockerImageUser}
----
+
.Example plugins file
[source,subs="+quotes"]
----
$ tree ./_my-plugins_/
./_my-plugins_/
├── debezium-connector-mongodb
│   ├── bson-<version>.jar
│   ├── CHANGELOG.md
│   ├── CONTRIBUTE.md
│   ├── COPYRIGHT.txt
│   ├── debezium-connector-mongodb-<version>.jar
│   ├── debezium-core-<version>.jar
│   ├── LICENSE.txt
│   ├── mongodb-driver-core-<version>.jar
│   ├── README.md
│   └── # ...
├── debezium-connector-mysql
│   ├── CHANGELOG.md
│   ├── CONTRIBUTE.md
│   ├── COPYRIGHT.txt
│   ├── debezium-connector-mysql-<version>.jar
│   ├── debezium-core-<version>.jar
│   ├── LICENSE.txt
│   ├── mysql-binlog-connector-java-<version>.jar
│   ├── mysql-connector-java-<version>.jar
│   ├── README.md
│   └── # ...
└── debezium-connector-postgres
    ├── CHANGELOG.md
    ├── CONTRIBUTE.md
    ├── COPYRIGHT.txt
    ├── debezium-connector-postgres-<version>.jar
    ├── debezium-core-<version>.jar
    ├── LICENSE.txt
    ├── postgresql-<version>.jar
    ├── protobuf-java-<version>.jar
    ├── README.md
    └── # ...
----
+
The COPY command points to the plugin files to copy to the container image.
+
This example adds plugins for Debezium connectors (MongoDB, MySQL, and PostgreSQL), though not all files are listed for brevity. Debezium running in Kafka Connect looks the same as any other Kafka Connect task.

. Build the container image.

. Push your custom image to your container registry.

. Point the `KafkaConnect` custom resource to the new container image.
+
Edit the `KafkaConnect.spec.image` property of the KafkaConnect custom resource to specify your custom image. 
+
[source,yaml,subs=attributes+]
----
apiVersion: {KafkaConnectApiVersion}
kind: KafkaConnect
metadata:
  name: my-connect-cluster
spec: # <1>
  version: {DefaultKafkaVersion} # <2>
  image: my-new-container-image # <3>
  #...
----
<1> link:{BookURLConfiguring}#type-KafkaConnectSpec-reference[The specification for the Kafka Connect cluster^].
<2> The Kafka version. Always specify the Kafka version that matches your Kafka cluster to avoid version conflicts.
<3> The custom docker image for Kafka Connect pods.

WARNING: Check the Kafka version you need for your custom image. 
If `spec.version` is unspecified, Strimzi defaults to Kafka {DefaultKafkaVersion}, which may cause compatibility issues if your Kafka cluster runs an earlier version.
Version mismatches may lead to connector failures and runtime errors.

[role="_additional-resources"]
.Additional resources

* link:{BookURLConfiguring}#con-common-configuration-images-reference[Container image configuration and the `KafkaConnect.spec.image property`^]
* xref:ref-operator-cluster-str[Cluster Operator configuration and the `STRIMZI_KAFKA_CONNECT_IMAGES` variable]
