docs(connect): clarifies image/version config for kafka connect

documentation/modules/con-common-configuration-properties.adoc

@@ -288,7 +288,7 @@ For more information on CPU specification, see {K8sMeaningOfCpu}.
 
 Use the `image` property to configure the container image used by the component.
 
-Overriding container images is recommended only in special situations where you need to use a different container registry or a customized image.
+Overriding container images is recommended only in special situations where you need to use a different container registry or a custom image.
 
 For example, if your network does not allow access to the container repository used by Strimzi, you can copy the Strimzi images or build them from the source.
 However, if the configured image is not compatible with Strimzi images, it might not work properly.
@@ -310,37 +310,97 @@ You can specify which container image to use for a component using the `image` p
 NOTE: Changing the Kafka image version does not automatically update the image versions for other Kafka components, such as Kafka Exporter.
 These components are not version dependent, so no additional configuration is necessary when updating the Kafka image version.
 
-*Configuring the `image` property for Kafka, Kafka Connect, and Kafka MirrorMaker*
+.Setting Kafka component images
 
-Kafka, Kafka Connect, and Kafka MirrorMaker 2 support multiple versions of Kafka.
-Each component requires its own image.
-The default images for the different Kafka versions are configured in the following environment variables:
+Strimzi supports multiple Kafka versions across Kafka, Kafka Connect, and Kafka MirrorMaker 2 components. 
+Each component requires a specific container image, which can be configured in two places:
 
-* `STRIMZI_KAFKA_IMAGES`
-* `STRIMZI_KAFKA_CONNECT_IMAGES`
-* `STRIMZI_KAFKA_MIRROR_MAKER2_IMAGES`
+. Cluster Operator environment variables (Default image mappings)
+. Custom resource configuration
 
-These environment variables contain mappings between Kafka versions and corresponding images.
-The mappings are used together with the `image` and `version` properties to determine the image used:
+Each environment variable maps Kafka versions to container images. 
+These mappings are used when a custom resource does not explicitly specify an image.
+You can override the default image by specifying the image and the matching version in the custom resource.
 
-* If neither `image` nor `version` are given in the custom resource, the `version` defaults to the Cluster Operator's default Kafka version, and the image used is the one corresponding to this version in the environment variable.
+.Cluster Operator environment variables
+[cols="1,2m",options="header"]
+|===
+| Component       | Environment variable
+
+| Kafka           | STRIMZI_KAFKA_IMAGES
+| Kafka Connect   | STRIMZI_KAFKA_CONNECT_IMAGES
+| MirrorMaker 2   | STRIMZI_KAFKA_MIRROR_MAKER2_IMAGES
+|===
+
+.Custom resource configuration
+[cols="1m,1m,1m",options="header"]
+|===
+| Custom resource       | Image property     | Version property
+
+| Kafka                 | spec.kafka.image   | spec.kafka.version
+| KafkaConnect          | spec.image         | spec.version
+| KafkaMirrorMaker2     | spec.image         | spec.version
+|===
+
+The values for the environment variables and those specified for `image` and `version` in the component configuration determines the image and Kafka version used:
+
+.Values specified for image and Kafka version
+[cols="1,1,2",options="header"]
+|===
+| `image` set?    | `version` set?  | Result
+
+| ✗           | ✗         | Uses Cluster Operator's default image and corresponding Kafka version
+| ✓           | ✗         | Uses specified image and default Kafka version
+| ✗           | ✓         | Uses image from environment variable for specified Kafka version
+| ✓           | ✓         | Uses specified image and assumes specified Kafka version matches
+|===
+
+NOTE: To avoid Kafka version and image mismatches, set the `version` property and allow the Cluster Operator to select the matching image from its mappings. 
+If you need to change the default image mapping for a given Kafka version, configure the Cluster Operator’s environment variables.
+
+Even if the configuration is syntactically correct, it can still be invalid if the image and version mismatch.
+To ensure a valid configuration:
+
+* The specified `version` *must* match the Kafka version that the image is built for.
+* The specified `version` must be one of the versions supported by the operator.
+* If you set a custom `image`, always set `version` to the Kafka version of that image.
+
+Here we can see what happens with versions {KafkaVersionLower} and {DefaultKafkaVersion} (the default).
+
+.Valid and invalid configuration examples
+[cols="1,1,1,1,1",options="header"]
+|===
+| `image` set? | `version` set? | Image used | Kafka version | Valid?
+
+| ✗ | ✗ | {DefaultKafkaVersion} (default) | {DefaultKafkaVersion} | ✓
+| ✗ | {KafkaVersionLower} | {KafkaVersionLower} (from mapping) | {KafkaVersionLower} | ✓
+| Custom {KafkaVersionLower} | {KafkaVersionLower} | Custom {KafkaVersionLower} | {KafkaVersionLower} | ✓
+| Custom {KafkaVersionLower} | ✗ | Custom {KafkaVersionLower} | {DefaultKafkaVersion} (default) | ✗
+| Custom {KafkaVersionLower} | {DefaultKafkaVersion} | Custom {KafkaVersionLower} | {DefaultKafkaVersion} | ✗
+|===
 
-* If `image` is given but `version` is not, then the given image is used and the `version` is assumed to be the Cluster Operator's default Kafka version.
+NOTE: _Custom {KafkaVersionLower}_ refers to a custom user-provided container image built against Kafka {KafkaVersionLower}.
+Setting a *custom image* means you set the `image` property to a user-provided image. 
+The operator does not automatically change this value during upgrades.
 
-* If `version` is given but `image` is not, then the image that corresponds to the given version in the environment variable is used.
+*Handling upgrades with custom images*
 
-* If both `version` and `image` are given, then the given image is used. The image is assumed to contain a Kafka image with the given version.
+When you set a custom image through the `image` property in a custom resource, you must keep the `image` and version in `sync` during upgrades.
+The Cluster Operator does not automatically update images defined this way. 
+(This limitation does not apply when you use Kafka Connect Build or the default image mappings defined in the Cluster Operator environment variables.)
 
-The `image` and `version` for the components can be configured in the following properties:
+To avoid version mismatches when changing the Kafka version:
 
-* For Kafka in `spec.kafka.image` and `spec.kafka.version`.
-* For Kafka Connect and Kafka MirrorMaker in `spec.image` and `spec.version`.
+* Pause reconciliation of the custom resource.
+* Upgrade the Cluster Operator to a release that supports a new Kafka version.
+* Update the custom resource:
+** Set `spec.*.version` to the target Kafka version
+** Set `spec.*.image` to the custom image built for that version
+* Unpause the reconciliation.
 
-WARNING: It is recommended to provide only the `version` and leave the `image` property unspecified.
-This reduces the chance of making a mistake when configuring the custom resource.
-If you need to change the images used for different versions of Kafka, it is preferable to configure the Cluster Operator's environment variables.
+If you don’t follow these steps, the operator might attempt to upgrade the resource before the correct image is specified, leading to mismatches.
 
-*Configuring the `image` property in other resources*
+.Configuring the `image` property in other resources
 
 For the `image` property in the custom resources for other components, the given value is used during deployment.
 If the `image` property is not set, the container `image` specified as an environment variable in the Cluster Operator configuration is used.

documentation/modules/deploying/proc-deploy-kafka-connect-new-image-from-base.adoc

@@ -3,15 +3,25 @@
 // assembly-deploy-kafka-connect-with-plugins.adoc
 
 [id='creating-new-image-from-base-{context}']
-= Building new container images with connector plugins from the Kafka Connect base image
+= 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`.
 
-At startup, the Strimzi version of Kafka Connect loads any third-party connector plugins contained in the `/opt/kafka/plugins` directory.
+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
 
@@ -77,31 +87,28 @@ This example adds plugins for Debezium connectors (MongoDB, MySQL, and PostgreSQ
 
 . Push your custom image to your container registry.
 
-. Point to the new container image.
-+
-You can point to the image in one of the following ways:
+. Point the `KafkaConnect` custom resource to the new container image.
 +
-* Edit the `KafkaConnect.spec.image` property of the `KafkaConnect` custom resource.
-+
-If set, this property overrides the `STRIMZI_KAFKA_CONNECT_IMAGES` environment variable in the Cluster Operator.
+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>
+spec: # <1>
+  version: {DefaultKafkaVersion} # <2>
+  image: my-new-container-image # <3>
   #...
-  image: my-new-container-image <2>
-  config: <3>
-    #...
 ----
 <1> link:{BookURLConfiguring}#type-KafkaConnectSpec-reference[The specification for the Kafka Connect cluster^].
-<2> The docker image for Kafka Connect pods.
-<3> Configuration of the Kafka Connect _workers_ (not connectors).
-+
-* Edit the `STRIMZI_KAFKA_CONNECT_IMAGES` environment variable in the `install/cluster-operator/060-Deployment-strimzi-cluster-operator.yaml` file to point to the new container image, and then reinstall the Cluster Operator.
+<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