Upgrade Notes

You may upgrade to Lenses 3.2 from 3.1 without any change in your configuration. Upgrading from 3.0 also does not require any change, though there are some recommended adjustments you can apply to your configuration. Upgrading from 2.3 or an older version of Lenses, requires some changes to the existing configuration files. Please familiarize with the changes described below before performing an upgrade.

For the full list of changes made for this release please check the Release Notes.

Note

Please remember that Lenses 2.2 introduced state on disk. You have to keep your Lenses Storage Directory in order for your Data Policies to transfer to 3.0. Furthermore, in 3.0 user management, audits, and alerts have been migrated to the Lenses Storage Directory, so you must make sure you persist these data in order to be able to retain them between upgrades in the future.

From 3.x to 3.2

Application Update

Archive

Download the latest archive and extract it in a new directory. It is important to avoid extracting an archive over an older installation. You should instead remove (or rename) the old directory, then move the new into its place. Copy if needed and update your lenses.conf and security.conf files as described later in the current page (Configuration Changes). Last make sure you keep the Lenses Storage Directory intact as this is where persistent data is stored. Up to Lenses 2.3 Data Policies are stored there. Starting with 3.0, users, groups, audits and other data is stored as well.

Docker

As usual the latest tag brings the latest Lenses versions. There are also tags for major releases (3.2, 3.1) and minor (3.2.0, 3.1.2) tags to help you better manage your upgrade path.

Starting with 3.0, the landoop/kafka-lenses-dev image can also be accessed via lensesio/box. The landoop/lenses image can also be accessed via the lensesio/lenses name. In the future the old names will be deprecated, thus it’s advised to make the switch to the new images earlier rather than later.

Docker pull the latest Lenses environment for Developers:

docker pull lensesio/box:latest

Or update you docker container for Lenses Enterprise with:

docker pull lensesio/lenses:latest

Follow the Configuration Changes section to update your settings if needed. Remember that Lenses Storage Directory should be stored in a docker volume and be kept intact between updates.

Helm

Download the latest charts and update your values.yaml as described in Configuration Changes and upgradenotes_helm sections. Remember that Lenses Storage Directory should be stored in a persistent volume and be kept intact between updates.

Cloud Installations

Use the latest version available in the marketplaces. Remember that Lenses Storage Directory should be provided as a persistent volume and be kept intact between updates.

SQL Processors

For kubernetes no action is required. New processors will use automatically the latest image. Old processors will keep working with the old image.

For Kafka Connect, please download the latest version of the connector and add it to your connect nodes whilst removing the old version. Your nodes need to be restarted for the change to take effect. A rolling restart is advised.

Configuration Changes

  • In Lenses 3.1 the settings for the producer and consumer Kafka client, are consolidated under the settings keyword. So the configuration below:

    lenses.kafka.client.producer.acks=1
lenses.kafka.client.consumer.check.crcs=true
lenses.kafka.client.producer.security.protocol=PLAINTEXT
lenses.kafka.client.consumer.security.protocol=PLAINTEXT

    Should be converted to:

    lenses.kafka.settings.client.acks=1
lenses.kafka.settings.client.check.crcs=true
lenses.kafka.settings.client.security.protocol=PLAINTEXT

    Old style settings are still supported, but you cannot mix old and new styles. In such case, Lenses will print an informative message and exit.

  • Starting with Lenses 3.1 you can create Alerts Connections (AlertManager, Slack, PagerDuty, DataDog, AWS CloudWatch, and webhooks) via the Web Interface, the Lenses CLI and the REST Api. In addition you can route specific alerts to specific channels via these connections.

    Old Alert connections that were added via the configuration file (lenses.conf) are still supported for AlertManager and Slack, but may be deprecated in the future. Also for these old connections, you cannot route specific alerts, rather you will always get all alerts. **It is recommended* you migrate your old Alert Connections to the new system via the ADMIN section of Lenses.

From 2.3 to 3.2

For this upgrade please perform the changes in configuration as described in 2.3 to 3.0, then follow the instructions in this page.

The most important part of the upgrade from 2.3, is that the User and Group management logic became dynamic and moved into the Lenses API. You can manage users and groups via the Lenses web interface or the lenses-cli application. What this means for operators, is that the security.conf file is no longer used to setup user acounts for the BASIC authentication module, neither groups or user-group mappings.

  • If you are using the BASIC authentication module you must recreate your users via the web interface or the command line.

  • You must recreate your groups via the Web Interface or the command line. This is also a great chance to familiarize with the new, fine grained, permission system.

  • If you are using the Kerberos (SPNEGO) authentication module you must add your principals and link them to groups via the Web Interface or the command line.

  • If you are using service accounts you must recreate them via the web interface or the command line.

    Check User Management and Security Configuration to familiarize with the changes.

Note

Since 3.0, Lenses comes with a default administrator user. Remember to secure your setup with a custom username and password for this user. Use SHA256 to protect the password inside security.conf.