Sign in Subscribe

Upgrading Kestra to v0.24 from v0.21 and Below: Key Changes, Migration Steps, and Database Cleanup

Last updated on 

If you’re running Kestra OSS and haven’t updated since before version v0.21, the release of Kestra v0.24 brings several important improvements, optimizations, and breaking changes that you should prepare for. In this guide, we’ll walk through the update process, highlight the tenant migration from default to main, and explain how to safely delete inactive rows from your PostgreSQL database.

Whether you’re a DevOps engineer, system administrator, or developer, following these steps will ensure your upgrade runs smoothly.

Why Upgrade to Kestra v0.24?

Kestra is an open-source orchestration engine that evolves rapidly. By upgrading to v0.24, you benefit from:

  • Improved workflow performance with optimized execution handling.
  • Stronger tenant management, moving from the legacy default tenant to main.
  • Bug fixes and security patches that improve overall system reliability.
  • New features that make workflow orchestration more flexible and developer-friendly.

Running older versions (< v0.21) puts your system at risk of compatibility issues and missed enhancements.

Preparing for the Upgrade

Before starting the migration, make sure to:

  1. Backup your PostgreSQL database:pg_dump -U kestra -h localhost kestra_db > kestra_backup.sql
  2. Check plugin compatibility: Some plugins may have changed between v0.21 and v0.24.
  3. Review configuration files: Look for deprecated settings and align them with the new defaults in v0.24.

Migrating Tenants: From default to main

One of the most important changes in Kestra OSS is the migration of tenants.

  • Older versions (< v0.21) used a default tenant.
  • From v0.24 onward, Kestra OSS standardizes on main as the tenant identifier.

How to Update Tenant References with Docker Compose

If you’re running Kestra with Docker Compose, you can run the built-in Kestra migration command directly inside the container. It is assumed that your container is called "kestra-con".

Run the tenant migration command:docker compose exec kestra-con ./kestra migrate tenants --to=main
This command automatically updates all tenant references (executions, flows, namespaces, etc.) from default to main.

  1. Verify the migration:docker compose exec kestra-con ./kestra list tenants
    You should now see main as the active tenant.
  2. Update your configuration files (application.yml or environment variables in docker-compose.yml) to use main.

Cleaning Up Inactive Rows in PostgreSQL

Over time, Kestra databases can accumulate rows in state INACTIVE, which are no longer needed. Cleaning them up improves performance and reduces storage usage.

Safely Delete Inactive Rows

  1. Check how many inactive rows exist:SELECT COUNT(*) FROM service_instanceexecutions WHERE state = 'INACTIVE';
  2. Delete in batches (recommended for large datasets):DELETE FROM service_instance WHERE state = 'INACTIVE' LIMIT 1000;
    (Run multiple times until count reaches zero.)
  3. Or delete all inactive rows at once (if database size allows):DELETE FROM service_instance WHERE state = 'INACTIVE';
  4. Vacuum the database to reclaim space:vacuumdb -U kestra -h localhost --full --analyze kestra_db

Final Steps After Upgrade

After updating Kestra to v0.24 and cleaning up your database:

  • Restart Kestra services: systemctl restart kestra
  • Verify tenant alignment:SELECT DISTINCT tenant FROM flows;
  • Run a test workflow to confirm everything works as expected.

Conclusion

Upgrading from Kestra v0.21 (and earlier) to v0.24 is an essential step to keep your orchestration platform modern, secure, and efficient.

The key steps involve:

  • Migrating tenants from default to main.
  • Cleaning up inactive rows in PostgreSQL for better performance.
  • Reviewing configs and restarting services, if necessary.

By following this guide, you’ll ensure a smooth migration and maintain a stable Kestra environment.

👉 Have you already upgraded to v0.24? Share your experience in the comments below!

About the author

Tim Wilkes is a UK-based security architect with over 15 years of experience in electronics, Linux, and Unix systems administration. Since 2021, he's been designing secure systems for a telecom company while indulging his passions for programming, automation, and 3D printing. Tim shares his projects, tinkering adventures, and tech insights here - partly as a personal log, and partly in the hopes that others will find them useful.

Want to connect or follow along?

LinkedIn: [phpsytems]
Twitter / X: [@timmehwimmy]
Mastodon: [@timmehwimmy@infosec.exchange]


If you've found a post helpful, consider supporting the blog - it's a part-time passion that your support helps keep alive.

⚠️ Disclaimer

This post may contain affiliate links. If you choose to purchase through them, I may earn a small commission at no extra cost to you. I only recommend items and services I’ve personally read or used and found valuable.

As an Amazon Associate I earn from qualifying purchases.