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 pin 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.
• Pinning 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 pinned, the latest available version is used.
• Refer to Check available connector versions to confirm which versions are supported before pinning 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, pin version 2.5.0 in your configuration. For details, see Pin a connector 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

note

Multi-version support is only available for dedicated Kafka Connect services. Ensure that your service is updated to enable this feature.

Check available connector versions

Before pinning a connector version, check which versions are available for your Apache Kafka Connect service. Verify if a connector supports multi-versioning by reviewing the listed versions. Use one of the following methods:

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 Pin a connector version.

Pin a connector version

To use a specific connector version, update the plugin_versions property in the service configuration. Pinning a plugin version applies to all connectors (source and sink) provided by that plugin. For example, pinning the aiven-kafka-connect-jdbc plugin to version 6.9.0 affects both the JDBC source and sink connectors.

note

Pinning a plugin version restarts Apache Kafka Connect and reloads all plugins. Allow time for the process to complete.

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 pinning 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 pinned 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 pinned version of the connector.