Manage connector versions in Aiven for Apache Kafka Connect®

Multi-version connector support lets you control which connector version is used in your Aiven for Apache Kafka Connect® service. 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 for multi-version connectors

• 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 any, are detailed 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.
• 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.
• If no version is set, the latest available version is used.
• Refer to Check available connector versions to confirm which versions are supported before setting a version.

Supported connectors and versions

note

All versions listed in the table are supported unless explicitly noted otherwise.

Connector	Versions
Debezium	2.5.0 (recommended) 1.9.7 (deprecated)
JDBC	6.10.0 (recommended) 6.9.0 (deprecated)
Snowflake	2.3.0 (recommended) 2.2.0

tip

This is a partial list of connectors, and it may change as new versions are released. To view the most up-to-date versions, see Check available connector versions.

note

If you are using version 1.9.7 of the Debezium connector, you can upgrade to version 2.5.0 without raising a support ticket. To upgrade, set version 2.5.0 in your configuration. For details, see Set a connector version.

Prerequisites

• Aiven for Apache Kafka® service with a dedicated Aiven for Apache Kafka Connect® service enabled

  note

  Multi-version support is only available for dedicated Apache Kafka Connect services.

• 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

1. Access the Aiven Console.
2. Select your Aiven for Apache Kafka Connect service.
3. 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.

Aiven API

1. 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>"

2. 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
        }
    ]
   }

Aiven CLI

1. Run the following command:

   avn service connector available <service_name>

2. 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
        }
      ]
    }

Terraform

In Terraform, you can specify the desired connector version using the plugin_versions attribute in your configuration. This ensures that your Apache Kafka Connect service uses the exact version you need.

For detailed steps and examples, see Set a connector version.

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

1. In your Aiven for Apache Kafka Connect service, click Connectors.
2. In the Enabled connectors section, locate the connector to update.
3. Click Actions > Change connector version.
4. 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.

5. 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.

Aiven API

1. 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.

2. 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>"

Aiven CLI

1. 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.

2. Verify the update:

   avn service get <service_name>

Terraform

1. Update your Terraform configuration:

   resource "aiven_kafka_connect" "my_aiven_kafka_connect" {
     service_name = "<service_name>"
     project      = "<project_name>"
   
     kafka_connect_user_config {
       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.

2. Apply the changes:

   terraform apply

3. Confirm the updated configuration:

   terraform show

For detailed information, refer to the Terraform Registry - plugin_versions.

Verify the connector version

After setting a version, confirm that the correct version is in use.

Aiven API

1. Run the following command:

   curl -X GET "https://api.aiven.io/v1/project/<project_name>/service/<service_name>" \
   -H "Authorization: Bearer <api_token>"
   

2. Review the plugin_versions property in the response to verify the set version.

Aiven CLI

1. Run the following command:

   avn service get <service_name>

2. Check the plugin_versions property in the output to confirm the version.

Terraform

Verify the version in your Terraform state or configuration after applying changes:

1. Run:

   terraform show

2. Locate the plugin_versions property under the Kafka Connect service resource. It displays the set version of the connector.