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 the config block in Terraform) is not supported and has no effect. To control connector versions, use the plugin_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.

warning

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.

note

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.

note

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

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.

note

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.

note

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

note

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.
  
  note
  Enable 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.

note

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.

Benefits​

Key considerations​

Limitations​

Prerequisites​

Check available connector versions​

Set a connector version​

Verify the connector version​

Benefits

Key considerations

Limitations

Prerequisites

Check available connector versions

Set a connector version

Verify the connector version