Roll back to the previous KCL version

This topic explains how to roll back your consumer application to the previous KCL version. The roll-back process consists of two steps:

1. Run the KCL Migration Tool.

2. Redeploy previous KCL version code.

Step 1: Run the KCL Migration Tool

When you need to roll back to the previous KCL version, you must run the KCL Migration Tool. The tool performs two important tasks:

• It removes a metadata table called worker metrics table and global secondary index on the lease table in DynamoDB. These artifacts are created by KCL 3.x but aren't needed when you roll back to the previous version.

• It makes all workers run in a mode compatible with KCL 1.x and start using the load balancing algorithm used in previous KCL versions. If you have issues with the new load balancing algorithm in KCL 3.x, this will mitigate the issue immediately.

Important

The coordinator state table in DynamoDB must exist and must not be deleted during the migration, rollback, and rollforward process.

Note

It's important that all workers in your consumer application use the same load balancing algorithm at a given time. The KCL Migration Tool makes sure that all workers in your KCL 3.x consumer application switch to the KCL 1.x compatible mode so that all workers run the same load balancing algorithm during the application rollback to the previous KCL version.

You can download the KCL Migration Tool in the scripts directory of the KCL GitHub repository. Run the script from a worker or host with appropriate permissions to write to the coordinator state table, worker metrics table, and lease table. Ensure the appropriate IAM permissions are configured for KCL consumer applications. Run the script only once per KCL application using the specified command:

python3 ./KclMigrationTool.py --region region --mode rollback [--application_name applicationName] [--lease_table_name leaseTableName] [--coordinator_state_table_name coordinatorStateTableName] [--worker_metrics_table_name workerMetricsTableName]

Parameters

--region

Replace region with your AWS Region.

--application_name

This parameter is required if you're using default names for your DynamoDB metadata tables (lease table, coordinator state table, and worker metrics table). If you have specified custom names for these tables, you can omit this parameter. Replace applicationName with your actual KCL application name. The tool uses this name to derive the default table names if custom names are not provided.

--lease_table_name

This parameter is needed when you have set a custom name for the lease table in your KCL configuration. If you're using the default table name, you can omit this parameter. Replace leaseTableName with the custom table name you specified for your lease table.

--coordinator_state_table_name

This parameter is needed when you have set a custom name for the coordinator state table in your KCL configuration. If you're using the default table name, you can omit this parameter. Replace coordinatorStateTableName with the custom table name you specified for your coordinator state table.

--worker_metrics_table_name

This parameter is needed when you have set a custom name for the worker metrics table in your KCL configuration. If you're using the default table name, you can omit this parameter. Replace workerMetricsTableName with the custom table name you specified for your worker metrics table.

Step 2: Redeploy the code with the previous KCL version

Important

Any mention of version 2.x in the output generated by the KCL Migration Tool should be interpreted as referring to KCL version 1.x. Running the script does not perform a complete rollback, it only switches the load balancing algorithm to the one used in KCL version 1.x.

After running the KCL Migration Tool for a rollback, you'll see one of these messages:

Message 1

"Rollback completed. Your application was running 2x compatible functionality. Please rollback to your previous application binaries by deploying the code with your previous KCL version."

Required action: This means that your workers were running in the KCL 1.x compatible mode. Redeploy the code with the previous KCL version to your workers.

Message 2

"Rollback completed. Your KCL Application was running 3x functionality and will rollback to 2x compatible functionality. If you don't see mitigation after a short period of time, please rollback to your previous application binaries by deploying the code with your previous KCL version."

Required action: This means that your workers were running in KCL 3.x mode and the KCL Migration Tool switched all workers to KCL 1.x compatible mode. Redeploy the code with the previous KCL version to your workers.

Message 3

"Application was already rolled back. Any KCLv3 resources that could be deleted were cleaned up to avoid charges until the application can be rolled forward with migration."

Required action: This means that your workers were already rolled back to run in the KCL 1.x compatible mode. Redeploy the code with the previous KCL version to your workers.