Skip to main content
SaltStack Support

Upgrade SaltStack Enterprise 5.4 to SaltStack Enterprise 5.5

The following information will help you prepare for the SaltStack Enterprise upgrade. SaltStack recommends that you always upgrade from the latest shipping code to the new release.

Redis added to SaltStack Enterprise

Redis has been added to SaltStack Enterprise. You will need to install Redis 4.x into your environment. If your SaltStack Enterprise deployment is on a single host, install Redis. If your deployment is on multiple hosts, create a host for Redis.

  1. Download the Redis and jemalloc installation packages for RH/CentOS that are provided under the Manual installation section.

    sudo yum install redis40u-4.0.11-1.ius.el7.x86_64.rpm jemalloc-3.6.0-1.el7.x86_64.rpm
    
  2. Update configuration (if Redis is on a separate host)

    If you are setting up Redis on a host that is separate from SaltStack Enterprise, you will need to configure Redis to accept remote connections and to limit access using a password. To do this, update the /etc/redis.conf file, specifying the bind parameter and setting the password that your SaltStack Enterprise servers should use to authenticate.

    bind 0.0.0.0
    requirepass 
    
  3. Start the redis service

    systemctl enable redis
    systemctl start redis

PyCrypto extension required for raas Database

The pycrypto extension is now required. To make this available to your PostgreSQL database, complete the following steps.

  1. Install the postgresql-contrib package on the PostgreSQL server.

    This extension requires PostgreSQL superuser privileges to install into the raas database.

    sudo yum install postgresql96-contrib
    
  2. Grant the raas user superuser privileges:

    The pycrypto extension requires Postgres superuser privilege to install into the raas database.

    su - postgres
    psql -d raas_<your_customer_id> -c 'ALTER USER <your_user> WITH SUPERUSER'
    
  3. Perform the raas upgrade. See Upgrading.

  4. Revoke the superuser privilege from the raas user.

    psql -d raas_<your_customer_id> -c 'ALTER USER <your_user> WITH NOSUPERUSER'
    

What to back up prior to the upgrade

  • Files / Directories

    • /etc/raas/raas
    • /etc/raas/pki/ - this contains hidden files, so back up the entire directory
    • /etc/salt/master.d/raas.conf - located on each Salt Master
    • postgres.conf - if local PostgreSQL
    • pg_hba.conf - if local PostgreSQL
  • Database

    When upgrading your raas server, the database schema will need to be updated. Make sure to create a backup of your database before the upgrade. An example of this command is:

        pg_dump -U salt_eapi raas_abc123... > postgres_raas_backup_$(date +%Y-%m-%d).sql
    
  • Targets, jobs, and the default SaltStack Enterprise Filesystem

    During the upgrade process, the default targets, jobs, and files in the Filesystem are updated to the latest version. Modifications you’ve made to these files are not preserved.

    Note the following:

    • Pillar assignments to default targets are not preserved. These need to be re-assigned after upgrade.
    • Pillar assignments to custom targets are preserved.
    • Custom files, pillar data, and jobs are preserved.
    • Role customizations are preserved.
    • User accounts and passwords are preserved.

Upgrading

  1. Back up your database. See PostgreSQL database backups for more information.

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

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

On the SaltStack Enterprise server

  1. Stop the raas service.

    sudo systemctl stop raas
    
  2. Back up or remove the log file(s) at /var/log/raas/raas. This provides a clean log file if troubleshooting is required.

  3. Back up or rename the /etc/raas/raas config file. You’ll need to restore this file after upgrading.

  4. Remove the currently installed version of Enterprise API.

    sudo yum remove raas
    
  5. Upgrade SaltStack Enterprise server by installing the latest RPM. For example:

    sudo yum install raas-5.5-1.el7.x86_64.rpm
    
  6. Restore the backup of the /etc/raas/raas config file.

  7. Add the following new configuration options to /etc/raas/raas:
    • Change driver: pg8000 to driver: psycopg2.

      background_workers:
        combined_process: True
        max_tasks: 100000
        max_memory: 1048576
      

      SaltStack Enterprise includes various background worker settings to improve performance for a range of deployment scenarios. For more on customizing background worker settings, see Background Worker Options.

      redis:
        url: redis://<Redis_IP>:6379
      
      # AD/LDAP driver configuration
      #authers:
      #  ldap:
      #    # Allowed log levels
      #    # - OFF       # nothing is logged
      #    # - ERROR     # only exceptions are logged
      #    # - BASIC     # library activity is logged, only operation result is shown
      #    # - PROTOCOL  # LDAPv3 operations are logged, sent requests and received responses are shown
      #    # - NETWORK   # socket activity is logged
      #    # - EXTENDED  # LDAP messages are decoded and properly printed
      #    log_level: ERROR
      #    ssl:
      #      # Allowed ciphers values
      #      # - TLSv1.2
      #      # - SSLv23  # Default value selected if not defined when the
      #      #           # AD auth config has use_ssl set to True
      #      ciphers: SSLv23
      #      ca_cert: /path/to/ca_cert.pem
      #      client_key = /path/to/client.key
      #      client_cert = /path/to/client.pem
      
  8. Start the raas service in debug mode in the foreground with:

    sudo raas -l debug
    

    This allows you to confirm that the /etc/raas/raas file was updated correctly. The process exits with a note that an update to the raas database is required. If you see this message, proceed with the upgrade. Otherwise, review your raas.conf file.

  9. Upgrade the raas database with:

    sudo raas upgrade
    

    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.

  10. Start the Enterprise API service.

    sudo systemctl enable raas
    sudo systemctl start raas
    
  11. Upgrade the “Preloaded Formulas”.

    To upgrade the “Preloaded Formulas” (Jobs), see KB Manually Adding “Preloaded Formulas” (Jobs) when doing a Manual Installation of SaltStack Enterprise.

On each connected Salt Master

  1. Stop the salt-master service.

    sudo systemctl stop salt-master
    
  2. Delete the SSEAPI Python module:

    Delete the prior version of the SSEAPE module (this is the SaltStack Enterprise plugin for the Salt Master). For example:

    RHEL:
    sudo rm -rf /usr/lib/python2.7/site-packages/SSEAPE*
    
    Ubuntu:
    sudo rm /usr/lib/python2.7/dist-packages/SSEAPE*
    
  3. Manually upgrade the Salt Master plugin by installing the updated Python egg.

    sudo easy_install-2.7 SSEAPE-5.5.1-py2.7.egg
    
  4. Update the eAPI Master paths.

    • Edit /etc/salt/master.d/eAPIMasterPaths.conf to reference the path to the new egg version.
    • If you are upgrading from a version of SaltStack Enterprise prior to 5.4, use the following command to generate the the paths:

      sudo sseapi-config --ext-modules > /etc/salt/master.d/eAPIMasterPaths.conf
      
    • Be sure to remove any of the path references from /etc/salt/master.d/raas.conf, as these were relocated in a previous release of SaltStack Enterprise.
  5. Add - job_completion: {} to the engines section of /etc/salt/master.d/raas.conf.

  6. Start the salt-master service.

    sudo systemctl start salt-master
  • Was this article helpful?