Upgrade from a previous version

Overview

This page explains how to upgrade SaltStack Enterprise to the latest stable version from a previous version. These upgrade instructions cover an upgrade from SaltStack Enterprise version 6.2.0 to version 6.3.0.

To upgrade SaltStack Enterprise, you will need to:

  • Back up your data, including certain files and directories that are crucial to your specific installation of SaltStack Enterprise
  • Upgrade PostgreSQL (optional, but recommended)
  • Upgrade your Salt infrastructure (optional, but recommended)
  • Download the upgrade files
  • Upgrade the Enterprise API (RaaS) node
  • Upgrade any Salt Masters using the Master Plugin

This page explains how to complete each of these steps in more detail.

Warning

If you are upgrading your SaltStack Enterprise installation, refer to the following upgrade instructions. Do not attempt to install using the automated installer (single-node or multi-node) or manual installation instructions.

Upgrading versions earlier than 6.2.0

As a best practice, always upgrade from the latest major version of SaltStack Enterprise to the new release. If you are upgrading from a version earlier than 6.2.0, you might see the best results if you upgrade in increments from one major release to the next.

For instructions on upgrading to earlier SaltStack Enterprise versions, see the specific upgrade instructions for the releases you are upgrading from. The upgrade instructions for previous releases are included in the installation guide PDF for the subsequent release. For example, if you need to upgrade from 5.5 to 6.0, see the upgrade instructions in the 6.0 installation PDF.

Version Installation and Upgrade Guide PDF
6.3 6.3 Installation and Upgrade Guide
6.2 6.2 Installation and Upgrade Guide
6.1 6.1 Installation and Upgrade Guide
6.0.1 6.0.1 Installation and Upgrade Guide
6.0 6.0.0 Installation and Upgrade Guide
5.5.1 5.5.1 Installation and Upgrade Guide

Best practices when upgrading

When preparing to perform an upgrade of SaltStack Enterprise, the following recommendations could be helpful:

  • Back up your data. In order to prevent data loss, back up your data. For an explanation of which files and directories must be backed up before upgrading, see Back up your data.
  • Perform upgrades during hours of slow network activity. Database upgrades require re-indexing data. Depending on the complexity of your data, a database upgrade could potentially take several hours. To prevent service disruptions, consider upgrading the database during slower business hours or trimming your database prior to an upgrade.
  • Test the upgrade before deploying. If possible, you could try running a dress rehearsal in a test environment to get a sense of how long the upgrade could take.
  • Read through the whole guide first. Consider also reading through this entire guide one time before you implement an upgrade so that you have a good sense of the tasks that are required and whether they require planning from your team or if stakeholders must be notified of pending changes.

Back up your data

Before upgrading SaltStack Enterprise, you should always back up your data. The following sections explain which data needs to be backed up so that it can be restored after you complete the upgrade process.

Back up SaltStack Enterprise files and directories

The following files and directories contain your custom SaltStack Enterprise configurations and need to be backed up before upgrading:

  1. On the Enterprise API (RaaS) node, back up these entire directories:

    • /etc/raas/raas
    • /etc/raas/raas.secconf
    • /var/log/raas
    • /etc/raas/pki/

    Note

    The pki directory contains hidden files, so ensure you back up the entire directory.

    Backing up the log files in the /var/log/raas directory is optional. During the upgrade process, you’ll clear the log files to provide a clean log file if troubleshooting is necessary.

  2. On each Salt Master, back up the /etc/salt/master.d/raas.conf and /etc/salt/master.d/eAPIMasterPaths.conf files.

    Note

    Depending on how you initially installed SaltStack Enterprise, the eAPI Master paths could instead be in the /etc/salt/master.d/raas.conf file instead.

After backing up the SaltStack Enterprise and Salt Master files, proceed to the next section.

Back up your database schema

When upgrading your Enterprise API (RaaS) node, the database schema is updated. For that reason, ensure you create a backup of your database before the upgrade.

To back up your database you need to first look up your PostgreSQL database name and then copy the contents:

  1. On the PostgreSQL server, back up these files:

    • postgres.conf
    • pg_hba.conf
  2. Log in as the postgres user using the following command:

    sudo su - postgres
    
  3. Get your database name, using the following commands to enter PostgreSQL and then list the databases:

    psql
    \l
    
  4. To exit PostgreSQL and log out as the postgres user, press Ctrl+D and then run the following command:

    exit
    
  5. Copy database contents to a file. The following command gives an example:

    pg_dump -U salt_eapi raas_db_name > postgres_raas_backup_$(date +%Y-%m-%d).sql
    

Your database files are now backed up. For the latest information about performing backups, see PostgreSQL database backups.

Upgrade PostgreSQL database

SaltStack Enterprise requires a PostgreSQL 9.6 database, but PostgreSQL 12.1 is recommended. The recommended version of PostgreSQL is included with the SaltStack Enterprise installer.

Upgrading to the latest version of PostgreSQL is not required. However, upgrading PostgreSQL can possibly improve performance. For instructions on upgrading to the latest version of PostgreSQL, see PostgreSQL upgrade.

Upgrade Salt

For best performance, ensure your Salt components are running on the latest major version of Salt. For instructions on upgrading your Salt Masters and other Salt components, see Upgrading Your Salt Infrastructure.

For instructions on upgrading the Salt Crystal package, see How to Upgrade Salt Crystal.

Download upgrade files

To download the files for upgrading:

  1. On the Downloads page, go to the Upgrade 6.2.0 to 6.3.0 requirements section.
  2. Download all files listed needed for upgrading.
  3. Verify the files. For specific instructions, see Verify the installation files.

After you’ve downloaded the files, proceed to the next section.

Upgrade the Enterprise API (RaaS) node

This section explains how to upgrade the Enterprise API (RaaS) node from 6.2.0 to version 6.3.0. Be aware that database upgrades require re-indexing data. If your data is complex, a database upgrade could potentially take several hours. For a discussion of when to plan an upgrade and other tips, see Best practices when upgrading.

Warning

Before upgrading your Enterprise API (RaaS) node, you must back up your system data to avoid data loss. For an explanation of which files and directories must be backed up before upgrading, see Back up your data.

To upgrade the Enterprise API (RaaS) node:

  1. Save any changes you made to the default file system, pillar data, and jobs as new files or jobs.

  2. Note any pillar assignments that are made to the default targets. These need to be re-assigned after upgrade.

  3. Stop the RaaS service using the following command:

    sudo systemctl stop raas
    
  4. Remove the log file(s) in the /var/log/raas directory. Clearing the log files provides a clean log file if troubleshooting is necessary.

  5. Remove the currently installed version of the Enterprise API with the following command:

    sudo yum remove raas
    
  6. Upgrade the Enterprise API (RaaS) node by installing the latest RPM. Use the following example command, replacing the exact file name of the RPM:

    sudo yum install raas-rpm-file-name.rpm
    
  7. IMPORTANT: Restore the backup of the following files:

    • /etc/raas/raas
    • /etc/raas/raas.secconf
    • /etc/raas/pki/
  8. Update permissions for the raas user with the following command:

    sudo chown -R raas:raas /etc/pki/raas/certs
    
  9. OPTIONAL: If you have a SaltStack Comply license, add the following new section to the /etc/raas/raas file:

    sec:
      ingest_override: true
      locke_dir: locke
      post_ingest_cleanup: true
      username: 'secops'
      content_url: 'https://enterprise.saltstack.com/secops_downloads'
      download_enabled: true
      download_frequency: 86400
      stats_snapshot_interval: 3600
      compile_stats_interval: 10
      ingest_on_boot: True
      content_lock_timeout: 60
      content_lock_block_timeout: 120
    

    Note

    This step is optional and only applies to organizations that have a valid SaltStack Comply and/or SaltStack Protect license. These add-on modules are available for SaltStack Enterprise versions 6.0 and later. The previous configuration options in the /etc/raas/raas configuration file are specific to these add-on modules.

  10. OPTIONAL: If you have a SaltStack Protect license , add a new section to the /etc/raas/raas file:

    vman:
      vman_dir: vman
      download_enabled: true
      download_frequency: 86400
      username: vman
      content_url: 'https://enterprise.saltstack.com/vman_downloads'
      ingest_on_boot: true
      compile_stats_interval: 60
      stats_snapshot_interval: 3600
      old_policy_file_lifespan: 2
      delete_old_policy_files_interval: 86400
      tenable_asset_import_enabled: True
      tenable_asset_import_grains: ['fqdn', 'ipv4', 'ipv6', 'hostname', 'mac_address', 'netbios_name',
                                    'bios_uuid', 'manufacturer_tpm_id', 'ssh_fingerprint',
                                    'mcafee_epo_guid', 'mcafee_epo_agent_guid', 'symantec_ep_hardware_key',
                                    'qualys_asset_id', 'qualys_host_id', 'servicenow_sys_id', 'gcp_project_id',
                                    'gcp_zone', 'gcp_instance_id', 'azure_vm_id', 'azure_resource_id',
                                    'aws_availability_zone', 'aws_ec2_instance_ami_id',
                                    'aws_ec2_instance_group_name', 'aws_ec2_instance_state_name',
                                    'aws_ec2_instance_type', 'aws_ec2_name', 'aws_ec2_product_code',
                                    'aws_owner_id', 'aws_region', 'aws_subnet_id', 'aws_vpc_id',
                                    'installed_software', 'bigfix_asset_id'
                                    ]
    

    Note

    This step is optional and only applies to organizations that have a valid SaltStack Protect license. This add-on module is available for SaltStack Enterprise versions 6.0 and later. The previous configuration options in the /etc/raas/raas configuration file are specific to these add-on modules.

  11. Upgrade the RaaS service database using the following command:

    sudo su - raas
    raas upgrade
    

    Note

    Depending on the size of your database, the upgrade can take anywhere from several minutes to over an hour.

    If you encounter errors, check the /var/log/raas/raas logfile for more information.

  12. After the upgrade, exit the session for the raas user with the following command:

    exit
    
  13. Start the RaaS service using the following command:

    sudo systemctl enable raas
    sudo systemctl start raas
    

Verify that SaltStack Enterprise is functioning correctly and is running the latest version. Proceed to the next section.

Upgrade Salt Masters with the Salt Master plugin

After you have successfully upgraded the Enterprise API (RaaS) node, you can then upgrade any Salt Masters that use the Salt Master plugin to connect to SaltStack Enterprise.

Note

Before you upgrade the Salt Masters, ensure that the pip3 application is installed on the Salt Masters. If you are upgrading from the latest version of the Salt Master plugin, this application is already installed.

To upgrade the Salt Master plugin on a Salt Master:

  1. Stop the salt-master service using the following command:

    sudo systemctl stop salt-master
    
  2. Check which version of Python is running on the Salt Master. If it is running Python 3.6 or higher, no changes are needed. Otherwise, delete the prior version of the SSEAPE module. (The SSEAPE is the SaltStack Enterprise plugin for the Salt Master). For example:

    sudo rm -rf /usr/lib/python3.6/site-packages/SSEAPE*
    
    sudo rm /usr/lib/python3.6/dist-packages/SSEAPE*
    
  3. Upgrade the Salt Master plugin by manually installing the updated Python wheel. Use the following example commands, replacing the exact name of the wheel file:

    sudo pip3 install SSEAPE-file-name.whl --prefix /usr
    
    sudo pip3 install SSEAPE-file-name.whl
    

    Note

    Some users might need to alter the syntax to pip3.6 or pip36 for their operating systems.

  4. Update the Enterprise API module paths by editing the /etc/salt/master.d/eAPIMasterPaths.conf file to reference the paths to the various modules. For example, you might change all python2.7 references in this file to python3.6.

    Note

    Depending on how you initially installed SaltStack Enterprise, the eAPI Master paths could instead be in the /etc/salt/master.d/raas.conf file instead.

  5. Check the engines section in /etc/salt/master.d/raas.conf to confirm that it matches the following:

    engines:
      - sseapi: {}
      - eventqueue: {}
      - rpcqueue: {}
      - jobcompletion: {}
    

    Note

    If a problem occurred, you may need to restore your backups of the /etc/salt/master.d/raas.conf and /etc/salt/master.d/eAPIMasterPaths.conf files.

  6. Start the salt-master service with the following command:

    sudo systemctl start salt-master
    

The upgrade process is now complete. If you encounter any other errors, refer to the Troubleshooting page or Contact Support.