Backup and Upgrade

Note

Upgrades of OKA are only supported between 2 consecutive minor versions, or latest minor to next major. Within a minor version, upgrade to any patch version is supported.

For example:

if you have version X.Y.Z (e.g., 1.10.0) , you cannot upgrade to version X.(Y+2).Z’ (e.g., 1.12.1) but you can upgrade to X.(Y+1).Z’ (e.g., 1.11.3)
if 1.15.5 is the latest minor version of major version 1, then you can upgrade to (X+1).0.Z’ (e.g., 2.0.3)

Warning

OKA update might take several hours depending on the size of your ElasticSearch database. We recommend to execute the installer in a screen (or similar tools such as tmux) to avoid untimely deconnections during the installation.

To upgrade OKA:

To upgrade OKA, you must first stop OKA services: sudo systemctl stop oka.service.

You must then backup the databases:

First, ensure that both PostgreSQL and Elasticsearch databases are running and accessible (the upgrade process will also update both databases content).
Backup your Elasticsearch database. To learn more about Elasticsearch snapshots see How to create a snapshot. Note: the snapshots are incremental, so not all the data are saved during each snapshot/backup process.
You must configure your snapshot directory before trying to take a snapshot for the first time:
Create a directory with read/write access for Elasticsearch to store the snapshots:
sudo mkdir /opt/esdata
sudo chown elasticsearch: /opt/esdata
Add this line in /etc/elasticsearch/elasticsearch.yml:
path.repo: /opt/esdata
Restart Elasticsearch:
sudo systemctl restart elasticsearch
Query Elasticsearch to create a snapshot directory (in our case it will be /opt/esdata/backup), this directory does not need to exist beforehand, Elasticsearch will create it automatically. You can replace my_backup by the name you want:
curl -X PUT "host:port/_snapshot/my_backup" -H 'Content-Type: application/json' -d '
{
"type": "fs",
"settings": {
      "location": "backup",
      "compress": "true"
}
}'
Backup your Elasticsearch database (take a snapshot). We recommend that you create a snapshot with a name that includes the current date (see below example with $(date +%Y%m%d)). The wait_for_completion=true option will make the command synchronous: it will wait until the backup has been completed:
curl -X PUT "host:port/_snapshot/my_backup/snapshot_oka_$(date +%Y%m%d)"?wait_for_completion=true -H '
Content-Type: application/json' -d '
{
"metadata": {
      "taken_by": "your_name",
      "taken_because": "backup before upgrading OKA"
}
}'
On completion, check in the output the "state" of the backup, it should be "SUCCESS".

Note

Snapshots must be identified by unique names. The above command use the date of the snapshot as unique identifier (snapshot_oka_$(date +%Y%m%d)).

Note

You can add multiple metadata to your snapshot. We recommend to add at least your name and the reason why the snapshot was taken.

Note

Over time, snapshot repositories can accumulate stale data that is no longer referenced by existing snapshots. Use this command to clean the snapshot repository curl -XPOST "host:port/_snapshot/my_backup/_cleanup". In case you need to copy the snapshot to another Elasticsearch (e.g., preproduction VM), we recommend that you run this command first. This command can take a long time to complete.
Backup your PostgreSQL database:
pg_dump --dbname=oka_db --host=HOSTNAME --port=PORT --username=oka --password > oka_db.backup.sql

Once the databases have been saved, you can proceed and install the new version using OKA installer (see Deployment).

When it is done, restart OKA services: sudo systemctl start oka.service.

Rollback and Restore

In case something went wrong during the update, you can go back to the previous OKA version.

You must first uninstall OKA (see Uninstalling OKA).

You must then restore the databases:

Restore Elasticsearch snapshot:
curl -X POST "http://host:port/_snapshot/my_backup/<SNAPSHOT NAME>/_restore"
Note

Modify the snapshot name (<SNAPSHOT NAME>) to match the one provided during the backup procedure. You can list the available snapshots with:
curl -X GET "http://host:port/_cat/snapshots/my_backup"
Note

You can make this command synchronous by adding ?wait_for_completion=true after _restore.
Restore PostgreSQL database:
sudo -i -u postgres
psql
      DROP DATABASE oka_db;
      CREATE DATABASE oka_db;
      GRANT ALL PRIVILEGES ON DATABASE oka_db TO oka;
      ctrl+d
psql oka_db < oka_db.backup.sql
ctrl+d
sudo service postgresql restart

Once the databases are restored, you can proceed with the following steps:

Save your oka.conf file: cp "${OKA_INSTALL_DIR}/conf/oka.conf" /tmp/oka.conf

Delete current_version file: rm ${OKA_INSTALL_DIR}/current-version

Install the previous version using the desired OKA installer (see Deployment).

Check if the new oka.conf file matches with the one previously saved, or report any specific customization.

Restart OKA services: sudo systemctl start oka.service