:_mod-docs-content-type: PROCEDURE

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

[id='creating-new-image-using-kafka-connect-build-{context}']
= Building Kafka Connect images with connector plugins

[role="_abstract"]
Configure Kafka Connect to build a new container image that includes the specified connector plugins.
This prepares the runtime environment with the necessary libraries to run specific connector types.

You define the connector plugins using the `.spec.build.plugins` property of the `KafkaConnect` custom resource.

Strimzi automatically downloads and adds the connector plugins into a new container image.
The container is pushed into the container repository specified in `.spec.build.output` and automatically used in the Kafka Connect deployment.

When the deployment is updated with the new image, the plugins are available for use. 
You must then create `KafkaConnector` resources (or use the Kafka Connect API) to instantiate and run the actual connectors.

.Prerequisites

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

You need to provide your own container registry where images can be pushed to, stored, and pulled from.
Strimzi supports private container registries as well as public registries such as link:https://quay.io/[Quay^] or link:https://hub.docker.com//[Docker Hub^].

.Procedure

. Configure the `KafkaConnect` custom resource by specifying the container registry in `.spec.build.output`, and additional connectors in `.spec.build.plugins`:
+
[source,yaml,subs=attributes+,options="nowrap"]
----
apiVersion: {KafkaConnectApiVersion}
kind: KafkaConnect
metadata:
  name: my-connect-cluster
spec: # <1>
  #...
  build:
    output: # <2>
      type: docker
      image: my-registry.io/my-org/my-connect-cluster:latest
      pushSecret: my-registry-credentials
    plugins: # <3>
      - name: connector-1
        artifacts:
          - type: tgz
            url: <url_to_download_connector_1_artifact>
            sha512sum: <SHA-512_checksum_of_connector_1_artifact>
      - name: connector-2
        artifacts:
          - type: jar
            url: <url_to_download_connector_2_artifact>
            sha512sum: <SHA-512_checksum_of_connector_2_artifact>
  #...
----
<1> link:{BookURLConfiguring}#type-KafkaConnectSpec-reference[The specification for the Kafka Connect cluster^].
<2> (Required) Configuration of the container registry where new images are pushed.
<3> (Required) List of connector plugins and their artifacts to add to the new container image. Each plugin must be configured with at least one `artifact`.

. Create or update the resource:
+
[source,subs="+quotes"]
----
$ kubectl apply -f <kafka_connect_configuration_file>
----

. Wait for the new container image to build, and for the Kafka Connect cluster to be deployed.

. Use the Kafka Connect REST API or `KafkaConnector` custom resources to use the connector plugins you added.

.Rebuilding the container image with new artifacts

A new container image is built automatically when you change the base image (`.spec.image`) or change the connector plugin artifacts configuration (`.spec.build.plugins`).

To pull an upgraded base image or to download the latest connector plugin artifacts without changing the `KafkaConnect` resource, you can trigger a rebuild of the container image associated with the Kafka Connect cluster by applying the annotation `strimzi.io/force-rebuild=true` to the Kafka Connect `StrimziPodSet` resource.

The annotation triggers the rebuilding process, fetching any new artifacts for plugins specified in the `KafkaConnect` custom resource and incorporating them into the container image.
The rebuild includes downloads of new plugin artifacts without versions. 

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

* link:{BookURLConfiguring}#type-Build-reference[Kafka Connect `Build` schema reference^]
