Steps to upgrade
StackState Self-hosted v5.0.x

Overview

This document describes the upgrade procedure for StackState.
For instructions on how to upgrade StackPacks, see the StackPacks documentation.

Before you upgrade

When executing a StackState upgrade, be aware of the following:
Always read the version-specific upgrade notes before upgrading StackState.
When upgrading a StackPack, any changes you have made to configuration items from that StackPack will be overwritten. See Configuration Locking for more information.
If there are hotfixes installed in your StackState installation, contact StackState technical support prior to upgrading.

Steps to upgrade

Minor or maintenance StackState release

A minor release of StackState is indicated by a change in the second digit of the version number, for example 4.1.0. Maintenance releases are identified by a change in the third digit of the version number, for example 4.1.1.
If you are upgrading to a new minor StackState release or a maintenance release, StackState itself and the StackPacks will be compatible with the current installation.
A minor upgrade consists of the following steps:

Major StackState release

A major release of StackState is indicated by a change in the first digit of the version number, for example 4.0.0.
If you are upgrading to a new major StackState release, StackState and/or the installed StackPacks may be incompatible with the current installation. For details, check the version-specific upgrade notes.
A major upgrade consists of the following steps:
  1. 1.
    ​Create a backup​
  2. 2.
    Optional: Uninstall StackPacks​
  3. 3.
    ​Upgrade StackState​
  4. 4.
    Optional: Install StackPacks​

Walkthrough of an upgrade

Create a backup

Before upgrading StackState it is recommended to backup your configuration and topology data.
Kubernetes
Linux
To create a backup on Kubernetes, see:
To create a backup on Linux, see:
Note that it will not be possible to restore the backup on the upgraded version of StackState. The StackState backup can only be restored in the StackState and StackPack versions prior to the upgrade.

Uninstall StackPacks (optional)

See Uninstalling StackPacks for more information.
When uninstalling StackPacks, the version of StackState prior to the upgrade must be used since this version can contain different installation logic from the new StackPack version.

Upgrade StackState

Remember to check the version specific upgrade notes for specific changes that need to be made for the new StackState version you will upgrade to.
Instructions to upgrade a StackState Kubernetes or Linux setup can be found below.Be sure to check the release notes and any optional upgrade notes before running the upgrade.
Linux
Kubernetes
KOTS
KOTS Airgap
OpenShift
  1. 1.
    Download the upgrade file from https://download.stackstate.com.
  2. 2.
    Depending on your platform, use one of the following commands to upgrade:
    • Fedora, RedHat, CentOS:
      • using RPM: rpm -U <stackstate>.rpm
      • using yum: yum localinstall <stackstate>.rpm
    • Debian, Ubuntu:
      • using dpkg: dpkg -i <stackstate>.deb
      • using apt: apt-get upgrade <stackstate>.deb
  1. 1.
    Get the latest helm chart by running helm repo update.
  2. 2.
    Check the version specific upgrade notes for all changes between your current version and the version that you will upgrade to. If there have been changes made to configuration items specified in your values.yaml file, the file should be updated accordingly.
  3. 3.
    To upgrade, use the same helm command as for the first time Kubernetes installation. The new helm chart will pull newer versions of Docker images and handle the upgrade.
  1. 1.
    In the admin console, go to the Version History tab and click Check For Updates.
  2. 2.
    Click the View preflight checks logo to view or re-run the preflight checks.
  3. 3.
    To update the application, return to the Version History tab and click Deploy next to the target version.
Upgrades should be done through SSH and not the KOTS UI.
  1. 1.
    Upload the Airgap bundle to your server via SSH/SFTP.
  2. 2.
    Check the StackState version specific upgrade notes for all changes between your current StackState version and the version that you will upgrade to.
  3. 3.
    Run kubectl kots upstream upgrade stackstate -n default--airgap-bundle bundle_name.airgap.
  4. 4.
    Log in to the KOTS UI.
  5. 5.
    Click Config and update as needed. Click Save Config and then follow the prompts to re-deploy
  1. 1.
    Get the latest helm chart by running helm repo update.
  2. 2.
    Check the version specific upgrade notes for all changes between your current version and the version that you will upgrade to. If there have been changes made to configuration items specified in your values.yaml file, the file should be updated accordingly.
  3. 4.
    To upgrade, use the same helm command as for the first time OpenShift installation. The new helm chart will pull newer versions of Docker images and handle the upgrade.

Install StackPacks (optional)

See Installing StackPacks for more information.

Verify the new installation

Once StackState has been upgraded and started, verify that the new installation of StackState is reachable and that the application is running.

See also