This is an automated email from the ASF dual-hosted git repository.
mimaison pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new e3a282afea6 KAFKA-19404: Align Connect plugin.path docs with actual
behavior (#22481)
e3a282afea6 is described below
commit e3a282afea68d7948cbc553124b39295d23aa1ed
Author: majialong <[email protected]>
AuthorDate: Thu Jun 18 20:14:32 2026 +0800
KAFKA-19404: Align Connect plugin.path docs with actual behavior (#22481)
This PR updates the Kafka Connect `plugin.path` docs to better describe
the current behavior.
It clarifies how directory entries are handled, that child directories
are scanned recursively, and how to lay out plugins and dependencies.
Co-authored-by: majialong <[email protected]>
Reviewers: Mickael Maison <[email protected]>
---
config/connect-distributed.properties | 20 +++++++++++++------
config/connect-standalone.properties | 22 ++++++++++++++-------
.../apache/kafka/connect/runtime/WorkerConfig.java | 23 +++++++++++++++-------
3 files changed, 45 insertions(+), 20 deletions(-)
diff --git a/config/connect-distributed.properties
b/config/connect-distributed.properties
index cedad9a6823..29cc5b18cc3 100644
--- a/config/connect-distributed.properties
+++ b/config/connect-distributed.properties
@@ -79,11 +79,19 @@ offset.flush.interval.ms=10000
#rest.advertised.listener=
# Set to a list of filesystem paths separated by commas (,) to enable class
loading isolation for plugins
-# (connectors, converters, transformations). The list should consist of top
level directories that include
-# any combination of:
-# a) directories immediately containing jars with plugins and their
dependencies
-# b) uber-jars with plugins and their dependencies
-# c) directories immediately containing the package directory structure of
classes of plugins and their dependencies
-# Examples:
+# (connectors, converters, transformations). A path may be a plugin archive
(JAR or ZIP), or a directory
+# containing plugins. When the path is a directory, each direct child
directory or archive is loaded
+# separately and may be:
+# a) a directory containing JARs or ZIPs with plugins and their dependencies
+# b) an uber-jar with plugins and their dependencies
+# c) a directory containing the package directory structure of classes of
plugins and their dependencies
+# Each direct child directory is scanned recursively, so archives, classes and
dependencies may be located in
+# nested subdirectories. Multiple plugins placed under the same direct child
directory share the same
+# class loader. For class loading isolation, place each plugin and its
dependencies in its own direct
+# child directory under a path listed in plugin.path.
+# Examples:
#
plugin.path=/usr/local/share/java,/usr/local/share/kafka/plugins,/opt/connectors,
+# With plugin.path=/opt/connectors, place each plugin in its own direct child
of /opt/connectors.
+# A plugin can be a directory such as /opt/connectors/my-plugin/ (dependencies
may be nested,
+# e.g. /opt/connectors/my-plugin/lib/dep.jar), or an uber-jar such as
/opt/connectors/another-plugin.jar.
#plugin.path=
diff --git a/config/connect-standalone.properties
b/config/connect-standalone.properties
index a340a3bf315..54bd13f0fa6 100644
--- a/config/connect-standalone.properties
+++ b/config/connect-standalone.properties
@@ -30,12 +30,20 @@ offset.storage.file.filename=/tmp/connect.offsets
offset.flush.interval.ms=10000
# Set to a list of filesystem paths separated by commas (,) to enable class
loading isolation for plugins
-# (connectors, converters, transformations). The list should consist of top
level directories that include
-# any combination of:
-# a) directories immediately containing jars with plugins and their
dependencies
-# b) uber-jars with plugins and their dependencies
-# c) directories immediately containing the package directory structure of
classes of plugins and their dependencies
-# Note: symlinks will be followed to discover dependencies or plugins.
-# Examples:
+# (connectors, converters, transformations). A path may be a plugin archive
(JAR or ZIP), or a directory
+# containing plugins. When the path is a directory, each direct child
directory or archive is loaded
+# separately and may be:
+# a) a directory containing JARs or ZIPs with plugins and their dependencies
+# b) an uber-jar with plugins and their dependencies
+# c) a directory containing the package directory structure of classes of
plugins and their dependencies
+# Each direct child directory is scanned recursively, so archives, classes and
dependencies may be located in
+# nested subdirectories. Multiple plugins placed under the same direct child
directory share the same
+# class loader. For class loading isolation, place each plugin and its
dependencies in its own direct
+# child directory under a path listed in plugin.path. Symlinks will be
followed to discover dependencies
+# or plugins.
+# Examples:
#
plugin.path=/usr/local/share/java,/usr/local/share/kafka/plugins,/opt/connectors,
+# With plugin.path=/opt/connectors, place each plugin in its own direct child
of /opt/connectors.
+# A plugin can be a directory such as /opt/connectors/my-plugin/ (dependencies
may be nested,
+# e.g. /opt/connectors/my-plugin/lib/dep.jar), or an uber-jar such as
/opt/connectors/another-plugin.jar.
#plugin.path=
diff --git
a/connect/runtime/src/main/java/org/apache/kafka/connect/runtime/WorkerConfig.java
b/connect/runtime/src/main/java/org/apache/kafka/connect/runtime/WorkerConfig.java
index 35326c03ae3..0dacbb909c3 100644
---
a/connect/runtime/src/main/java/org/apache/kafka/connect/runtime/WorkerConfig.java
+++
b/connect/runtime/src/main/java/org/apache/kafka/connect/runtime/WorkerConfig.java
@@ -128,15 +128,24 @@ public class WorkerConfig extends AbstractConfig {
public static final String PLUGIN_PATH_CONFIG = "plugin.path";
protected static final String PLUGIN_PATH_DOC = "List of paths separated
by commas (,) that "
- + "contain plugins (connectors, converters, transformations). The
list should consist"
- + " of top level directories that include any combination of: \n"
- + "a) directories immediately containing jars with plugins and
their dependencies\n"
- + "b) uber-jars with plugins and their dependencies\n"
- + "c) directories immediately containing the package directory
structure of classes of "
- + "plugins and their dependencies\n"
- + "Note: symlinks will be followed to discover dependencies or
plugins.\n"
+ + "contain plugins (connectors, converters, transformations). A
path may be a plugin "
+ + "archive (JAR or ZIP), or a directory containing plugins. When
the path is a directory, "
+ + "each direct child directory or archive is loaded separately and
may be: \n"
+ + "a) a directory containing JARs or ZIPs with plugins and their
dependencies\n"
+ + "b) an uber-jar with plugins and their dependencies\n"
+ + "c) a directory containing the package directory structure of
classes of plugins and "
+ + "their dependencies\n"
+ + "Each direct child directory is scanned recursively, so
archives, classes and dependencies "
+ + "may be located in nested subdirectories. Multiple plugins
placed under the same direct "
+ + "child directory share the same class loader. For class loading
isolation, place each "
+ + "plugin and its dependencies in its own direct child directory
under a path listed in "
+ + "plugin.path. Symlinks will be followed to discover dependencies
or plugins.\n"
+ "Examples:
plugin.path=/usr/local/share/java,/usr/local/share/kafka/plugins,"
+ "/opt/connectors\n"
+ + "With plugin.path=/opt/connectors, place each plugin in its own
direct child "
+ + "of /opt/connectors. A plugin can be a directory such as
/opt/connectors/my-plugin/ "
+ + "(dependencies may be nested, e.g.
/opt/connectors/my-plugin/lib/dep.jar), or "
+ + "an uber-jar such as /opt/connectors/another-plugin.jar.\n"
+ "Do not use config provider variables in this property, since
the raw path is used "
+ "by the worker's scanner before config providers are initialized
and used to "
+ "replace variables.";
