Playbooks | 3.x | Upgrade | Run#

Important

This page describes steps for upgrading existing installations.
For instructions to perform new installations, see Playbooks | 3.x | Install instead.

This section contains instructions for running the playbooks to upgrade EclecticIQ Intelligence Center (EIQ IC).

Supported:

Upgrade EIQ IC 2.14 to 3.x
Upgrade EIQ IC 3.x to 3.y

If you are running an EIQ IC version older than 2.14, you must upgrade to 2.14 before following instructions here. See Upgrade EIQ IC (2.x only)

Requirements#

To upgrade EIQ IC using these playbooks, fulfill these requirements.

Upgrade operating system

When upgrading an EclecticIQ Intelligence Center (EIQ IC) instance on hosts running older operating systems (such as CentOS 7 or RHEL 7), you must upgrade the operating system to Rocky Linux 8 or 9, or RHEL 8 or 9 before attempting to upgrade to EIQ IC 3.0 and newer.

See:

Rocky Linux’ documentation:
- for migrating to Rocky Linux
- for upgrading Rocky Linux
RHEL’s documentation:
- for upgrading 7 > 8
- for upgrading 8 > 9

Control node:

You should have an existing .env, ansible.cfg, and an inventory file appropriate for your deployment.

If you do not, reconstruct them with the instructions for node preparation.

Managed nodes:

Go over the configuration of your managed nodes.

Update .env#

Caution

You may have used an .envrc file in earlier versions of the installation playbooks. Rename it to .env or create an .env file using instructions in Set up .env.

Update this .env file to set the target EIQ IC version to install:

# Recommend that you generate passwords with the below command:
# printf '~^'; cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1

# Password requirements: at least 10 chars with at least one uppercase, one lowercase, one number, and one special character.
# https://docs.eclecticiq.com/ic/current/install-configure-upgrade/rocky/install-the-ic/before-you-start/#user-name-and-password

export EIQ_IC_VERSION="3.5"

After setting these values, make sure to reload your .env file:

source .env

Carrying out the upgrade#

You can upgrade your EIQ IC deployment by running the provided installation script. This is the preferred, recommended upgrade method.

You could also run all playbooks individually (discouraged). This is more labor-intensive and error-prone.

Excute installation script#

To upgrade EIQ IC, use the /ic-playbooks/utils script to run all the required playbooks in order.

Install with Ollama host

If you’ve procured an Ollama node and entered its variables in the .env file for this installation, this script will run the playbooks that configure that node as a part of the deployment you chose.

To use the provided script, on your controle node, run:

./utils/deploy-from-inventory.sh

(Discouraged) Execute individual playbooks#

Use script instead

We recommend running the installation script instead of running individual playbooks.

Run the upgrade

After completing all the above sections, run the playbooks.

Tip

A playbook run is successful if has 0 failed tasks.

The following is an example PLAY RECAP from a successful (failed=0) single node playbook run:

PLAY RECAP ******************************************************************************************
application-node           : ok=64   changed=44   unreachable=0    failed=0    skipped=12   rescued=0    ignored=0   
localhost                  : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

See the ansible-playbook command and option example in the dropdown below:

Usage: Ansible playbook command and options

ansible-playbook --tags=all,logstash -i inventories/<inventory_file.yml> <pb-playbook.yml>

Option	Description
`--tags=all,logstash`	(Optional) Use `--tags=all,logstash` to include Logstash. You can omit this option entirely to install EclecticIQ Intelligence Center without Logstash.
`-i inventories/<inventory_file.yml>`	Specify the path to the inventory file that matches your chosen deployment.
`<pb-playbook.yml>`	This is the playbook to run.

Run the playbooks in the sequence specified in the dropdown below:

Important

If you are adding Elasticsearch or PostgreSQL nodes to your deployment, you must:

Migrate your existing inventory file to an inventory file for your deployment size.
Run the playbooks for initializing PostgreSQL clusters, as instructed in Playbooks | 3.x | Install | Run.

After upgrade#

Save and version control playbook configuration#

Save and version control your playbook configuration. Playbook configurations document your deployment, and can be used to administer and upgrade your EclecticIQ Intelligence Center instance.

Warning

Do not store credentials in version control.

Refresh your browser#

Your browser might have cached chunks of the old version of your platform. This may cause the follow errors when booting up the platform:

  "Failed to fetch dynamically imported module",
  "Importing a module script failed",
  "Failed to load resource: the server responded with a status of 401",
  "error loading dynamically imported module"

Doing a hard refresh clears your browser’s caches and prevents these errors from cropping up. Check below to see how to do a hard reset on your browser on your OS.