Upgrade

The Confluent Platform will be referred to as “CP.” Apache Kafka will be referred to as “Kafka”.

Note

If you are a Confluent Platform subscriber, and you have questions about upgrades (or need help), please feel free to contact us through our Support Portal.

Preparation

Consider the below guidelines in preparation for the upgrade.

  • Always back up all configuration files before upgrading. This includes /etc/kafka, /etc/kafka-rest, /etc/schema-registry and /etc/camus.
  • Read through the documentation and draft an upgrade plan that matches your specific requirements and environment before starting the upgrade process. Put differently, don’t start working through this guide on a live cluster. Read the guide entirely, make a plan, then execute the plan.
  • Pay careful consideration to the order in which components are upgraded. Starting with version 0.10.2, Java clients (producer and consumer) have acquired the ability to communicate with older brokers. Version 0.10.2 clients can talk to version 0.10.0 or newer brokers. However, if your brokers are older than 0.10.0, you must upgrade all the brokers in the Kafka cluster before upgrading your clients. Version 0.10.2 brokers support 0.8.x and newer clients. Before 0.10.2, Kafka is backward compatible, which means that clients from Kafka 0.8.x releases (CP 1.0.x) will work with brokers from Kafka 0.9.x, 0.10.0, 0.10.1 and 0.10.2 releases (CP 2.0.x, 3.0.x, 3.1.x and 3.2.x), but not vice-versa. This means you always need to plan upgrades such that all brokers are upgraded before clients. Clients include any application that uses Kafka producer or consumer, command line tools, Camus, Schema Registry, Rest Proxy, Kafka Connect and Kafka Streams.
    • IMPORTANT: Due to a bug introduced in Kafka 0.9.0.0 (CP 2.0.0), clients that depend on ZooKeeper (old Scala high-level Consumer and MirrorMaker if used with the old consumer) will not work with 0.10.x.x brokers. Therefore, Kafka 0.9.0.0 (CP 2.0.0) clients should be upgraded to 0.9.0.1 (CP 2.0.1) before brokers are upgraded to 0.10.x.x. This step is not necessary for 0.8.x or 0.9.0.1 clients.
    • IMPORTANT: although not recommended, some deployments have clients co-located with brokers (on the same node). In these cases, both the broker and clients share the same packages. This is problematic because all brokers must be upgraded before clients are upgraded. Pay careful attention to this when upgrading.
  • Kafka 0.10.2.0 contains changes with potential compatibility impact and deprecations with respect to previous major versions (i.e. 0.8.x.x and 0.9.x.x). Refer to the Kafka documentation to understand how they affect applications using Kafka.
  • Read the Confluent Platform 3.2.2 Release Notes. They contain not only information about noteworthy features, but also changes to configurations that may impact your upgrade.

Step-by-step Guide

  1. Determine if clients are co-located with brokers. If yes, ensure all client processes are not upgraded until all Kafka brokers have been upgraded.
  2. Decide on performing a rolling upgrade or a downtime upgrade. Confluent Platform supports both rolling upgrades (upgrade one broker at a time to avoid cluster downtime) and downtime upgrades (take down the entire cluster, upgrade it, and bring everything back up).
  3. Upgrade all Kafka brokers (more below).
  4. Upgrade Schema Registry, Rest Proxy and Camus (more below).
  5. If it makes sense, build applications that use Kafka producers and consumers against the new 0.10.2.x libraries and deploy the new versions. See Application Development documentation for more details on using the 0.10.2.x libraries.

Upgrade All Kafka Brokers

In a rolling upgrade scenario, upgrade one Kafka broker at a time. In a downtime upgrade scenario, take the entire cluster down, upgrade each Kafka broker, then start the cluster.

Steps to upgrade for any fix pack release (e.g. 3.1.1 to 3.1.2): Any fix pack release will be able to perform a rolling upgrade by simply upgrading each broker one at a time. For each broker:

  1. Stop the broker
  2. Upgrade the software (see below for your packaging type)
  3. Start the broker

Steps for 3.0.x/3.1.x to 3.2.x upgrade: In a rolling upgrade scenario, upgrading from CP 3.0.x (Kafka 0.10.0.x) or CP 3.1.x (Kafka 0.10.1.x) to CP 3.2.x (Kafka 0.10.2.x) requires special steps because Kafka 0.10.2.x included a change to the inter-broker protocol. Follow the below steps for a rolling upgrade:

  1. Modify server.properties on all Kafka brokers by adding/changing the following properties (you can edit these while the brokers are still running):
    • inter.broker.protocol.version=0.10.1 (0.10.0 for 3.0.x)
    • log.message.format.version=0.10.1 (0.10.0 for 3.0.x)
  2. Upgrade each Kafka broker, one at a time (see below).
  3. Once all Kafka brokers have been upgraded, modify server.properties again by changing the following properties: inter.broker.protocol.version=0.10.2, log.message.format.version=0.10.2.
  4. Restart each Kafka broker, one at a time, to apply the configuration change.

Steps for 2.0.x to 3.2.x upgrade: In a rolling upgrade scenario, upgrading from CP 2.0.x (Kafka 0.9.0.x) to CP 3.2.x (Kafka 0.10.2.x) requires special steps because Kafka 0.10.0.x included a change to the inter-broker protocol and the on-disk data format. Follow the below steps for a rolling upgrade:

  1. Modify server.properties on all Kafka brokers by adding/changing the following properties (you can edit these while the brokers are still running):
    • inter.broker.protocol.version=0.9.0.1
    • log.message.format.version=0.9.0.1 (required, improves broker performance if most of your clients are still 0.8.x or 0.9.0.x)
  2. Upgrade each Kafka broker, one at a time (see below).
  3. Once all Kafka brokers have been upgraded, modify server.properties again by changing the following property: inter.broker.protocol.version=0.10.2 (0.10.2 instead of 0.9.0.1).
  4. Restart each Kafka broker, one at a time, to apply the configuration change.
  5. Once most clients are using 0.10.2.x, remove the log.message.format.version property to optimize broker performance for 0.10.2.x clients.
  6. Restart each Kafka broker, one at a time, to apply the configuration change.

Instructions for both deb packages and rpm packages are below. For zip and tar archives, the old archives directory can be simply deleted after the new archive folder has been created and any old configuration files copied over.

deb packages via apt

  1. Backup all configuration files from /etc, including /etc/kafka, /etc/kafka-rest, /etc/schema-registry and /etc/camus.

  2. Stop the services and remove the existing packages and their dependencies. As mentioned above, this can be done on one server at a time for rolling upgrade.

    # The example below removes the Kafka package (for Scala 2.11, which is the default for CP 3.0.x)
$ sudo kafka-server-stop
$ sudo apt-get remove confluent-kafka-2.11

# To remove Confluent-Platform and all its dependencies at once, run the following after stopping all services
$ sudo apt-get autoremove confluent-platform-2.11

  3. Remove the repository files of the previous version

    $ sudo add-apt-repository -r "deb http://packages.confluent.io/deb/3.2 stable main"

  4. Add the 3.2 repository to /etc/apt/sources.list

    $ sudo add-apt-repository "deb http://packages.confluent.io/deb/3.2 stable main"

  5. Refresh repository metadata

    $ sudo apt-get update

  6. Install the new version: (Note that if you modified the configuration files, apt will prompt you to resolve the conflicts. You will want to keep your original configuration).

    $ sudo apt-get install confluent-platform-2.11

# Or install the packages you need one by one. For example, to install just Kafka:
$ sudo apt-get install confluent-kafka-2.11

  7. Start services.

    $ kafka-server-start -daemon /etc/kafka/server.properties

rpm packages via yum

  1. Backup all configuration files from /etc, including /etc/kafka, /etc/kafka-rest, /etc/schema-registry and /etc/camus.

  2. Stop the services and remove the existing packages and their dependencies. As mentioned above, this can be done on one server at a time for rolling upgrade.

    # The example below removes the Kafka package (for Scala 2.11, which is the default for CP 3.0.x)
$ sudo kafka-server-stop
$ sudo yum remove confluent-kafka-2.11

# To remove Confluent-Platform and all its dependencies at once, run the following after stopping all services
$ sudo yum autoremove confluent-platform-2.11

  3. Remove the repository files of the previous version

    $ sudo rm /etc/yum.repos.d/confluent.repo

  4. Add the repository to your /etc/yum.repos.d/ directory in a file named confluent-3.2.repo.

    [confluent-3.2]
name=Confluent repository for 3.2.x packages
baseurl=http://packages.confluent.io/rpm/3.2
gpgcheck=1
gpgkey=http://packages.confluent.io/rpm/3.2/archive.key
enabled=1

  5. Refresh repository metadata

    $ sudo yum clean all

  6. Install the new version. Note that yum may override your existing configuration files, so you will need to restore them from backup after installing the packages:

    $ sudo yum install confluent-platform-2.11

# Or install the packages you need one by one. For example, to install just Kafka:
$ sudo yum install confluent-kafka-2.11

  7. Start services.

    $ kafka-server-start -daemon /etc/kafka/server.properties

TAR or ZIP archives

  1. Go to the directory where you installed the Confluent Platform.

  2. Backup all configuration files from ./etc, including ./etc/kafka, ./etc/kafka-rest, ./etc/schema-registry, ./etc/confluent-control-center``and ``./etc/camus.

  3. Stop the services and remove the existing packages and their dependencies. As mentioned above, this can be done on one server at a time for rolling upgrade.

    $ ./bin/control-center-stop
$ ./bin/kafka-rest-stop
$ ./bin/schema-registry-stop
$ ./bin/kafka-server-stop
$ ./bin/zookeeper-server-stop

# To remove Confluent-Platform and all its dependencies at once, run the following after stopping all services
$ cd ..
$ rm -R confluent-1.0.1 (or confluent-2.0.1 or confluent-3.0.1 or confluent-3.1.2)

  4. Unpack the new archive. Note that yum may override your existing configuration files, so you will need to restore them from backup after installing the packages:

    $ tar xzf confluent-3.2.2-2.11.tar.gz

# Or for ZIP archives:

$ unzip confluent-3.2.2-2.11.zip

  5. Start services.

    $ sudo confluent-3.2.2/bin/zookeeper-server-start -daemon /etc/kafka/zookeeper.properties
$ sudo confluent-3.2.2/bin/kafka-server-start -daemon /etc/kafka/server.properties

Upgrade Schema Registry

The Schema Registry service can be upgraded once all Kafka brokers have been upgraded.

To upgrade the Schema Registry service, follow the same steps above to upgrade the package (backup config files, remove packages, install upgraded packages, etc.). Then, restart the Schema Registry service.

Upgrade Kafka REST Proxy

The Kafka REST Proxy service can be upgraded once all Kafka brokers have been upgraded.

To upgrade the Kafka REST Proxy service, follow the same steps above to upgrade the package (backup config files, remove packages, install upgraded packages, etc.). Then, restart the Kafka REST Proxy service.

Upgrade Kafka Streams applications

Kafka Streams applications can be upgraded independently and without requiring Kafka brokers to have been upgraded first.

Please follow the instructions in the Kafka Streams Upgrade Guide to upgrade your applications to use the latest version of Kafka Streams.

Upgrade Kafka Connect

Upgrade Kafka Connect Standalone Mode

Kafka Connect in standalone mode can be upgraded once all Kafka brokers have been upgraded.

To upgrade Kafka Connect, follow the same steps above to upgrade the package (backup config files, remove packages, install upgraded packages, etc.). Then, restart the client processes.

Upgrade Kafka Connect Distributed Mode

A new required configuration, status.storage.topic was added to Kafka Connect in 0.10.0.1. To upgrade a Kafka Connect cluster, this configuration should be added before updating to the new version. The setting will be ignored by older versions of Kafka Connect.

  1. Backup worker configuration files.
  2. Modify your configuration file to add the status.storage.topic setting. You can safely modify the configuration file while the worker is running. Note that you should create this topic manually. See the Distributed Mode Configuration section of the Connect User Guide for a detailed explanation.
  3. Perform a rolling restart of the workers.

Upgrade Camus

Camus can be upgraded once all Kafka brokers have been upgraded.

To upgrade Camus, follow the same steps above to upgrade the package (backup config files, remove packages, install upgraded packages, etc.). Then, restart Camus.

Upgrade Other Client Applications

Any other client applications (e.g. applications that use Kafka’s producer or consumer clients in Java, C/C++, or Python) can be upgraded once all Kafka brokers have been upgraded.

As mentioned above, if it makes sense, build applications that use Kafka producers and consumers against the new 0.10.2.x libraries and deploy the new versions. See Application Development documentation for more details on using the 0.10.2.x libraries.

Confluent Control Center

Control Center can be upgraded once all Kafka brokers have been upgraded.

Please follow the instructions in the Control Center Upgrade Guide.