.. _ansible-upgrade:

---------
Upgrading
---------

|ansible| includes playbooks to upgrade all |cp| components. The playbooks go
host by host, shutting down the component, upgrading packages, and validating
application health before moving onto the next one. 

You must complete the upgrades in the following order:

1. Upgrade Zookeeper.
2. Upgrade |ak| brokers.
3. Upgrade (in any order):

   * |sr|
   * |crest|
   * |kconnect|
   
4. Upgrade |c3|.
5. Upgrade external clients.
6. Upgrade |ak| log format. This step ensures that the log is formatted properly for the new version of |cp| after all upgrades have been completed.

Requirements
^^^^^^^^^^^^

The upgrade playbooks have the following requirements:

* Component must have been originally installed and configured using |ansible|.
* You must have the same ``hosts.yml`` file used during the installation.
* Upgrade playbooks are supported in |cp| version 5.3.0 and later.
* The |ak| broker upgrade playbook requires the **jolokia** agent be running on all |ak| brokers. Jolokia is required for the upgrade to work.


Step 1. Check out the upgrade branch
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check out the branch of cp-ansible you want to upgrade to. Branches will be in
the format ``<version>-post``. For example ``5.4.0-post``.

::
   
   cd /path/to/cp-ansible
   git fetch
   git checkout 5.4.0-post
   
Step 2. Upgrade |zk|
^^^^^^^^^^^^^^^^^^^^

The |zk| upgrade is designed to run on |ak| clusters with three nodes or more.
As it upgrades the hosts it checks for quorum and health on each host before
moving on to the next. Enter the command below to upgrade |zk|:

::
   
   ansible-playbook -i /path/to/hosts.yml upgrade_zookeeper.yml


Step 3. Upgrade |ak|
^^^^^^^^^^^^^^^^^^^^

The |ak| broker upgrade playbook upgrades each broker in sequence. The upgrade
takes special care around the ``inter.broker.protocol.version`` and
``log.message.format.version properties``. First, enter the following command
and note the current version of ``confluent-kafka-2.12`` or ``confluent-server``
installed on your hosts: 

::
   
   # rpm -qa | grep confluent
   confluent-server-5.3.0-1.noarch

Next, run the **upgrade_kafka_broker** playbook and pass in the version installed:

::
   
   ansible-playbook -i /path/to/hosts.yml upgrade_kafka_broker.yml -e kafka_broker_upgrade_start_version=5.3.0

This playbook upgrades the |ak| brokers in sequence.

.. important::
   
   The ``log.message.format.version`` property is not updated when the |ak| upgrade completes. This property is changed at the end of this procedure, after all clients have been upgraded.

Step 4. Upgrade other components
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
   
   If you need to upgrade specific hosts instead of all of them, you can `limit the upgrade <https://ansible-tips-and-tricks.readthedocs.io/en/latest/ansible/commands/#limit-to-one-or-more-hosts>`__. This can be useful when your components are behind a load balancer. In this case, remove a specific host from the load balancer pool, upgrade it, then add it back. This ensures no traffic is disrupted. Enter the following command to limit the upgrade to one or more specific hosts.
   
   ::
      
      ansible-playbook -i /path/to/hosts.yml upgrade_<component>.yml --limit "<host1>,<host2>"

Use the commands below to update the other components:

* |sr|

  ::
     
     ansible-playbook -i /path/to/hosts.yml upgrade_schema_registry.yml
      
* |kconnect|

  ::
     
     ansible-playbook -i /path/to/hosts.yml upgrade_kafka_connect.yml
     
* KSQL

  ::
     
     ansible-playbook -i /path/to/hosts.yml upgrade_ksql.yml
     
* |crest|

  ::
     
     ansible-playbook -i /path/to/hosts.yml upgrade_kafka_rest.yml
     
* |c3|

  ::
     
     ansible-playbook -i /path/to/hosts.yml upgrade_control_center.yml

  

Step 5. Upgrade clients
^^^^^^^^^^^^^^^^^^^^^^^

|cp| Ansible playbooks do not currently support upgrading clients. Review :ref:`upgrade-preparation` for additional information.


Step 6. Update the |ak| log format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After all of the applicable clients have been updated, run the following command to update update the log format:

::
   
   ansible-playbook -i /path/to/hosts.yml upgrade_kafka_broker_log_format.yml -e kafka_broker_upgrade_end_version=5.4