Upgrade with playbooks#

Important

This page describes steps for upgrading existing installations.
For instructions to perform new installations, see New install with playbooks instead.

Upgrading from CentOS 7/RHEL 7

If you are installing or upgrading EcelcticIQ Intelligence Center on managed on older operating systems (e.g. CentOS 7, RHEL 7), you must upgrade the operating system to Rocky Linux 8 or RHEL 8 before following the instructions here.

See:

This section contains instructions for running the playbooks to upgrade EclecticIQ Intelligence Center.

Supported: Upgrade EclecticIQ Intelligence Center 2.14 to 3.1

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)

Requirements#

To upgrade EclecticIQ Intelligence Center using these playbooks, fulfill these requirements.

Control node:

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

    Follow the instructions in Prepare nodes to reconstruct these files if needed.

Managed nodes:

  • Must run one of these supported operating systems:

    • Red Hat Enterprise Linux 8

    • Rocky Linux 8

  • Fulfill requirements stated in Prepare 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.

You should have an existing .env file from a previous installation. If you do not, follow instructions in Prepare nodes to reconstruct one.

Update this .env file to set the target EclecticIQ Intelligence Center 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 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

Back up existing configuration files#

See Back up and restore with playbooks.

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 upgrade#

After completing all the above sections, run the playbooks.

You must run the playbooks in the sequence specified.

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

On the control node, run playbooks with the ansible-playbook command with these command line 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 an inventory file configured for your deployment.

Inventory files are described in Prepare nodes.

<pb-playbook.yml>

This is the playbook to run.

Run the playbooks in this sequence:

  1. Load .env. Run:

    source .env

  2. Prepare nodes: pb-pre_requisites.yml

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

  3. Install components: pb-install_intelligence_center.yml

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

  4. Make sure services have started: pb-start_services.yml

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

  5. Run database migrations: pb-migrate_databases.yml

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

  6. Start services: pb-start_services.yml

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

  7. Run the post-installation playbook: pb-post.yml

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

  8. 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 New install with playbooks.