Upgrade with playbooks#

Important

This page describes steps for upgrading existing installations.

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

To upgrade an existing EclecticIQ Intelligence Center 2.x deployment, follow instructions here.

To upgrade EclecticIQ Intelligence Center using these playbooks:

  • You must have an existing .envrc, 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

Supported upgrade paths#

The following upgrade paths are supported:

Upgrade from …

Target version

2.12

2.13, 2.14

2.13

2.14

Requirements#

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

    Specifically, you must have an existing .envrc, 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 group_vars/all/config-all.yml#

In your existing playbook configuration, edit the group_vars/all/config-all.yml file.

In it, set the following parameters:

Parameter

Description

eiq_ic_version

Set this to the EclecticIQ Intelligence Center version to upgrade to.

E.g.: To upgrade to 2.14, set this to 2.14

Tip

The playbooks will always install the latest version of EclecticIQ Intelligence Center within the specified minor version.

eiq_ic_api_version

Specify a version of EclecticIQ Intelligence Center public API package to install.

This must match the EclecticIQ Intelligence Center being installed/upgraded to.

The following is a list of IC versions and their compatible eiq_ic_api_version values:

  • 2.11 - 2.12: 1.0.*

  • 2.13: 1.1.*

  • 2.14: 2.14.*

Load secrets#

You should have an existing .envrc 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 .envrc is loaded:

source .envrc

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 ./tmp/ic-config, 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 ./tmp/ic-config 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

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. (Optional) Run the pre-requisites playbook to install OS updates on your managed nodes: pb-pre_requisites.yml

    You must reboot all managed nodes after this playbook completes.

  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

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.