Manage connector versions in Aiven for Apache Kafka Connect®
Aiven for Apache Kafka Connect® lets you control which connector version is used in your service.
Benefits
It prevents compatibility issues from automatic updates, avoids breaking changes
when multiple dependencies rely on a specific connector version, and allows testing,
upgrading, or reverting versions to maintain production pipeline stability. You can
specify the version of a connector by setting the plugin_versions
property in the
service configuration.
Key considerations
- Deprecated connector versions may be removed during maintenance updates. If you set a deprecated version, the system alerts you and recommends an upgrade. The connector will continue to run, but upgrading to a supported version is recommended to avoid compatibility issues.
- Support is limited to the latest connector version and the most recent previous version. Breaking changes, if known, are mentioned in maintenance update notifications.
- Setting a connector version applies to the entire plugin, ensuring that all connectors provided by the plugin (such as source and sink connectors) use the same version.
- Downgrading a connector to an older version is supported if that version is available. On older service nodes, the selected version takes effect only after a maintenance update.
- Multi-version support is available for all connectors where Aiven has published and supports more than one version. Support will continue to expand as new versions are released.
- Set a specific version to prevent automatic upgrades. If not set, the latest published version is used.
- See Check available connector versions to confirm which versions are supported before setting a version.
- Setting
plugin_version
in the connector configuration (for example, in theconfig
block in Terraform) is not supported and has no effect. To control connector versions, use theplugin_versions
property in the Kafka Connect service configuration. - You can set connector versions even if the service is running on older nodes. However, the selected version only takes effect after a maintenance update. Until then, the connector runs the latest available version, and no warning is shown.
Breaking changes may exist between different connector versions. These changes often involve updates to configuration parameters, such as the removal of deprecated parameters or the introduction of new ones. Before upgrading:
- Review the connector release notes for details on changes.
- Always test a connector version change in a non-production environment before applying it in production.
Aiven supports multiple Debezium versions through multi-version support, including versions 1.9.7, 2.5.0, 2.7.4, and 3.1.0.
To prevent automatic upgrades during maintenance, pin the connector version using
the plugin_versions
property.
If you use Debezium for PostgreSQL with version 1.9.7 and the wal2json
format, do not
upgrade to version 2.0 or later until you migrate to pgoutput
.
For upgrade steps, see Set a connector version.
Limitations
Connector version selection is available in the Aiven Console only for dedicated Apache Kafka Connect services.
If you enabled Apache Kafka Connect as part of an Aiven for Apache Kafka service, use the Aiven API, Aiven CLI, or Aiven Provider for Terraform to set the connector version.
The version selector in the Aiven Console appears on individual connector configuration pages, but changing the version affects all instances of that connector within the service, not just the selected instance. Apache Kafka Connect does not support loading multiple versions of the same plugin within a service. This limitation is expected to be addressed in Apache Kafka 4.1.0 through KIP-891. Until then, if you run multiple instances of a connector in a service, they must all use the same plugin version.
Prerequisites
- Aiven for Apache Kafka® service with a dedicated Aiven for Apache Kafka Connect® service enabled
- Aiven CLI
- Aiven API
- Aiven Provider for Terraform
Check available connector versions
Before selecting a connector version, check which versions are available for your Aiven for Apache Kafka Connect service. This ensures that the desired version is supported and can be set if needed. Use one of the following methods:
- Aiven Console
- Aiven API
- Aiven CLI
- Access the Aiven Console.
- Select your Aiven for Apache Kafka Connect service.
- Click Connectors.
Connectors that support multiple versions display 2 versions next to their names on the Connectors page.
When setting up a new connector, a default version is selected. To change it, go to the connector details page and click Change version.
-
Run the following command:
curl -X GET "https://api.aiven.io/v1/project/<project_name>/service/<service_name>/available-connectors" \
-H "Authorization: Bearer <API_TOKEN>" -
Review the response to see the available versions. If multiple versions are listed, the connector supports multi-versioning.
Example output:
{
"plugin_name": "aiven-kafka-connect-jdbc",
"available_versions": [
{
"version": "6.10.0",
"deprecated": false
},
{
"version": "6.9.0",
"deprecated": true
}
]
}
-
Run the following command:
avn service connector available <service_name>
-
Review the output to see the available versions. If multiple versions are listed, the connector supports multi-versioning.
Example output:
{
"plugin_name": "aiven-kafka-connect-jdbc",
"available_versions": [
{
"version": "6.10.0",
"deprecated": false
},
{
"version": "6.9.0",
"deprecated": true
}
]
}
Set a connector version
To set a specific connector version, update the plugin_versions
property in the
service configuration using the API, CLI, or Terraform. In the Aiven Console, you can
select the version through the UI.
The selected version applies to all instances of the connector, including both source and
sink connectors. For example, setting
the aiven-kafka-connect-jdbc
plugin to version 6.9.0
affects both the JDBC source
and sink connectors.
Changing the connector version restarts the Apache Kafka Connect service and reloads all plugins. This process can take several minutes.
- Aiven Console
- Aiven API
- Aiven CLI
- Terraform
Connector version selection in the Aiven Console is available only for dedicated Apache Kafka Connect services.
- In your Aiven for Apache Kafka Connect service, click Connectors.
- In the Enabled connectors section, locate the connector to update.
- Click Actions > Change connector version.
- In the Version setup window:
-
Select the version to use.
-
Optional: If you select the latest version, you can turn on Enable version updates to automatically update the connector to newer versions during maintenance updates.
noteEnable version updates is available only for the latest (default) version. This option is unavailable for older versions because automatic updates apply only to the latest version.
-
- Depending on your selection, click:
- Install version and restart service to apply the selected version.
- Confirm version to keep the current version.
If you change the version, the connector installs the new package and restarts. The selected version applies to all instances of the connector, including both source and sink connectors.
-
Run the following command:
curl -X PUT "https://api.aiven.io/v1/project/<project_name>/service/<service_name>" \
-H "Authorization: Bearer <api_token>" \
-H "Content-Type: application/json" \
-d '{
"user_config": {
"plugin_versions": [{
"plugin_name": "<plugin_name>",
"version": "<version>"
}]
}
}'Parameters:
<project_name>
: Aiven project name.<service_name>
: Apache Kafka Connect service name.<api_token>
: Aiven API token.<plugin_name>
: Plugin name. For example,aiven-kafka-connect-jdbc
.<version>
: Desired version of the plugin. For example,6.9.0
.
-
Verify the update in the service configuration:
curl -X GET "https://api.aiven.io/v1/project/<project_name>/service/<service_name>" \
-H "Authorization: Bearer <api_token>"
-
Run the following command:
avn service update <service_name> --project <project_name> \
-c plugin_versions='[{"plugin_name":"<plugin_name>","version":"<version>"}]'Parameters:
<service_name>
: Apache Kafka Connect service name.<project_name>
: Aiven project name.<plugin_name>
: Plugin name. For example,aiven-kafka-connect-jdbc
.<version>
: Desired version of the plugin. For example,6.9.0
.
-
Verify the update:
avn service get <service_name>
Use the plugin_versions
attribute
in your aiven_kafka_connect
resource.
Verify the connector version
After setting a version, confirm that the correct version is in use.
- Aiven API
-
Run the following command:
curl -X GET "https://api.aiven.io/v1/project/<project_name>/service/<service_name>" \
-H "Authorization: Bearer <api_token>" -
Review the
plugin_versions
property in the response to verify the set version.