Upgrade notes

Lenses 5.1 is an incremental release which brings in new features and improvements.

• There are no breaking changes when upgrading from 5.0.
• You should still take care and follow upgrade best practices.
• JRE & Lenses tarball installation: From 5.1 onwards, the Lenses tarball doesn’t come with a built-in JRE anymore. This allows you to provide a JRE of your own choosing, based on your requirements (e.g OpenJDK, Oracle, Azul).

If you are upgrading from older versions of Lenses, follow the upgrade procedure for Lenses 5.0.

Breaking Changes and Caution Items 

The first time Lenses 5.1 is run, it will upgrade the database. The process is not reversible. It is recommended to backup the database (internal database stored at lenses.storage.directory or remote PostgreSQL database) before upgrading, so it is possible to downgrade if needed. The database holds the user and service accounts, groups information, audits, alerts, and more.

• If you upgrade from Lenses 4.3 or older, follow the upgrade procedure for Lenses 5.0 first.
• If you are using the Lenses tarball, then you must have a JRE installed on the server running Lenses. The minimum supported version is Java 8, but we recommend to use Java 11 if possible.

Update Process 

Using the Lenses Archive 

Download the latest 5.1 archive and extract it in a new directory on your server. It is important to avoid extracting an archive over an older installation to avoid having multiple versions of libraries. Instead, you should 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. If you are using the internal database instead of PostgreSQL, make sure Lenses Storage Directory (lenses.storage.directory) is kept intact. The folder is where persistent data is stored, such as users, groups, audits, data policies, connections, and more.

Make sure you have a JRE (or JDK) installed in the server running Lenses. Lenses can run on JRE 8 or greater, and the recommended version is JRE 11.

Using the Lenses Docker 

The docker image uses tags to distinguish between versions. The latest tag (lensesio/lenses:latest) brings the latest stable version of Lenses. There are minor tags to help users get the latest patch in a minor version (e.g 5.1, 5.0) and patch tags to help users pin to a specific patch (e.g 5.1.0, 5.0.7). The best practice advice is to use the minor tag (lensesio/lenses:5.1), which ensures that your installation will always get compatible updates until you made a conscious decision to upgrade the minor version.

If you use the internal database instead of PostgreSQL as the backing store of Lenses, make sure you keep the /data/storage volume to not lose your data. Other volumes supported by the docker are /data/kafka-streams-state which holds state for SQL Processors running IN-PROC and may have to be rebuilt (automatically) if lost, /data/log (log files on disk), /data/plugins (custom UDFs).

Pull the 5.1 docker:

docker pull lensesio/lenses:5.1

Stop your current container and restart with the 5.1 image, mounting any volumes you might need.

Lenses Box 

If you are a Box user, pull the latest version, preserve your /data volume and restart Lenses:

docker pull lensesio/box:5.1
docker stop [CURRENT BOX NAME or ID]
docker run -v /path/to/box/data:/data -e EULA="..." -p 3030 lensesio/box:5.1

Helm 

Download the latest charts and update your values.yaml as described below. Remember that if you are using the internal database instead of PostgreSQL as the backing store, then the Lenses Storage Directory should be stored in a persistent volume and be kept intact between updates. To support a potential downgrade, make sure this volume is backed-up before installing a newer version of Lenses.

helm repo add lensesio https://helm.repo.lenses.io/
helm repo update

In values.yaml disable the provisioning section (if enabled) as Lenses already has all the information stored in the database, and provision cannot function.

lenses:
  provision:
    enabled: false

If you don’t have your values.yaml you can download it from the Kubernetes cluster using Helm:

helm get values --namespace [LENSES_NAMESPACE] \
     --output yaml [LENSES_DEPLOYMENT] > values.yaml

Proceed to upgrade:

helm upgrade --namespace [LENSES_NAMESPACE] --values values.yaml [LENSES_DEPLOYMENT]

Alternatively, reusing the old values and turning provisioning off:

helm upgrade --namespace [LENSES_NAMESPACE] --reuse-values \
     --set lenses.provision.enabled=false [LENSES_DEPLOYMENT]

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. If a new image does not exist, you may be able to update Lenses in-place. Our support team will be happy to go through the available options with you.

Configuration Changes 

Lenses 5.1 configuration is compatible with version 5.0.

The following, optional, configuration keys have been added:

See more in the Advanced configuration section.