.. _controlcenter_upgrade: Upgrade |c3-short| for |cp| =========================== .. important:: * By default, the upgrade process will preserve the last 15 minutes of historical data. There are two properties that allow you to control how much history will be preserved: ``confluent.metrics.topic.skip.backlog.minutes`` for broker metrics and ``confluent.monitoring.interceptor.topic.skip.backlog.minutes`` for stream monitoring. Preserving history for longer will slow down restore time of |c3-short| after the upgrade, while preserving less history will speed the process up. * Every version of |c3-short| (even minor upgrades) will re-create a new set of topics, since topic names contain the full version number. It is a good idea to remove the old ones to avoid confusion. For more information, see :ref:`bulk-delete-topics-c3`. * For |cp| version compatibility, see the :ref:`compatibility matrix `. Upgrading to 6.2.2 or later --------------------------- If you are upgrading your deployments to |c3| 6.2.2 or newer from an earlier version of |cp|, you must also upgrade |sr| to the same version (6.2.2 or newer). Starting with |cp| 6.2.2, |sr| provides a new endpoint for |c3| to filter visible |sr| clusters to support |c3-short| interaction with an RBAC enabled |sr|, and |c3-short| is upgraded to call this endpoint. |c3-short| versions 6.2.2 and newer are not compatible with pre-6.2.2 versions of |sr|. Therefore, if you upgrade |c3-short| from pre-6.2.2, you must also upgrade |sr|. (You can run an older version of |c3-short| with a newer |sr|, but you will not get the benefit of the improved interaction of |c3-short| with RBAC enabled registries.) More details are provided under :ref:`upgrade-sr`. Upgrading from 6.0.1 or 6.0.2 to 6.1.0 or later ----------------------------------------------- In most cases, we recommend you upgrade |c3| last among the |cp| components. However, if you are upgrading from 6.0.1 or 6.0.2 to 6.1.0 or later, you should upgrade |c3| first, and then upgrade your |ak| brokers to avoid |c3| instability. If you have already upgraded your |ak| brokers and |c3| crashes, upgrade |c3| and the situation should resolve itself. Upgrading to version 6.0.1 -------------------------- Version 6.0.1 of |cp| includes the option to enable the :ref:`cluster-registry` for |c3-short|, which creates a more user-friendly RBAC role binding experience and enables centralized audit logging. .. note:: For details on all new feature flags for |cr| in |c3-short|, see the section on :ref:`cluster_registry_settings`. Upgrading from 6.0.0 to 6.0.1 ----------------------------- #. Export your cluster information from the command store and then import it into |cr| using the :ref:`migration scripts described below `. #. Configure |c3-short| to :ref:`talk to MDS and RBAC `. #. Add the following property to the ``control-center.properties`` file: ``confluent.metadata.cluster.registry.enable=true`` Upgrading from 5.5.x to 6.0.1 ----------------------------- To upgrade existing |c3-short| components from versions 5.5.x and prior to 6.0.x, you need to transition your existing cluster data from command store to |cr|. You can do this easily using import and export scripts. If your cluster is not enabled for RBAC, the following steps are optional: #. Export your cluster information from the command store and then import it into |cr| using the :ref:`migration scripts described below `. #. Configure |c3-short| to :ref:`talk to MDS and RBAC `. #. Add the following property to the ``control-center.properties`` file: ``confluent.metadata.cluster.registry.enable=true`` .. _cluster-registry-migration-scripts: Migrating cluster data with import and export scripts ----------------------------------------------------- .. important:: Only **MDS broker super.user** or **MDS broker SystemAdmin** roles can successfully execute the migration scripts. **Export Script** To export cluster information from the command store into a ``.json`` file: #. Confirm that your |ak| broker is up and running. #. Run the export command script: .. codewithvars:: bash ./control-center-export --cluster controlCenterPropertiesFilePath --outfile outputfilePath controlCenterPropertiesFilePath The path to the |c3-short| properties file. outputfilePath The path for the ``.json`` file where you want save your output. **Import Script** To read the cluster information from the provided ``.json`` file and register the clusters with |cr|: #. Confirm that :ref:`MDS is up and running `. #. Run the import command script. You can specify the MDS credentials and URL in a properties file, or specify the MDS URL as a command line argument, and be prompted for the username and password: .. codewithvars:: bash cluster-information-migration-script [-i import] [-u url] [-p mds-properties-file] -f clusters-file mds-properties-file A properties file that contains the MDS URL, username, and password. This file should have contents similar to the following: .. code:: bash username= password= url= url URL for the MDS server. If URL is passed, you will be prompted for the username and password. clusters-file The ``.json`` file for importing and exporting cluster information. Upgrading from version 3.1.x and later -------------------------------------- #. Upgrade |ak-tm| brokers to your target |cp| release. Follow instructions in :ref:`Confluent Platform Upgrade Guide `. #. Upgrade the monitoring interceptors in all |ak| clients to your target |cp| version (this is optional if you are using |cp| interceptors 3.1 version and later). #. Stop the |c3-short| process. #. Make a backup of your current version configuration file. For example, copy and rename as ``control-center-3.1.properties``. .. codewithvars:: bash sudo cp /etc/confluent-control-center/control-center.properties /etc/confluent-control-center/control-center-3.1.properties #. Upgrade |c3-short| packages to your target version. #. Edit the |c3-short| properties file. :ref:`Configuration property names ` may have changed between versions. * If you are running against a secured cluster you need to update your :ref:`security configs`. Properties named ``confluent.controlcenter.streams.{producer,consumer}.{sasl,ssl}.*`` are now ``confluent.controlcenter.streams.{sasl,ssl}.*`` * You can control the amount of historical stream monitoring data |c3-short| will process after the upgrade (which can take some time), by setting ``confluent.metrics.topic.skip.backlog.minutes`` for broker metrics and ``confluent.monitoring.interceptor.topic.skip.backlog.minutes`` for stream monitoring. They default to 15 minutes. Setting them to shorter period will allow |c3-short| to catch up and show current data faster, at the expense of not processing old data. #. Start |c3-short|. For more information about starting |cp|, see :ref:`installation`. .. codewithvars:: bash control-center-start ${CONFLUENT_HOME}/etc/confluent-control-center/control-center.properties #. If you have authentication and authorization configured, you must run ``control-center-set-acls`` to give |c3-short| permission to create topics. For more information, see :ref:`c3-auth-acls`. Upgrading from version 3.0.x ---------------------------- #. Upgrade |ak| brokers to |cp| 3.1 #. Upgrade the monitoring interceptors in all |ak| clients to |cp| 3.1 #. Stop the |c3-short| process #. Copy the 3.0.x configuration file .. codewithvars:: bash sudo cp /etc/confluent-control-center/control-center.properties /etc/confluent-control-center/control-center-3.0.properties #. Upgrade |c3-short| packages to |cp| 3.1 #. Reset the application (deleting internal state) .. codewithvars:: bash # Use the same properties file you used to launch Control Center # From 3.0.1 /usr/bin/control-center-3_0_1-reset /etc/confluent-control-center/control-center-3.0.properties # From 3.0.0 /usr/bin/control-center-3_0_0-reset /etc/confluent-control-center/control-center-3.0.properties #. Edit the |c3-short| properties file. Some :ref:`configuration property names ` have changed * If you had set the ``confluent.controlcenter.name`` parameter, we suggest changing the value to reflect the new version (e.g. _confluent-controlcenter-3-1-0). This isn't strictly necessary but a good precaution in case any step of the reset failed. * You can control the amount of historical stream monitoring data |c3-short| will process after the upgrade (which can take some time), by setting ``confluent.metrics.topic.skip.backlog.minutes`` for broker metrics and ``confluent.monitoring.interceptor.topic.skip.backlog.minutes`` for stream monitoring. They default to 15 minutes. Setting them to shorter period will allow |c3-short| to catch up and show current data faster, at the expense of not processing old data. #. Start |c3-short| .. codewithvars:: bash /usr/bin/control-center-start /etc/confluent-control-center/control-center.properties