Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Migration from HealthBot Release 2.X to 3.X

 

Overview

You can only upgrade (migrate) to version 3.X from version 2.X. Upgrade from previous versions is not supported.

HealthBot 2.X was based entirely on docker and docker-compose for the management of the back end microservices for both single-node and multi-node installations. Starting with HealthBot release 3.0.0, Kubernetes is used to manage the docker components in multi-node installations. This change introduces some incompatibilities between the existing 2.X data and the new 3.X formats, specifically:

  • The underscore, “_”, character is no longer supported for Device Group or Network Group names.

  • Device Group and Network Group names are no longer case-sensitive. So, in 3.X, the names DeviceGroup and deviceGroup are considered the same.

  • Differences in the time-series databases (TSDB) between the versions can cause problems.

We have implemented procedures for detecting these incompatibilities and transforming the data during specific data migration processes.

The following three use cases describe procedures for migrating the 2.X data into a 3.X installation.

Warning

The procedures and functions outlined below are provided only on a best-effort basis. There is no guarantee that the data will migrate without some errors. In the event that the migration function encounters incompatibilities that it cannot resolve, an alert message regarding the need for manual intervention is displayed.

Ensure that you are familiar with HealthBot Installation Requirements and Using the Interactive Installers. These topics provide greater detail about some of the steps outlined in the procedures below.

Case 1: HealthBot 2.X Single-node (Docker-compose) to HealthBot 3.X Single-node (Docker-compose) Migration

Note

Single-node HealthBot installations are not recommended for production systems. If you perform this type of upgrade, you cannot upgrade later to a multi-node installation with Docker-compose.

Before you begin, you must have:

  • A working 2.X installation

  • Downloaded either the .deb file for Ubuntu or the .rpm file for CentOS to a temporary location on your 2.X server

    See Using the Interactive Installers for details.

The commands that you need to run to perform the migration on Ubuntu are:

$ sudo apt-get install -y /<path-to-deb-file>/healthbot-<version>.deb
$ sudo healthbot setup

Answer “n” to the question about using Kubernetes.

The setup procedure contains the functions needed to detect the incompatibilities and transform the data. If incompatibilities are discovered, you are asked to confirm the data transformation attempt.

$ healthbot start

Check to see if your data was properly migrated.

The commands that you need to run to perform the migration on CentOS are:

sudo yum install -y /<path-to-rpm-file>/healthbot-<version>.rpm
sudo healthbot setup

Answer “n” to the question about using Kubernetes.

The setup procedure contains the functions needed to detect the incompatibilities and transform the data. If incompatibilities are discovered, you are asked to confirm the data transformation attempt.

$ healthbot start

Check to see if your data was properly migrated.

Case 2: Automated Migration from 2.X to 3.X (Kubernetes)

Before you begin, you must have:

  • A working HealthBot 2.X installation

  • Run $ healthbot stop on the 2.X server

  • Downloaded either the .deb file for Ubuntu or the .rpm file for CentOS to your 3.X server

    See Using the Interactive Installers for details.

  • Run the interactive installers on your 3.X server.

    During the $ sudo healthbot setup phase of the install, answer “Y” to the question about installing with Kubernetes.

    See Using the Interactive Installers for details.

When healthbot setup reports success, do not run healthbot start. Instead, run the following commands:

  • Run $ healthbot migrate --host <ip address or hostname of 2.X installation>

    For example: $ healthbot migrate --host 10.209.11.124

    The migration function immediately prompts you for an ssh username and password to use to connect to the 2.X server. The credentials you provide must have root privileges. Once connected to the 2.X server, it collects the following files needed for migration and places them in the appropriate directories on the new server:

    • Configuration files

    • TSDB files

    • Helper files

    Once collected, the migration function scans the configuration and TSDB files for incompatibilities. If any are found, it tries to transform them to make them compatible with HealthBot 3.X.

  • Run $ healthbot start
  • Check to see if your data migrated properly.

Case 3: Manual Migration from 2.X to 3.X (Kubernetes)

Before you begin, you must have:

  • A working HealthBot 2.X installation

  • Run $ healthbot stop on the 2.X server

  • Downloaded either the .deb file for Ubuntu or the .rpm file for CentOS to your 3.X server

    See Using the Interactive Installers for details.

  • Run the interactive installers on your 3.X server.

    During the $ sudo healthbot setup phase of the install, answer “Y” to the question about installing with Kubernetes.

    See Using the Interactive Installers for details.

When healthbot setup reports success, do not run healthbot start. Instead, run the following commands on the 2.X server:

  • $ tar czf /tmp/influx.tgz /var/local/healthbot/etc/data/influxdb
  • $ tar czf /tmp/helper.tgz /var/local/healthbot/input
  • $ scp /tmp/helper.tgz /tmp/influx.tgz /var/local/healthbot/config/healthbot.json <username>@<ip or hostname of 3.x server>:</writable/directory/on/3.x/server>

    For example: $ scp /tmp/helper.tgz /tmp/influx.tgz /var/local/healthbot/config/healthbot.json user@10.100.101.12:/var/tmp/ where user is a valid username on the host with permission to write in the /var/tmp/ directory.

  • On the 3.X server, run: $ healthbot migrate -c </path/to/healthbot.json> -t </path/to/influx.tgz> -hf </path/to/helper.tgz>

    For example: $ healthbot migrate -c /var/tmp/healthbot.json -t /var/tmp/influx.tgz -hf /var/tmp/helper.tgz

    The migration function scans the configuration and TSDB files for incompatibilities. If any are found, it requests confirmation from the user before it tries to transform them to make them compatible with HealthBot 3.X.

  • Run $ healthbot start
  • Check to see if your data migrated properly.