Skip to main content
This guide explains the supported process for upgrading an on-prem Omni installation.

​
Upgrade Policy

To maintain data integrity, follow these upgrade policies:
  • Sequential upgrades only: Upgrade one minor version at a time. For example, upgrading from v1.3 → v1.4 is supported.
  • No version skipping: Skipping versions (for example v1.3 → v1.5) is not supported. While it might technically work, this upgrade path is not tested.
  • No downgrades: Downgrading Omni (for example v1.4 → v1.3) is not supported. Database migrations performed during an upgrade are typically irreversible. Attempting to downgrade will usually cause Omni to fail to start because the database schema is newer than the version being run, or it may lead to other unexpected behavior.
Pre-release versions: Alpha and beta releases are intended for testing only. Use them at your own risk, as they may introduce breaking changes that can affect your installation.

​
Preparation

Before upgrading, you must review the release notes for the version you are upgrading to. Release notes contain important information such as:
  • breaking changes
  • new required flags
  • configuration updates
  • migration instructions
Resources:

​
Example: Checking for breaking changes

Always review the Urgent Upgrade Notes section of the release notes. For example, when upgrading from v1.3 to v1.4, a new required flag (--sqlite-storage-path) was introduced. This flag does not have a default value. If a user upgraded without reading the release notes and adding this flag, Omni would fail to start.

​
Perform the Upgrade

After reviewing the release notes and confirming your configuration meets the requirements for the new version, you can perform the upgrade. Upgrading Omni simply involves updating the container image used by your deployment.

​
Update the Omni Image

Update the Omni image tag in your deployment configuration (for example compose.yaml or your docker run script) to the desired version. You can view available versions in the Omni container registry: https://github.com/siderolabs/omni/pkgs/container/omni After updating the image, restart the Omni container.

​
Update omnictl

It is strongly recommended to update omnictl to match the version of the Omni server. See Install and configure omnictl for instructions on updating the CLI tool.