You may upgrade to Lenses 3.1 from 3.0 without any change  in your configuration. However there are some changes to the configuration format and new features that you may want to take advantage of. 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.
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.
Please note that in case you need to downgrade from 3.1 to 3.0, your Alert settings and custom rules will be lost. Make sure to keep a copy of your Lenses Storage Directory, in case you want to downgrade.
|||If you have custom descriptions for new connectors, then you have to change the default extractor class name. Check Configuration Changes for more information.|
From 3.0 to 3.1¶
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
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.
As usual the latest tag brings the latest Lenses versions. There are also tagged releases major (3.1, 3.0) and even minor (3.1.0, 3.0.8) tags to help you better manage your upgrade path.
Starting with 3.0, the
landoop/kafka-lenses-dev image can also be accessed
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.
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.
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.
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.
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.
You can now 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.
Extractor classes for connector definitions changed from
io.lenses.config. When you add custom connector definitions, you have to define an extractor class for Lenses to be able to detect the topics the connector uses. Update your configuration to use the new class names. Some examples are the class
io.lenses.core.kafka.connect.SimpleTopicsExtractorto be renamed to
io.lenses.config.kafka.connect.SimpleTopicsExtractorand the class
io.lenses.core.kafka.connect.JdbcSourceTopicsExtractorto be renamed to
From 2.3 to 3.1¶
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.
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