The documentation you're currently reading is for version 2.3.2. Click here to view documentation for the latest stable version.
To upgrade StackStorm, use the standard upgrade procedure for your Linux
distribution. You can simply upgrade the specific packages namely
Most of these upgrades should be seamless and do no require the user to do anything else.
st2 package, depending on the
from version and the
to version, you might need to run
migration scripts for picking up data model changes.
The list of migrations to run when upgrading to a version is listed in the section below.
If you skipped a version and are upgrading to a newer version, please make sure you run migration scripts for skipped versions as well.
Migration scripts most often need to be run when upgrading to StackStorm :versions that include data model changes. The typical upgrade procedure is
st2*services on the box.
sudo st2ctl stop
- Upgrade StackStorm packages (
bwc-enterpriseusing distro specific tools.
Ubuntu:sudo apt-get install --only-upgrade $PKG_NAME
RHEL / CentOS:sudo yum update $PKG_NAME
- Upgrade Mistral database.
/opt/stackstorm/mistral/bin/mistral-db-manage --config-file /etc/mistral/mistral.conf upgrade head /opt/stackstorm/mistral/bin/mistral-db-manage --config-file /etc/mistral/mistral.conf populate
The mistral and mistral-api services must be stopped at time of upgrade. If the services are
restarted before the mistral-db-manage commands are run, then the
mistral-db-manage upgrade head command may fail.
- Run the migration script (if any). See section below for StackStorm version-specific migration scripts.
- Start StackStorm services.
sudo st2ctl start
Version-specific Migration Scripts¶
We document upgrade notes for the various versions. The upgrade notes section gives an idea of what major changes happened with each release. You may also want to take a look at detailed Changelog for each version. Following sections call out the migration scripts that need to be run before upgrading to the respective version
- The database schema for Mistral has changed. The executions_v2 table is no longer used. The
table is being broken down into workflow_executions_v2, task_executions_v2, and
action_executions_v2. After upgrade, using the Mistral commands from the command line such as
mistral execution-listwill return an empty table. The records in executions_v2 have not been deleted. The commands are reading from the new tables. There is currently no migration script to move existing records from executions_v2 into the new tables. To read from executions_v2, either use psql or install an older version of the python-mistralclient in a separate python virtual environment.
Please be sure to follow the general steps listed above to do the database upgrade.
- If you’re seeing an error
event_triggers_v2 already existswhen running
mistral-db-manage upgrade head, this means the mistral services started before the mistral-db-manage commands were run. SQLAlchemy automatically creates new tables in the updated database schema and it conflicts with the mistral-db-manage commands. To recover, open the psql shell and delete the new tables manually and rerun the mistral-db-manage commands. The following is a sample script to recover from the errors.
sudo service mistral-api stop sudo service mistral stop sudo -u postgres psql \connect mistral DROP TABLE event_triggers_v2; DROP TABLE workflow_executions_v2 CASCADE; DROP TABLE task_executions_v2; DROP TABLE action_executions_v2; DROP TABLE named_locks; \q /opt/stackstorm/mistral/bin/mistral-db-manage --config-file /etc/mistral/mistral.conf upgrade head /opt/stackstorm/mistral/bin/mistral-db-manage --config-file /etc/mistral/mistral.conf populate sudo service mistral start sudo service mistral-api start
- Datastore model migration - Scope names are now
st2kv.useras opposed to
- We are piloting pluggable runners (See upgrade notes). Runners now have to be explicitly registered just like other content.
- Service restart
st2ctl restartand reload
st2ctl reloadare required after upgrade for the new pack management features to work properly. Some of the pack management actions and workflows have changed.
- Datastore model migration
In some cases, you may need to roll over the automation from one instance of StackStorm to another box or deployment. To do this, provision a new StackStorm instance, and roll over the content. Thanks to the “Infrastructure as code” approach, all StackStorm content and artifacts are simple files, and should be kept under source control.
- Install StackStorm
VERSION_NEWon a brand new instance using packages based installer.
- Package all your packs from the old
VERSION_OLDinstance and place them under some SCM like git (you should have done it long ago).
- Save your key-value pairs from the st2 datastore:
st2 key list -j > kv_file.json
- Grab packs from the SCM.
- If the SCM is git then it is possible to use
st2 run packs.install packs=<pack-list> repo_url=<repo-url>
- Reconfigure all external services to point to the new StackStorm instance.
- Load your keys to the datastore:
st2 key load kv_file.json. You might have to readjust the JSON files to include
secretif you are upgrading from version < 1.5 to 1.5 onwards. See migration script in
/opt/stackstorm/st2/bin/st2-migrate-datastore-to-include-scope-secret.pyfor an idea.
- Back up audit log from
VERSION_OLDserver found under
/var/log/st2/*.audit.logand move to a safe location. Note that history of old executions will be lost during such a transition, but a full audit record is still available in the log files that were transferred over.