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.2
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.2"
After setting these values, make sure to reload your .env
file:
source .env
Back up existing configuration files#
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,
Make sure your
.env
file is loaded:source .env
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:
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.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 |
---|---|
|
(Optional) Use |
|
Specify the path to an inventory file configured for your deployment. Inventory files are described in Prepare nodes. |
|
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.
Load
.env
. Run:source .env
Prepare nodes:
pb-pre_requisites.yml
ansible-playbook --tags=all,logstash -i inventories/<inventory_file.yml> pb-pre_requisites.yml
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
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
Install components:
pb-install_intelligence_center.yml
ansible-playbook --tags=all,logstash -i inventories/<inventory_file.yml> pb-install_intelligence_center.yml
Run PostgreSQL upgrade:
pb-pg_upgrade.yml
ansible-playbook --tags=all,logstash -i inventories/<inventory_file.yml> pb-pg_upgrade.yml
Make sure services have started:
pb-start_services.yml
ansible-playbook --tags=all,logstash -i inventories/<inventory_file.yml> pb-start_services.yml
Run database migrations:
pb-migrate_databases.yml
ansible-playbook --tags=all,logstash -i inventories/<inventory_file.yml> pb-migrate_databases.yml
Start services:
pb-start_services.yml
ansible-playbook --tags=all,logstash -i inventories/<inventory_file.yml> pb-start_services.yml
Run the post-installation playbook:
pb-post.yml
ansible-playbook --tags=all,logstash -i inventories/<inventory_file.yml> pb-post.yml
Reboot your managed node(s) after
pb-post.yml
completes.
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 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,
Make sure your
.env
file is loaded:source .env
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
(Recommended) 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.
Do not store credentials in version control.