Changing the Plan of an Apache Kafka on Heroku Cluster

Last updated June 30, 2026

This article describes the method for changing the plan of an Apache Kafka on Heroku cluster. To change the plan, you can use addons:upgrade. Changing your cluster plan requires some downtime to complete. See Choosing the Right Apache Kafka on Heroku Plan for a list of Apache Kafka on Heroku plans.

Upgrade the plan of your Apache Kafka on Heroku add-on with the heroku addons:upgrade CLI command.

Use this command to:

See the differences between multi-tenant and dedicated clusters.

You can’t use this command to:

  • Upgrade or downgrade between a multi-tenant plan and a dedicated plan.
  • Upgrade or downgrade between Common Runtime plans and Private or Shield tier plans.

These cases require a migration between your source and target Kafka add-ons.

You can’t downgrade to a smaller plan if the Kafka cluster’s data size is over the limit of the plan you want to downgrade to.

Find Your Cluster Resource Name

To upgrade your Apache Kafka on Heroku plan, first, find the resource name of the Kafka cluster you want to upgrade. The resource name is a globally unique name of the cluster across all of your apps and add-ons:

$ heroku kafka:info -a example-app
=== kafka-animated-39618

Plan:       heroku-kafka:standard-0
Status:     available
Version:    3.7.1
Created:    2026-06-01 16:28:54 +0000
Topics:     84 topics, see heroku kafka:topics
Partitions: [··········] 417 / 12000 partition replicas (partitions × replication factor)
Messages:   5 message/s
Traffic:    32 byte/s in / 166 byte/s out
Data Size:  [··········] 68.38 MB / 150.00 GB (0.04%)
Add-on:     kafka-animated-39618

Upgrade Plan

This example upgrades kafka-animated-39618 from a standard-0 plan to a extended-1 plan.

$ heroku addons:upgrade kafka-animated-39618 extended-1 -a example-app
Changing kafka-animated-39618 on ⬢ example-app from heroku-kafka:standard-0 to heroku-kafka:extended-1... done, ~$6.944/hour (max $5000/month)
Kafka cluster is being upgraded, and will be ready shortly.
Please use `heroku kafka:wait` to monitor the status of your upgrade.

The process of scaling up or down plan levels of Apache Kafka on Heroku is performed in-place and doesn’t require cluster downtime. Heroku rebalances the partition between brokers if the plan change for the upgrade or downgrade requires adding new brokers or removing existing ones.

However, you must migrate the data when moving between multi-tenant and dedicated plans, or between Common Runtime and Private or Shield Spaces.

Check Upgrade Status

Follow the plan upgrade process with the heroku kafka:wait CLI command:

$ heroku kafka:wait -a example-app
Waiting for cluster kafka-animated-39618... ⡿ upgrading

Alternatively, you can also use heroku kafka:info to check the status of your add-on:

$ heroku kafka:info kafka-convex-12345 -a example-app
=== kafka-animated-39618

Plan:       heroku-kafka:extended-1
Status:     upgrading
Version:    3.7.1
Created:    2026-06-01 16:28:54 +0000
Topics:     84 topics, see heroku kafka:topics
Partitions: [··········] 417 / 12000 partition replicas (partitions × replication factor)
Messages:   5 message/s
Traffic:    32 byte/s in / 166 byte/s out
Data Size:  [··········] 68.38 MB / 150.00 GB (0.04%)
Add-on:     kafka-animated-39618

The time it takes to complete an upgrade depends on the difference of the plans and the size of the stream volume. If the upgrade or downgrade is between levels of the same tier, for example, standard-0 to standard-1, the upgrade is almost immediate. If the upgrade or downgrade is between different tiers, for example, standard to extended, we create or remove the extra brokers that each plan offers and rebalance partitions between the final number of brokers. There’s no downtime in this process, but the upgrade takes time to complete depending on the size of the cluster.