Help Center/ Distributed Message Service for Kafka/ User Guide/ Managing Instances/ Upgrading the Kafka Instance Kernel
Updated on 2026-07-14 GMT+08:00
View PDF

Upgrading the Kafka Instance Kernel

Upgrade your Kafka instance kernel to use the latest kernel version. A kernel upgrade adds certain new features and resolves certain earlier issues. For example, new features may include consumer group creation on the console and topic details viewing.

Kafka instance kernel upgrades have no impact on the Kafka version. For example, if you use Kafka 2.7, you will still be using it after a kernel upgrade.

Impact of Kernel Upgrades

  • Single-replica topics do not support message production and consumption during an upgrade, which will cause service interruptions.
  • If a topic has multiple replicas, upgrades do not interrupt services. Brokers are restarted in sequence and the workload is shifted to the remaining brokers. Evaluate this impact and avoid peak hours.
  • Brokers are upgraded one by one. The upgrade involves software package upgrade and data synchronization. Upgrading the software package takes about 5 minutes. Synchronizing the data takes longer as the data volume of other brokers' leader replica becomes larger. Total upgrade duration = Software package upgrade duration of each broker + Data synchronization duration
  • During the upgrade, the partition leader may change, which may cause repeated message delivery. If the leader changes before the consumer commits the offset after processing messages, the consumer will consume messages from the last offset after reconnect. As a result, some messages are processed repeatedly. To ensure service data consistency, implement the idempotent processing logic on the consumer.
  • During the upgrade, the monitoring process is restarted on each broker, causing monitoring data breakpoints. After the restart, the monitoring data will be restored.
  • Broker rolling restarts will cause partition leader changes, interrupting connections for less than a minute when the network is stable. For multi-replica topics, configure the retry mechanism on the producer client. To do so:
    • If you use an open-source Kafka client, configure the retries and retry.backoff.ms parameters. You are advised to set retries to 10 and retry.backoff.ms to 1000.
    • Flink: Configure the retry policy by referring to the following code: 
      StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment();
env.setRestartStrategy(RestartStrategies.fixedDelayRestart(10, Time.seconds(20)));

Prerequisites

The instance must be in the Running state.

Procedure

  1. Log in to the Kafka console.
  2. Click in the upper left corner to select the region where your instance is located.
  3. Upgrade a Kafka instance using either of the following methods:

    • Choose More > Upgrade in the row containing the desired instance.
    • Click the name of the Kafka instance to go to the instance details page. Choose > Upgrade in the upper right corner.

  4. Set Execute to Now or As scheduled.

    If you select As scheduled, specify date and time.

  5. In the Risk Check area, check whether the items are normal.

    If any risk is found, handle it as prompted and click Recheck. If the risk does not need to be handled, select I understand the risks.

  6. Click OK.

    The method of checking the upgrade result depends on when the upgrade is executed.

    Table 1 Checking the upgrade result

    Execution

    Check Method

    Now
    1. Click an instance name to go to the instance details page.
    2. Choose Instance > Background Tasks in the navigation pane.
    3. Check the upgrade task status on the Current Tasks tab page.
      • The upgrade is complete when the task is in the Successful state.
      • The upgrade failed when the task is in the Failed state. Contact customer service.

    As scheduled
    1. Click an instance name to go to the instance details page.
    2. Choose Instance > Background Tasks in the navigation pane.
    3. On the Scheduled tasks tab page, check whether the upgrade task is started.
      • The task has not been started when it is in the Pending state.
      • The task has been started when it is in the Successful state.
    4. Check the upgrade task status on the Current Tasks tab page.
      • The upgrade is complete when the task is in the Successful state.
      • The upgrade failed when the task is in the Failed state. Contact customer service.

Modifying Scheduled Upgrade Tasks

  1. Go to the Scheduled tasks tab page on the Instance > Background Tasks page, click the drop-down box in the upper left corner and select a period. Enter "upgrade" in the search box and press Enter.
  2. Click Modify in the row containing the desired task.
  3. In the Change Schedule dialog box, reschedule or cancel the task.

    • To reschedule: Specify a new time and click OK.
    • To cancel: Select Cancel and click OK.

Related Document

To upgrade the kernel version of a Kafka instance by calling an API, see Upgrading an Instance.

Parent topic: Managing Instances