<a id="upgrade"></a>

# Upgrade Confluent Platform

Use these instructions to upgrade earlier versions of Confluent Platform to the latest Confluent Platform version.

The recommended upgrade order is to upgrade brokers, controllers, and
Confluent Control Center before client applications. For prerequisites and detailed
steps, see [Preparation](#upgrade-preparation).

#### NOTE
This guide covers upgrading manual Confluent Platform installations using Debian or RPM packages or TAR or ZIP archives.
If you are upgrading Confluent Platform with Confluent for Kubernetes, see [Upgrade Confluent Platform using Confluent for Kubernetes](https://docs.confluent.io/operator/current/co-upgrade-cp.html).
If you are upgrading Confluent Platform with Ansible Playbooks, see [Upgrade Confluent Platform with Confluent Ansible](https://docs.confluent.io/ansible/current/ansible-upgrade.html).

These steps apply only to upgrading from one Confluent Platform version to another.
If you want to migrate from an open source Kafka deployment to Confluent Platform, see [Migrate an Existing Kafka Deployment to Confluent Platform](migrating.md#migrate-kafka).
If you want to migrate from ZooKeeper to KRaft, see [Migrate from ZooKeeper to KRaft on Confluent Platform](migrate-zk-kraft.md#migrate-zk-kraft).

You should not upgrade and migrate at the same time.

#### IMPORTANT
Confluent Platform 8.3 does not support ZooKeeper for metadata management. If you are currently running ZooKeeper mode, you must upgrade to
to a version of Confluent Platform that supports migrating to KRaft, migrate to KRaft and then upgrade to Confluent Platform 8.3. For example:

1. If you are on a version earlier than 7.7.1, upgrade to Confluent Platform 7.7.1 or later in ZooKeeper mode.
2. Migrate to KRaft mode. For more information, see [Migrate from ZooKeeper to KRaft on Confluent Platform](migrate-zk-kraft.md#migrate-zk-kraft).
3. Upgrade to Confluent Platform 8.3.

Confluent Platform 8.3 includes many other changes, so read the [Release Notes for Confluent Platform 8.3](../release-notes/index.md#release-notes) and the [Changelogs](../release-notes/changelog.md#cp-changelog)
for your Confluent Platform components before you upgrade. For example, you must migrate to Log4j 2
before upgrading to Confluent Platform 8.3.

If you are a Confluent Platform subscriber, and you have questions about upgrades
or need help, you can contact Confluent using the [Support Portal](https://support.confluent.io/).

<a id="client-upgrade"></a>

## Upgrade prerequisite: client protocol deprecation

Confluent Platform 8.0 and later (based on Apache Kafka® 4.0) remove support for client protocol APIs older than Kafka 2.1.0, as per
[KIP-896](https://cwiki.apache.org/confluence/display/KAFKA/KIP-896%3A+Remove+old+client+protocol+API+versions+in+Kafka+4.0).
This is a breaking change. Any client, such as producer, consumer, or streams application, using a deprecated protocol version will
fail to connect after you upgrade your brokers to version 8.3.

Before you upgrade to Confluent Platform 8.3, you must identify and upgrade all non-compliant clients.

If you are already running Confluent Platform 8.0 or later, your clients are already
compliant because Confluent Platform 8.0 removed support for older protocols. The following
steps apply only when upgrading from a version earlier than Confluent Platform 8.0.

1. To detect the old clients, you must be running Confluent Platform version 7.7, 7.8, or 7.9. Version 7.9 is strongly recommended.
2. If you are on a version older than 7.7 (for example, 7.0), your upgrade path must be:
   1. Upgrade your cluster to a 7.7-7.9 version.
   2. Use the `DeprecatedRequestsPerSec` metric to scan for, identify, and upgrade all non-compliant clients.
   3. After you remediate all old clients, you can proceed with the upgrade to 8.3.

For instructions, see [How to identify deprecated client requests](../clients/deprecate-how-to.md#cp-identify-deprecated-clients).

<a id="upgrade-preparation"></a>

## Preparation

Before upgrading, complete these steps to protect your data and avoid
downtime.

* Read the [Release Notes for Confluent Platform 8.3](../release-notes/index.md#release-notes) and review the [Changelogs](../release-notes/changelog.md#cp-changelog) for your Confluent Platform components.
  : The release notes contain important information about noteworthy
    features, and changes to configurations that can impact your upgrade.
    Changelogs note updates to third-party
    components such as Jolokia or JMX exporters that might affect your system.
* Form a plan.
  : Read the documentation and draft an upgrade plan that matches your
    specific requirements and environment before starting the upgrade process. In
    other words, don’t start working through the [Upgrade Confluent Platform](#upgrade) guide on a live cluster. Read
    it entirely, make a plan, then execute the plan.
* Perform backups.
  : Before upgrading, always back up all configuration and unit files with their file
    permissions, ownership, and customizations.
    Confluent Platform might not run if the proper ownership isn’t preserved on configuration files. By default, configuration files are located
    in the `$CONFLUENT_HOME/etc` directory and are organized by component.
* Upgrade all components.
  : Upgrade your entire platform deployment so that all components are running
    the same version. Do not bridge component versions.
* Consider upgrade order.
  : The general recommended upgrade order is to upgrade your server-side components (brokers, controllers, and Confluent Control Center)
    before you upgrade your client applications. Newer brokers are designed to work with compliant older clients. As noted in
    the [KIP-896](https://cwiki.apache.org/confluence/display/KAFKA/KIP-896%3A+Remove+old+client+protocol+API+versions+in+Kafka+4.0) warning,
    this compatibility guarantee has changed. Confluent Platform 8.3 won’t communicate with clients using a protocol older than Kafka 2.1.0.
    <br/>
    The upgrade process must be:
    1. If you are upgrading from a version earlier than Confluent Platform 8.0:
       1. Upgrade to Confluent Platform 7.7, 7.8, or 7.9.
       2. Identify and upgrade all non-compliant clients.
    2. Upgrade Confluent Control Center to a version compatible with 8.3.
    3. Upgrade your brokers, controllers, and other server-side components to 8.3.
    4. Upgrade your compliant clients to the 8.3 libraries as needed to access new features.

Clients include any application that uses Kafka producers or consumers, command-line tools, Schema Registry, REST Proxy, Kafka Connect, and Kafka Streams.

* Determine if clients are colocated with brokers.
  : Although not recommended, some deployments have clients co-located with
    brokers (on the same node). In these cases, brokers and clients
    share the same packages. In this colocation case, ensure
    all client processes are not upgraded until *all* Kafka brokers have been upgraded.
* Decide between a rolling upgrade or a downtime upgrade.
  : Confluent Platform supports
    both rolling upgrades, meaning you upgrade one broker at a time to avoid cluster downtime,
    and downtime upgrades meaning you take down the entire cluster, upgrade it, and bring
    everything back up.
* Use Confluent Control Center for monitoring for a rolling restart.
  : Consider using [Control Center](/control-center/current/installation/overview.html) to
    monitor broker status during the [rolling restart](../kafka/post-deployment.md#rolling-restart).
* Set a license string.
  : The Confluent Platform package includes Confluent Server by default and requires a
    `confluent.license` key in your `server.properties` file.
    The Confluent Server broker checks for a license during startup. You must
    supply a license string in each broker’s properties file using the
    `confluent.license` property as shown in the following code:
    ```none
    confluent.license=LICENCE_STRING_HERE_NO_QUOTES
    ```
    <br/>
    If you want to use the Kafka broker, download the `confluent-community` package.
    The Kafka broker is the default in all Debian, RHEL, and CentOS packages.
* Run the correct version of Java.
  : Determine and install the appropriate Java version.
    See [Supported Java
    Versions](versions-interoperability.md#java-sys-req) for a list of Confluent Platform versions and the corresponding Java version support
    before you upgrade. For complete compatibility information, see [Supported Versions and Interoperability for Confluent Platform](versions-interoperability.md#interoperability-versions).
* Validate list-based configuration requirements.
  : Kafka 4.2 enforces stricter validation for `LIST`-type configurations. It
    no longer accepts null values, duplicate entries, or empty lists for most
    list-based configurations, and reclassifies some configurations from
    string to list. Review all list-based configuration properties, because
    invalid configurations cause startup failures. Verify all list
    configurations before starting the upgrade.
* Review deprecated and updated configurations.
  : In Kafka 4.2, `log.cleaner.enable` is deprecated and has no effect because log cleaning is always enabled.
    Additionally, `cleanup.policy` now supports empty values to enable infinite retention (disabling
    both deletion and compaction). Review any topics where infinite retention can be desired.
    For Confluent Platform deprecations to review before you upgrade, see
    [the list of deprecations](#cp-deprecations).
    For deprecated and removed Kafka configurations, see the
    [Apache Kafka documentation](https://kafka.apache.org/documentation/).
* Review metadata version limitations.
  : Kafka 4.2 and later introduce metadata changes that prevent cluster
    metadata downgrade. Rolling back from Confluent Platform 8.3 to an earlier version
    might require restoring from backups. Ensure you have a comprehensive
    backup and recovery strategy before you upgrade to Confluent Platform 8.3.
* Configure share groups.
  : If your cluster has fewer than 3 brokers and you plan to use share groups, set
    `share.coordinator.state.topic.replication.factor` and
    `share.coordinator.state.topic.min.isr` to `1`. Share groups use an internal topic
    called `__share_group_state` that is created automatically the first time you use
    share groups. By default, this topic requires 3 replicas and at least 3 brokers.

<a id="cp-deprecations"></a>

## Deprecations

Confluent Platform deprecates the following items as of the version shown and removes them in
a later release. Migrate to the replacement before you upgrade to the removal
version. For the complete list of Confluent Platform deprecations, see
[deprecated features and components](../deprecations.md#deprecations).

| Deprecated item                                                            |   Deprecated in | Replacement                                                                                                      |   Removal |
|----------------------------------------------------------------------------|-----------------|------------------------------------------------------------------------------------------------------------------|-----------|
| `group.coordinator.rebalance.protocols` broker configuration               |             8.3 | Feature versions `group.version`, `streams.version`, and `share.version`, managed with the `kafka-features` tool |         9 |
| `kafka-streams-scala` module, the `org.apache.kafka.streams.scala` package |             8.3 | Java Kafka Streams DSL                                                                                           |         9 |
| `--max-partition-memory-bytes` option on `kafka-console-producer`          |             8.2 | `--batch-size`                                                                                                   |         9 |

The Classic consumer rebalance protocol remains the default and is fully
supported in Confluent Platform 8.3. As advance notice,
[KIP-1274](https://cwiki.apache.org/confluence/display/KAFKA/KIP-1274%3A+Deprecate+and+remove+support+for+Classic+rebalance+protocol+in+KafkaConsumer)
plans to change the `KafkaConsumer` default to `group.protocol=consumer` in
Confluent Platform 9.0 and to remove the Classic protocol from `KafkaConsumer` in Confluent Platform 10.0.
To prepare, begin migrating consumer applications to the new consumer group
protocol.

<a id="upgrade-procedures"></a>

## Upgrade order

Before starting the 8.3 upgrade, you must ensure all clients are compatible. Review the [Upgrade prerequisite: client protocol deprecation](#client-upgrade) (KIP-896) notice at the top of this topic.

The recommended multi-stage upgrade process is as follows:

### Stage 1: Preparation (If you are on Confluent Platform 7.7 or earlier)

1. If you are running a Confluent Platform version older than 7.7, first upgrade your cluster to a version between 7.7 and 7.9. Version 7.9 is strongly recommended.
   Follow the upgrade documentation for that specific version.
2. After you are on a 7.7–7.9 version, use the `DeprecatedRequestsPerSec` metric to scan for and identify all clients using a protocol version older than Kafka 2.1.0.
3. Remediate, disable, or upgrade all non-compliant clients. Do not proceed to Stage 2 until you fix all old clients.

For instructions, see [How to identify deprecated client requests](../clients/deprecate-how-to.md#cp-identify-deprecated-clients).

### Stage 2: Upgrade to Confluent Platform 8.3

After you verify that no non-compliant clients are active, you can begin the upgrade to 8.3 in the following order:

1. Upgrade Confluent Control Center to a version that is compatible with Confluent Platform 8.3. You must upgrade Confluent Control Center before upgrading your brokers and controllers.
   Confluent Control Center 2.2 is compatible with older versions of Confluent Platform, but Control Center (Legacy) is not compatible with Confluent Platform 8.3. If you are already running
   Confluent Control Center 2.2 or later, you can skip this step. For upgrade steps, see [Control Center Upgrade Guide](/control-center/current/installation/upgrade.html).
2. Upgrade each broker and then each controller.

   #### NOTE
   For clusters running in ZooKeeper mode, see [Upgrade Confluent Platform (version 7.9)](https://docs.confluent.io/platform/current/installation/upgrade.html#steps-for-upgrading-to-version-x-zk-mode).
3. Upgrade the rest of Confluent Platform components as described in the later part of this topic.
4. If it makes sense, build applications that use Kafka producers and consumers
   against the new 8.3.x libraries and deploy the new versions. See
   [Schemas, Serializers, and Deserializers for Confluent Platform](../clients/app-development.md#app-development) for more details about using the 8.3.x libraries.

<a id="upgrade-brokers"></a>

## Upgrade Kafka

In a rolling upgrade scenario, upgrade one Kafka broker or controller at a time, taking into
consideration the recommendations for doing [rolling restarts](../kafka/post-deployment.md#rolling-restart)
to avoid downtime for end users.

In a downtime upgrade scenario, take the entire cluster down, upgrade each broker, upgrade each controller,
and then start the cluster.

### Steps to upgrade for any fix pack release

You can perform a rolling upgrade for any fix pack release, that is, from one
patch release to a later patch release within the same minor version. For
example, you can roll from Confluent Platform 8.2.0 to 8.2.1 by upgrading each controller or
broker, one at a time.

To upgrade each broker:

1. Stop the broker or controller.
2. Upgrade the software. See the packaging type sections that follow for instructions.
3. Start the broker or controller.

<a id="rolling-upgrade"></a>

<a id="upgrade-kraft-cluster"></a>

### Steps for upgrading to 8.3.x

You can upgrade KRaft clusters for any Confluent Platform version 7.7.1 and later to the latest Confluent Platform version.

You should upgrade all the brokers and then all the controllers, one at a time.
Follow these steps for a rolling upgrade:

1. Shut down the broker or controller. Starting with Kafka 3.7, you can
   stop a specific node using the [kafka-server-stop tool](/kafka/operations-tools/kafka-tools.html#kafka-server-stop-sh) by specifying a node ID.

   #### IMPORTANT
   Before you upgrade to any Confluent Platform 8.x version:
   * Remove the `message.format.version`, `message.downconversion.enable`, and
     `message.timestamp.difference.max.ms` properties from your static configuration files, such as `server.properties`.
     If you don’t remove these properties, dynamic configuration updates might not work properly.
   * If upgrading from a version earlier than Confluent Platform 8.0, verify that all `segment.bytes` or
     `log.segment.bytes` configurations are set to at least 1048576 bytes (1 MB). In Confluent Platform 8.0,
     [KIP-1030](https://cwiki.apache.org/confluence/display/KAFKA/KIP-1030%3A+Change+constraints+and+default+values+for+various+configurations)
     increased the minimum acceptable value from 14 bytes to 1 MB. Update any topic or broker configurations
     with lower values before upgrading. Otherwise, the broker fails to start. For more information, see the
     [Confluent Platform 8.0 Release Notes](https://docs.confluent.io/platform/8.0/release-notes/index.html).
2. Upgrade the software on the node per the packaging type.
   - [Upgrade Debian packages using APT](#upgrade-deb-packages)
   - [Upgrade RPM packages by using YUM](#upgrade-rpm-packages)
   - [Upgrade using TAR or ZIP archives](#upgrade-tar-zip-archives)
3. Restart the broker or controller.
4. Verify that the cluster behavior and performance meet your expectations.
5. After you upgrade each broker and controller, increment the release version for the cluster by following these steps:
   1. Verify the feature mapping. Run the `version-mapping` command to see which
      feature levels will be applied:
      ```none
      bin/kafka-features.sh version-mapping \
        --bootstrap-server <broker:port> \
        --release-version 4.3
      ```

      #### WARNING
      **Multi-region cluster users**

      If you have a multi-region cluster setup, set the
      `advertised.listeners` configuration on your KRaft controllers to
      reachable endpoints before you upgrade using `--release-version` to a
      release version >= `CP-7.9-IV0A`. For example, each node’s endpoint
      in `controller.quorum.voters` is a valid `advertised.listeners`
      value for that node.

      **Confluent for Kubernetes users**

      Setting `advertised.listeners` on KRaft controllers is not supported in CFK.
      To upgrade with CFK, follow the instructions in the [CFK upgrade guide](https://docs.confluent.io/operator/current/co-upgrade-cp.html#update-metadata-version-of-kraft-and-ak).
   2. Upgrade the release version. Run the following command to upgrade all features at once:
      ```none
      bin/kafka-features.sh --bootstrap-server <broker:port> upgrade --release-version 4.3
      ```

      #### NOTE
      Broker and log directory cordoning requires the Confluent Platform 8.3 metadata
      version or later. Until you upgrade the release version, the
      `cordoned.log.dirs` configuration has no effect. For more
      information, see [Cordon Brokers and Log Directories in Confluent Platform](../kafka/cordon-broker.md#cordon-broker).

   <!-- see this in source: https://github.com/apache/kafka/blob/trunk/server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java -->

   Each [MetadataVersion](https://github.com/apache/kafka/blob/trunk/server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java) later
   than 3.2.x provides a boolean parameter, which when true indicates there are breaking metadata changes.
   After you have changed the release version to the latest version, you can only downgrade if there are no
   metadata changes between the current and earlier version.

   The following table lists the metadata versions supported for each platform version.
   The IV suffix means “internal version” and each metadata version after 0.10.0 also provides an
   internal version. If you omit the IV, the latest IV is assumed.

   | Confluent Platform version   | Kafka metadata versions   |
   |------------------------------|---------------------------|
   | 8.3.x                        | 4.3-IV0                   |
   | 8.2.x                        | 4.2-IV0 through 4.2-IV1   |
   | 8.1.x                        | 4.1-IV0 through 4.1-IV1   |
   | 8.0.x                        | 4.0-IV0 through 4.0-IV3   |
   | 7.9.x                        | 3.9-IV0                   |
   | 7.8.x                        | 3.8-IV0                   |
   | 7.7.x                        | 3.7-IV0 through 3.7-IV4   |
   | 7.6.x                        | 3.6-IV0 through 3.6-IV2   |
   | 7.5.x                        | 3.5-IV0 through 3.5-IV2   |

<a id="upgrade-cp-license"></a>

### Confluent license

Add the `confluent.license` configuration parameter to the broker or
controller properties files. Confluent Platform requires `confluent.license` to start. For
more information, see [confluent-server](available_packages.md#confluent-server-package).

#### NOTE
The Customer-Managed Confluent Platform for Confluent Cloud license key enables you to use self-managed Confluent Platform components exclusively
with Confluent Cloud services.

Prerequisites for installing the Customer-Managed Confluent Platform for Confluent Cloud license:

1. Ensure all your self-managed Confluent Platform components are connected with Confluent Cloud and used for Confluent Cloud
   broker-related use cases. Confluent does not provide support for any self-managed
   Confluent Platform components that are used exclusively for Confluent Platform broker use cases under the Customer-Managed Confluent Platform for Confluent Cloud subscription.
2. You must upgrade Confluent Platform to the recommended minimum patch version, or later, for each version of Confluent Platform,
   as shown in the following table.

You must upgrade Confluent Platform components or Control Center before you apply a new Confluent Enterprise
license key, otherwise the license key update may fail.
The failure is recorded as an error in the component logs, and it is shown in Control Center if the license key was
applied using Control Center.

<!-- This file contains just the table for easy inclusion in other documents -->

| Confluent Platform version   | Minimum patch version   |
|------------------------------|-------------------------|
| 8.2.x                        | 8.2.0                   |
| 8.1.x                        | 8.1.0                   |
| 8.0.x                        | 8.0.2                   |
| 7.9.x                        | 7.9.4                   |
| 7.8.x                        | 7.8.5                   |
| 7.7.x                        | 7.7.6                   |
| 7.6.x                        | 7.6.8                   |
| 7.5.x                        | 7.5.11                  |
| 7.4.x                        | 7.4.12                  |
<!-- Lets comment this out as 8.1.x hasn't shipped -->
<!-- All |cp| versions from 8.1.x support the Enterprise license key for |cmcpcc| subscription. -->

The license key must be configured for each self-managed Confluent Platform component:

- If you are using Control Center, you should apply the license key in Control Center. For more information, see
  [Manage Licenses using Control Center](/control-center/current/installation/license.html).
- Alternatively, configure the license key for each Confluent Platform component.
  For more information, see [Configure component licenses](license.md#cp-configure-license).

#### NOTE
If you are an existing customer, your current license key will continue to function until its expiration date.

### Advertised listeners

When you upgrade from 5.x or earlier version to 6.x or later version, you need
to include the following properties  in the `server.properties` file:

* `advertised.listeners` is required for all deployments. See
  [Admin REST APIs Configuration Options for Confluent Server on Confluent Platform](../kafka-rest/production-deployment/confluent-server/config.md#confluent-server-rest-config) for more information.
* `confluent.metadata.server.advertised.listeners` is required for RBAC
  deployments. See [Metadata Service Configuration Settings](../kafka/configure-mds/mds-configuration.md#mds-configuration-options) for more information.

### Security

The authorizer class `kafka.security.authorizer.AclAuthorizer` replaces the legacy authorizer class
`kafka.security.auth.SimpleAclAuthorizer`. You must manually change existing
instances of `kafka.security.auth.SimpleAclAuthorizer` to
`kafka.security.authorizer.AclAuthorizer` in the `server.properties file`.
For more information, see [ACL concepts](../security/authorization/acls/overview.md#acl-concepts).

### Replication factor for Self-Balancing Clusters

If the value of `confluent.balancer.topic.replication.factor` is greater than
the total number of brokers, the brokers will not start.

The default value of `confluent.balancer.topic.replication.factor` is `3`.

For details on the setting, see [confluent.balancer.topic.replication.factor](../clusters/sbc/configuration-options.md#sbc-config-replication-factor).

<a id="upgrade-deb-packages"></a>

### Upgrade Debian packages using APT

1. Back up all configuration files from `/etc`, including, for example, `/etc/kafka`,
   `/etc/kafka-rest`, and `/etc/schema-registry`.
2. Stop the services and remove the existing packages and their dependencies.
   This can be done on one server at a time for a [rolling upgrade](#rolling-upgrade).
   ```bash
   # The example below removes the Kafka package
   sudo kafka-server-stop
   sudo apt-get remove confluent-kafka

   # To remove Confluent Platform and all its dependencies at once,
   # run the following command after all services are stopped.
   sudo apt-get autoremove confluent-platform-*

   If you're running |cs|, the previous ``autoremove`` command may not work.
   Instead, run the following command:

   .. code:: bash

      sudo yum remove confluent-*
   ```
3. Remove the repository files of the previous version.
   ```bash
   sudo add-apt-repository -r "deb https://packages.confluent.io/deb/<currently installed version> stable main"
   ```
4. Add the 8.3 repository to `/etc/apt/sources.list`.

   #### ATTENTION
   Starting with Confluent Platform 8.0, the librdkafka, Avro, and libserdes C/C++ client packages
   will only be available in the `https://packages.confluent.io/clients` location.

   For the `clients` repository, you must obtain your Debian distribution’s
   release “Code Name”, such as `buster`, `focal`, or `jammy`.
   The following example uses `$(lsb_release -cs)`, which should work in most cases. If it does not, you
   must pick the closest [Debian](https://www.debian.org/releases/) or [Ubuntu](https://releases.ubuntu.com/) code name for your Debian Linux distribution
   that matches the [supported Debian & Ubuntu Operating Systems](system-requirements.md#supported-os) supported by Confluent Platform.
   ```bash
   sudo add-apt-repository "deb https://packages.confluent.io/deb/8.3 stable main"
   sudo add-apt-repository "deb https://packages.confluent.io/clients/deb $(lsb_release -cs) main"
   ```
5. Refresh repository metadata.
   ```bash
   sudo apt-get update
   ```
6. Install the new packages. If you have modified configuration files, `apt` may prompt you to resolve conflicts.
   Be sure to keep your original configuration to preserve your settings.
   ```bash
   # Install the latest version of the full platform
   sudo apt-get install confluent-platform

   # Or, install a specific component like Kafka
   sudo apt-get install confluent-kafka
   ```

#### Install a specific version on Debian or Ubuntu

On Debian or Ubuntu, `apt` raises an **unmet dependencies** error when you try to install a specific Confluent Platform version after a newer patch release. The following steps work around the error.

This dependency issue only occurs when you try to install a version for which a newer patch release already exists. For example, you
encounter this issue when trying to install `confluent-platform=8.1.0` after version `8.1.1` has been released.

On Debian-based systems, `apt` always tries to install the latest available dependency. This can cause an **unmet dependencies** error
if you try to install a specific older Confluent package (for example, 8.0.1-1) when a newer patch version (for example, 8.1.1-1)
is also available. This occurs because Confluent packages enforce strict dependencies, requiring all components to match the exact same version.
When `apt` resolves dependencies for the older package you requested, it defaults to the newest dependency versions,
creating a version mismatch.

#### NOTE
The following installation steps are only required when pinning to a version that has been superseded by a newer patch release.
For example, you would use these steps to install `confluent-platform=8.1.0` after `8.1.1` is available. This process is not
necessary for the initial release of a new minor version (for example, 8.1.0), which can be installed directly by specifying
its version number.

You can choose one of the following methods to manage this behavior.

##### Method 1: Install the latest version (Recommended)

Install the latest version available in the repository. This allows `apt` to manage all
dependencies automatically without conflict.

```bash
# This command installs the latest version of the platform and its dependencies
sudo apt-get install confluent-platform
```

##### Method 2: Force a specific older version with pinning

If you install a specific older version, for example, 8.1.0, use `apt` pinning to force `apt` to select the correct dependency versions.

To avoid conflicts, first ensure no other Confluent packages are installed.

1. List all installed Confluent packages to review what to be removed.
   ```bash
   dpkg -l | grep confluent
   ```
2. Uninstall all listed packages.
3. Create an `apt` preference file to force all packages starting with `confluent-` to the desired version. A pin priority of
   `1001` ensures this version will be used, even if it requires a downgrade.
   1. Create and open the file:
      ```bash
      sudo vi /etc/apt/preferences.d/confluent.pref
      ```
   2. Add the following content, replacing 8.1.0 with your target version.
      ```bash
      Package: confluent-*
      Pin: version 8.1.0-*
      Pin-Priority: 1001
      ```
4. Update your package list and install the pinned version. The pinning rule ensures the correct dependencies are downloaded.
   ```bash
   sudo apt-get update

   # Install a specific version of the full platform
   sudo apt-get install confluent-platform=8.1.0-1

   # Or, install a specific version of a single component
   sudo apt-get install confluent-server=8.1.0-1
   ```
5. Start your Confluent Platform components.
   ```bash
   # Command to start a broker
   kafka-server-start -daemon /etc/kafka/broker.properties

   # Command to start a controller
   kafka-server-start -daemon /etc/kafka/controller.properties
   ```

<a id="upgrade-rpm-packages"></a>

### Upgrade RPM packages by using YUM

1. Back up all configuration files from `/etc`, including, for example,
   `/etc/kafka`, `/etc/kafka-rest`, and `/etc/schema-registry`.
   You should also back up all customizations to your configuration and unit files.
2. Stop the services and remove the existing packages and their dependencies.
   This can be done on one server at a time for a rolling upgrade (see
   [Steps for upgrading to 8.3.x](#rolling-upgrade)).

   To stop and remove the Kafka package:
   ```bash
   sudo kafka-server-stop
   sudo yum remove confluent-kafka
   ```

   To remove Confluent Platform and its dependencies at once, run the following after stopping all services.
   ```bash
   sudo yum autoremove confluent-platform-7.8.0
   ```

   If you’re running Confluent Server, the previous `autoremove` command won’t work.
   Instead, run the following command:
   ```bash
   sudo yum remove confluent-*
   ```

   To upgrade from previous minor versions, run the following command
   instead:
   ```bash
   sudo yum autoremove confluent-platform
   ```
3. Remove the repository files of the previous version.
   ```bash
   sudo rm /etc/yum.repos.d/confluent.repo
   ```
4. Add the repository to your `/etc/yum.repos.d/` directory in a file named `confluent-8.3.repo`.

   #### IMPORTANT
   Starting with Confluent Platform 8.0, the librdkafka, Avro, and libserdes C/C++ client packages
   will only be available from the
   `https://packages.confluent.io/clients` location.

   **RHEL 9 and later:** Avro and libserdes RPM packages are not available for RHEL 9 and later versions.
   The libserdes library has been discontinued and replaced by
   [libschemaregistry](https://github.com/confluentinc/libschemaregistry).

   For customers who previously used Avro or libserdes RPM packages:
   * Confluent no longer provides pre-packaged RPM deliverables for these libraries
   * Instead, integrate these libraries directly into your projects using CMake
   * See the [libschemaregistry repository](https://github.com/confluentinc/libschemaregistry)
     for CMake integration instructions
   * The libschemaregistry library replaces libserdes functionality

   The `$releasever` and `$basearch` are [Yum placeholder variables](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/deployment_guide/sec-using_yum_variables)
   that change depending on what release version of the OS and CPU Architecture the
   OS is running. These are meant to be literal `$releasever` `$basearch`
   values in the Yum configuration, not shell variables.
   ```ini
   [confluent-8.3]
   name=Confluent repository for 8.3.x packages
   baseurl=https://packages.confluent.io/rpm/8.3
   gpgcheck=1
   gpgkey=https://packages.confluent.io/rpm/8.3/archive.key
   enabled=1

   [Confluent-Clients]
   name=Confluent Clients repository
   baseurl=https://packages.confluent.io/clients/rpm/centos/$releasever/$basearch
   gpgcheck=1
   gpgkey=https://packages.confluent.io/clients/rpm/archive.key
   enabled=1
   ```
5. Refresh repository metadata.
   ```bash
   sudo yum clean all
   ```
6. Install the new version. `yum` can override your existing configuration
   files. Restore them from the backup after installing the packages.

   You can install the entire platform or individual packages. For a list of packages,
   see [Confluent Platform Packages](available_packages.md#available-packages).

   To install Confluent Platform, run:
   ```bash
   sudo yum install confluent-platform
   ```

   Or install the packages you need one by one. `confluent-server` and `confluent-kafka`
   cannot coexist, so install each desired package individually.

   For example, to install Confluent Server, run:
   ```bash
   yum install confluent-server
   ```

   To install Kafka, run:
   ```bash
   sudo yum install confluent-kafka
   ```
7. Start services.
   ```bash
   kafka-server-start -daemon /etc/kafka/server.properties
   ```

<a id="upgrade-tar-zip-archives"></a>

### Upgrade using TAR or ZIP archives

For ZIP and TAR archives, you can delete the old archives directory after the
new archive folder has been created and any previous configuration files have
been copied into it as described in the following steps.

1. Return to the directory where you installed Confluent Platform.
2. Back up all configuration files from `./etc`, including, for example,
   `./etc/kafka`, `./etc/kafka-rest`, `./etc/schema-registry`, and
   `./etc/confluent-control-center`.
3. Stop the services and remove the existing packages and their dependencies.
   This can be done on one server at a time for a rolling upgrade (see
   [Steps for upgrading to 8.3.x](#rolling-upgrade)).
   ```bash
   ./bin/kafka-rest-stop
   ./bin/schema-registry-stop
   ./bin/kafka-server-stop
   ```
4. To remove Confluent Platform and all its dependencies at once, run the following after stopping all services.
   Replace `confluent-7.6.0` with your installed version number.
   ```bash
   cd ..
   rm -R confluent-7.6.0
   ```
5. Unpack the new archive. `yum` can override your existing configuration
   files. Restore them from the backup after installing the packages.
   ```bash
     tar xzf confluent-8.3.1.tar.gz

   # Or for ZIP archives:

     unzip confluent-8.3.1.zip
   ```
6. Start services.
   ```bash
   sudo confluent-8.3.1/bin/kafka-server-start -daemon /etc/kafka/server.properties
   ```

## Upgrade Confluent Control Center

To upgrade Confluent Control Center, follow the instructions in the [Confluent Control Center Upgrade Guide](/control-center/current/installation/upgrade.html).
Upgrade Confluent Control Center first before upgrading the brokers and controllers.

<a id="upgrade-sr"></a>

## Upgrade Schema Registry

You can upgrade Schema Registry after *all* Kafka brokers have been upgraded.

#### IMPORTANT
Schema Registry 8.x adds fields to its JSON responses (such as `guid`, `subject`,
`ts`, and `deleted`) that older Schema Registry client libraries do not
recognize. Applications that depend on `kafka-schema-registry-client`
libraries older than 6.2 fail with
`com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException` on
calls to endpoints such as `GET /schemas/ids/{id}`.

Upgrade `kafka-schema-registry-client` to 6.2 or later in all producer
and consumer applications before upgrading Schema Registry to 8.x. Otherwise, keep
Schema Registry on the 7.x branch. Other Confluent Platform components can upgrade to 8.x
independently.

Older Avro serializer and deserializer client libraries can also leak
memory against Schema Registry 8.x. These clients cache Avro `Schema` objects by
object identity, but Schema Registry 8.x returns a freshly parsed `Schema`
instance on every register and lookup call. Because the cached entries
never match by identity, the cache fills with duplicate entries, and
each entry pins a full schema tree in memory. This is fixed in the Avro
client libraries bundled with any of the following Confluent Platform releases:

- 7.5.16 or later
- 7.6.14 or later
- 7.7.12 or later
- 7.8.11 or later
- 7.9.10 or later
- 8.0.8 or later

Upgrade producer and consumer applications to one of these versions
before connecting to Schema Registry 8.x. If you cannot upgrade yet, set
`auto.register.schemas` to `false` to avoid triggering the leak.

To upgrade Schema Registry:

1. **For RBAC-enabled environments only:** Add `ResourceOwner` for the REST Proxy user for the Confluent license
   topic resource (default name is `_confluent-command`). For example:
   ```none
   confluent iam rbac role-binding create \
   --role ResourceOwner \
   --principal User:<service-account-id> \
   --resource Topic:_confluent-command \
   --kafka-cluster <kafka-cluster-id>
   ```
2. Stop Schema Registry:
   ```bash
   schema-registry-stop
   ```
3. Back up the configuration file. For example:
   ```bash
   cp SR.properties /back-up/SR.properties
   ```
4. Remove the old version:
   ```bash
   yum remove confluent-schema-registry-<old release number>
   ```

   For example:
   ```bash
   yum remove confluent-schema-registry-7.6.0
   ```
5. Install the new version:
   ```bash
   yum install -y confluent-schema-registry-<new release number>
   ```
6. Restart Schema Registry:
   ```bash
   schema-registry-start SR.properties
   ```

<a id="upgrade-rest-proxy"></a>

## Upgrade Confluent REST Proxy

You can upgrade the Confluent REST Proxy service after *all* Kafka brokers have been upgraded.

To upgrade the REST Proxy:

1. **For RBAC-enabled environments only:** Add `ResourceOwner` for the REST Proxy user for the Confluent license
   topic resource (default name is `_confluent-command`). For example:
   ```none
   confluent iam rbac role-binding create \
   --role ResourceOwner \
   --principal User:<service-account-id> \
   --resource Topic:_confluent-command \
   --kafka-cluster <kafka-cluster>
   ```
2. Follow the steps in [Upgrade Debian packages using APT](#upgrade-deb-packages) or [Upgrade RPM packages by using YUM](#upgrade-rpm-packages) to upgrade the package (back up configuration files,
   remove packages, and install upgraded packages).
3. Restart the Confluent REST Proxy service.

<a id="upgrade-kafka-streams"></a>

## Upgrade Kafka Streams applications

You can upgrade Kafka Streams applications independently, without requiring
Kafka brokers to be upgraded first.

Follow the instructions in the [Kafka Streams Upgrade Guide](../streams/upgrade-guide.md#streams-upgrade-guide)
to upgrade your applications to use the latest version of Kafka Streams.

<a id="upgrade-connect"></a>

## Upgrade Kafka Connect

You can upgrade Kafka Connect in either standalone or distributed mode.

#### NOTE
Enterprise support is not provided for the Confluent Community licensed distributions of Kafka Connect workers
(CCS or `cp-kafka-connect`). Confluent recommends using the Confluent Enterprise distribution
of Kafka Connect workers (CE or `cp-server-connect`). Note that Confluent Enterprise distribution of
Kafka Connect workers fails without a valid enterprise license key.

#### NOTE
If you are using Control Center, apply the license key in Control Center (recommended). For more information, see
[Manage Confluent Platform licenses using Control Center](https://docs.confluent.io/control-center/current/installation/license.html#manage-cp-licenses-using-c3-short).

Alternatively, you can configure the `confluent.license` parameter in the Connect worker configuration,
or at the individual connector level for enterprise support of connectors and Connect workers.
For more information, see [Centralized License in the Kafka Connect Worker](../connect/license.md#central-connect-license).
Confluent recommends validating in lower environments before production upgrades.

#### NOTE
The [Confluent Replicator](../multi-dc-deployments/replicator/index.md#replicator-detail) version must match the Connect version it runs on.
For example, deploy Replicator 8.3 only to Connect 8.3,
so if you upgrade Connect, you must upgrade Replicator.

#### NOTE
When you upgrade Confluent Platform, also upgrade your connector versions to ensure compatibility and continued support, as they are tightly coupled with the Confluent Platform version you are using. For more information, see [Supported Versions and Compatibility for Self-Managed Connectors](https://docs.confluent.io/platform/current/connect/supported.html#for-connector-versions).

### Upgrade Kafka Connect standalone mode

You can upgrade Kafka Connect in standalone mode after *all* Kafka brokers have
been upgraded.

To upgrade Kafka Connect, follow the steps in [Upgrade Debian packages using APT](#upgrade-deb-packages) or [Upgrade RPM packages by using YUM](#upgrade-rpm-packages)
(back up configuration files, remove packages, and install upgraded packages). Then,
restart the client processes.

<a id="upgrade-connect-distributed"></a>

### Upgrade Kafka Connect distributed mode

1. Back up 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
   [Distributed Mode Configuration](/kafka-connectors/self-managed/userguide.html#distributed-mode)
   in the [Connect User Guide](/kafka-connectors/self-managed/userguide.html) for a detailed explanation.
3. Perform a rolling restart of the workers.

<a id="upgrade-ksqldb"></a>

## Upgrade ksqlDB

To upgrade ksqlDB to the latest version, follow the steps in
[Upgrading ksqlDB](../ksqldb/operate-and-deploy/installation/upgrading.md#ksqldb-installation-upgrade).

<a id="upgrade-other-client-apps"></a>

## Upgrade other client applications

Review [Cross-component compatibility](versions-interoperability.md#cross-component-compatibility) before you upgrade your client applications.

Confluent clients (C/C++, Python, Go, and .NET) support all released Kafka broker versions, but not
all features are available on all broker versions because some features rely on newer broker functionality.
See [Build Streaming Applications on Confluent Platform](../clients/overview.md#kafka-clients) for the list of Kafka features supported in the latest versions of clients.

If it makes sense, build applications that use Kafka producers and consumers against
the new 4.3.x libraries and deploy the new versions. See [Schemas, Serializers, and Deserializers for Confluent Platform](../clients/app-development.md#app-development)
for details about using the 4.3.x libraries.

## Related content

- [Overview of Confluent Platform Upgrade](upgrade-checklist.md#cp-upgrade-checklist)
- [Supported Versions and Interoperability for Confluent Platform](versions-interoperability.md#interoperability-versions)
- [Migrate from ZooKeeper to KRaft on Confluent Platform](migrate-zk-kraft.md#migrate-zk-kraft)