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

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.3"

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.

Back up Kibana configuration and dashboards#

You must back up Kibana configuration and dashboards with pb-backup_kibana.yml before attempting to upgrade.

You must run the Kibana backup playbook (pb-backup_kibana.yml) before attempting an Upgrade with playbooks to preserve custom configuration and dashboards.

Before following instructions here, you must make sure that:

  • Kibana and Elasticsearch are running

  • Control node must be able to connect to Kibana and Elasticsearch

To back up Kibana configuration and dashboards,

  1. Make sure your .env file is loaded:

    source .env

  2. Run the pb-backup_kibana.yml playbook. Kibana and Elasticsearch must be running.

    ansible-playbook -i inventories/<inventory_file.yml> pb-backup_kibana.yml

When the backup completes, make sure that ic-kibana-objects.ndjson:

  • Is successfully created in your backup directory on the control node.

  • Contains expected contents (e.g. named custom dashboards).

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:

Tip

Playbooks here are idempotent. Repeated runs have no effect.

If there is nothing for a playbook to do (e.g. tasks do not apply to deployment type), running it has no effect.

  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 foundation and base roles: pb-install-foundations-and-base.yml

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

  4. Run Elasticsearch upgrade and data migration: pb-es-upgrade-data.yml

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

  5. Install components: pb-install_intelligence_center.yml

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

  6. Run PostgreSQL upgrade: pb-pg_upgrade.yml

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

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

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

  8. Run database migrations: pb-migrate_databases.yml

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

  9. Start services: pb-start_services.yml

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

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

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

  11. 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 PostgreSQL clusters, as instructed in New install with playbooks.

Restore Kibana configuration and dashboard#

Run the Kibana restore playbook to restore Kibana configuration and dashboards. If you have any custom Kibana configuration or dashboards, you must run this to make them available.

Before following instructions here, you must make sure that:

  • Kibana and Elasticsearch are running

  • Control node must be able to connect to Kibana and Elasticsearch

  • ic-kibana-objects.ndjson must be present in the backup destination directory on your control node.

To restore up Kibana configuration and dashboards,

  1. Make sure your .env file is loaded:

    source .env

  2. Run Kibana restore playbook: pb-restore-kibana.yml

    The playbook expects ic-kibana-objects.ndjson, to be in the backup destination directory on the control node.

    ansible-playbook -i inventories/ic-test-small.yml pb-restore-kibana.yml