In the world of enterprise customer-managed software your end customers will likely be on various versions of your software at any given time given different deployment cadences and processes. As such, it’s considered an enterprise software design best practice to support upgrading your customer from any prior version to any newer version, to enable their ability to accelerate adoption of the latest versions of your software as upgrade cycles allow.
It’s not always feasible for you to support a multitude of potential upgrade paths, whether due to a breaking change between minor versions, or a required database migration to enable new end user capabilities. In these cases you will likely want to make a given version in the customer’s upgrade path “required”, or unable to be skipped. This is a supported capability in the Replicated Platform.
Let’s break down what marking a release as “required” really means for your end customer across the broader Replicated Platform features.
How to make a release version required
Every release has editable release properties where you can set/change version labels, release notes, and more. Within a given release you have the option to select the checkbox “Prevent this release from being skipped during upgrades”, which will set the release as “required” in the Replicated Platform. Docs on how to edit release properties in Vendor Portal.
What does a required release look like to the customer in Enterprise Portal
When your customer goes to their customer-specific Enterprise Portal they will see a list of installable releases that you have made available to them. If you have made one or more of these releases required, then this will be indicated next to the version(s) in the app version list.
If this is a new install, where the Enterprise Portal does not know of any existing install versions of the app, then the list allows any version to be selected.
If this is an upgrade, and the Enterprise Portal has awareness of the currently installed version, the end customer will be unable to select anything newer than the required version if they are on an earlier version now. Once the end customer has upgraded to the required version, any newer versions become available (up until any additionally required versions).
While the Enterprise Portal can help direct end customers towards necessary required versions, the actual enforcement of this requirement at the point of install is dependent on the installation method used.
Embedded Cluster Installation
Within the Embedded Cluster Admin UI, end customers will see the newer application versions to install that have been made available to them in their respective distribution channel. If one or more of these newer application versions has been marked as a “required” release by you as the software provider, then the Admin UI shows the “deploy” button as unselectable on any versions newer than the required version, and offers a tooltip that says you must install {required version number} first. Once that required version is deployed, the newer versions will become deploy selectable in the Admin UI.
The behavior in air gap installs/upgrades is similar. You upload the bundle and it becomes available in the new versions list, however the option to deploy will be unselectable until any previously required version requirements are met.
For any Embedded Cluster version 2.10.0 or later, in an online installation the Admin Console will refetch metadata of any not-yet deployed releases. This means that if you toggle a previously required release as no longer required in Vendor Portal, or vice versa, the Admin Console will update that information as long as the end customer has not yet deployed that version.
KOTS Existing Cluster Installation
The behavior of online and air gap KOTS existing cluster installs matches the behavior described above. Additionally, KOTS will also refetch the release metadata as noted above as of version 1.126.0.
Helm CLI Installation
Due to the Helm CLI installation method being a common open-source tooling standard, there is currently no way to enforce the concept of a required version if a release is marked as such in Vendor Portal. If an end customer pulls version images past the point of a required release nothing is stopping them in Helm from attempting an installation. Your best course of action in this installation type is to make use of the Enterprise Portal with these customers. When marked as “required” the Enterprise Portal will customize the release availability list to guide the end customer through the right release version install/upgrade order.
Additional considerations for making a release required
Required releases has some of the following limitations (updated as of Sept 18, 2025)
-
After users deploy a required version, they can no longer redeploy (roll back to) versions earlier than the required version, even if
allowRollbackis true in the Application custom resource manifest. For more information, see allowRollback in the Application custom resource topic in the product docs. (Applicable for Embedded Cluster and KOTS Installs) -
If you change the channel an existing customer is assigned to, the Admin UI always fetches the latest release on the new channel, regardless of any required releases on the channel. For more information, see Channel Assignment in About Customers in the product docs. (Applicable for Embedded Cluster and KOTS Installs)
-
For installations using KOTS 1.125.2 or earlier, or Embedded Cluster 1.8.0 or earlier, if you disable the Prevent this release from being skipped during upgrades option for a promoted release, the release will still be marked as required in the Admin Console and users must still upgrade to the given version before they can upgrade to later versions.