Upgrade with playbooks#

Important

This page describes steps for upgrading existing installations.

For instructions to perform new installations, see Run installation playbooks instead.

Upgrading from CentOS 7/RHEL 7

If you are upgarding an EcelcticIQ Intelligence Center instance on managed nodes that are running on CentOS 7 or RHEL 7, you must upgrade the operating system to Rocky Linux 8 or RHEL 8 before following the instructions here.

See:

This section containst instructions for running the playbooks to upgrade EclecticIQ Intelligence Center 2.14 to 3.0.

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

To upgrade EclecticIQ Intelligence Center using these playbooks:

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

    If you have to re-create these files, follow the instructions in Prepare nodes.

  • You must run the playbooks in the sequence specified.

  • 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

Upgrade operating system#

EclecticIQ Intelligence Center 3.0.0 and newer requires one of these supported operating systems:

  • Red Hat Enterprise Linux 8

  • Rocky Linux 8

If you are using an older operating system such as CentOS 7 or RHEL 7, you must upgrade your operating system to one of the supported operating systems before attempting to install EclecticIQ Intelligence Center 3.0.

See:

Requirements#

  • An existing EclecticIQ Intelligence Center installation playbook configuration, used previously in Prepare nodes and Run installation playbooks.

    Specifically, you must have an existing .env, ansible.cfg, and an inventory file appropriate for your deployment.

    If you have to re-create these files, follow the instructions in Prepare nodes.

  • Fulfill requirements stated in Prepare nodes

Upgrade with playbooks#

To upgrade an EclecticIQ Intelligence Center deployment, do the following:

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 secrets.

Set EclecticIQ Intelligence Center version to install by setting the following environment variables in .env:

# 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 char with on uppercase, one lowercase, one number and 1 symbol
# 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.1"
export EIQ_IC_API_VERSION="3.1.*"

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

source .env

Load secrets#

You should have an existing .env file containing secrets and credentials for the EclecticIQ Intelligence Center instance you are upgrading.

Tip

If you have to re-create these files, follow the instructions in Set up secrets.

Make sure this .env is loaded:

source .env

Back up existing configuration files#

Run the pb-backup_config.yml playbook to back up configuration files for your existing EclecticIQ Intelligence Center instance.

This backs up only configuration files on your EclecticIQ Intelligence Center deployment. Back up PostgreSQL and Elasticsearch data stores separately.

Danger

This overwrites the contents of ./eiq.backup/, relative to where the ansible-playbook command is run.

Archive this directory after each time you run pb-backup_config.yml, or make sure that group_vars/backup.yml is configured to back up to a different directory each time you run this.

By default, this playbook writes backups to ./eiq.backup/ on the control node, relative to where the ansible-playbook command is run.

Change where configuration file backups are written to by editing the config_backup_dest_folder parameter in group_vars/backup.yml. Running pb-backup_config.yml more than once without changing this parameter will overwrite your previous backup.

Tip

Omit --tags=all,logstash from commands if your deployment configuration does not include Logstash.

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

Remove Neo4j#

If upgrading from EclecticIQ Intelligence Center 2.14, you may need to remove Neo4j from an existing host.

To do this:

  1. Edit inventories/ic-remove-neo4j.yml.

    This is a separate inventory file for the pb-remove_neo4j.yml playbook.

    Set neo4j-node-01.ansible_host to the network address of the host to remove Neo4j from.

  2. From the control node, run the pb-remove_neo4j.yml playbook with the above inventory file:

    ansible-playbook -i inventories/ic-remove-neo4j.yml pb-remove_neo4j.yml

Run the playbooks#

After completing all the above sections, run the playbooks.

On the control node, run playbooks with the ansible-playbook command. For example (omit --tags=all,logstash if your deployment configuration does not include Logstash):

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

Run the playbooks in this sequence:

  1. Run the pre-requisites playbook: pb-pre_requisites.yml

  2. Run the install playbook: pb-install_intelligence_center.yml

  3. Make sure services have started at least once: pb-start_services.yml

  4. Run database migrations: pb-migrate_databases.yml

  5. Start services: pb-start_services.yml

  6. Run post-install playbook: pb-post.yml

  7. Reboot your managed node(s) after pb-post.yml completes.

Important

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

  1. Migrate your existing inventory file to an inventory file for your deployment size.

  2. Run the playbooks for initializing Elasticsearch and PostgreSQL clusters, as instructed in Production deployments.