> For the complete documentation index, see [llms.txt](https://archivedocs.stackstate.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://archivedocs.stackstate.com/5.1/setup/upgrade-stackstate/steps-to-upgrade.md). # Steps to upgrade ## Overview This document describes the upgrade procedure for StackState. For instructions on how to upgrade StackPacks, see [the StackPacks documentation](/5.1/stackpacks/about-stackpacks.md#upgrade-a-stackpack). ## Before you upgrade When executing a StackState upgrade, be aware of the following: {% hint style="warning" %} **Always read the** [**version-specific upgrade notes**](/5.1/setup/upgrade-stackstate/version-specific-upgrade-instructions.md) **before upgrading StackState.** {% endhint %} {% hint style="warning" %} When upgrading a StackPack, **any changes you have made to configuration items from that StackPack will be overwritten**. See [Configuration Locking](/5.1/stackpacks/about-stackpacks.md#locked-configuration-items) for more information. {% endhint %} {% hint style="danger" %} If there are **hotfixes** installed in your StackState installation, contact StackState technical support prior to upgrading. {% endhint %} ## 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: 1. [Create a backup](#create-a-backup) 2. [Upgrade StackState](#upgrade-stackstate) 3. [Verify the new installation](#verify-the-new-installation) 4. [Check if any installed StackPacks require an upgrade](/5.1/setup/upgrade-stackstate/stackpack-versions.md) ### 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 upgrade to a new **major** StackState release, StackState and the installed StackPacks may be incompatible with the current installation. For details, check the [version-specific upgrade notes](/5.1/setup/upgrade-stackstate/version-specific-upgrade-instructions.md). A major upgrade consists of the following steps: 1. [Create a backup](#create-a-backup) 2. Optional: [Uninstall StackPacks](#uninstall-stackpacks-optional) 3. [Upgrade StackState](#upgrade-stackstate) 4. Optional: [Install StackPacks](#install-stackpacks-optional) 5. [Verify the new installation](#verify-the-new-installation) ## Walkthrough of an upgrade ### Create a backup Before upgrading StackState it's recommended to back up your configuration and topology data. {% tabs %} {% tab title="Kubernetes" %} To create a backup on Kubernetes, see: * [Kubernetes backup](/5.1/setup/data-management/backup_restore/kubernetes_backup.md) * [Configuration backup](/5.1/setup/data-management/backup_restore/configuration_backup.md) * [Manually created topology backup](broken://pages/e0QRPwTjDbxvzaZ1k1TU) {% endtab %} {% tab title="Linux" %} To create a backup on Linux, see: * [Linux backup](/5.1/setup/data-management/backup_restore/linux_backup.md) * [Configuration backup](/5.1/setup/data-management/backup_restore/configuration_backup.md) * [Manually created topology backup](broken://pages/e0QRPwTjDbxvzaZ1k1TU) {% endtab %} {% endtabs %} {% hint style="info" %} Note that it won't 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. {% endhint %} ### Uninstall StackPacks (optional) See [Uninstalling StackPacks](/5.1/stackpacks/about-stackpacks.md#install-or-uninstall-a-stackpack) for more information. {% hint style="warning" %} 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. {% endhint %} ### Upgrade StackState 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. {% tabs %} {% tab title="Linux" %} 1. Check the [version specific upgrade notes](/5.1/setup/upgrade-stackstate/version-specific-upgrade-instructions.md) for specific changes that need to be made for the new StackState version you will upgrade to. 2. Download the upgrade file from . 3. Depending on your platform, use one of the following commands to upgrade: * **Fedora, RedHat, CentOS:** * using RPM: `rpm -U .rpm` * using yum: `yum localinstall .rpm` * **Debian, Ubuntu:** * using dpkg: `dpkg -i .deb` * using apt: `apt-get upgrade .deb` {% endtab %} {% tab title="Kubernetes" %} 1. Get the latest helm chart by running `helm repo update`. 2. Check the [version specific upgrade notes](/5.1/setup/upgrade-stackstate/version-specific-upgrade-instructions.md) 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. To upgrade, use the same helm command as for the [first time Kubernetes installation](/5.1/setup/install-stackstate/kubernetes_openshift/kubernetes_install.md#deploy-stackstate-with-helm). The new helm chart will pull newer versions of Docker images and handle the upgrade. {% endtab %} {% tab title="OpenShift" %} 1. Get the latest helm chart by running `helm repo update`. 2. Check the [version specific upgrade notes](/5.1/setup/upgrade-stackstate/version-specific-upgrade-instructions.md) 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. [Update the `openshift-values.yaml`](/5.1/setup/install-stackstate/kubernetes_openshift/openshift_install.md#additional-openshift-values-file) file. 4. To upgrade, use the same helm command as for the [first time OpenShift installation](/5.1/setup/install-stackstate/kubernetes_openshift/openshift_install.md#deploy-stackstate-with-helm). The new helm chart will pull newer versions of Docker images and handle the upgrade. {% endtab %} {% endtabs %} ### Install StackPacks (optional) See [Installing StackPacks](/5.1/stackpacks/about-stackpacks.md#install-or-uninstall-a-stackpack) 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 * [Manually upgrade a StackPack](/5.1/stackpacks/about-stackpacks.md#upgrade-a-stackpack) * [StackPack versions shipped with each StackState release](/5.1/setup/upgrade-stackstate/stackpack-versions.md) * [Version-specific upgrade notes](/5.1/setup/upgrade-stackstate/version-specific-upgrade-instructions.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://archivedocs.stackstate.com/5.1/setup/upgrade-stackstate/steps-to-upgrade.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.