Skip to content

Build data is not used when determining instance sequence #3363

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 9, 2025
Merged

Build data is not used when determining instance sequence #3363

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
70f0916
Add info about how build data is not used when determining semver pre…
paigecalvert Jul 7, 2025
1d5a906
edits
paigecalvert Jul 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 42 additions & 1 deletion docs/enterprise/updating-app-manager.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ import ViewAirGapBundle from "../partials/install/_airgap-bundle-view-contents.m

This topic describes how to perform updates in existing cluster installations with Replicated KOTS. It includes information about how to update applications and the version of KOTS running in the cluster.

It also includes information about how the Admin Console determines version precendence. See [How the Admin Console Determines Version Precendence](/enterprise/updating-app-manager#how-the-admin-console-determines-version-precedence).

## Update an Application

You can perform an application update using the KOTS Admin Console or the KOTS CLI. You can also set up automatic updates. See [Configure Automatic Updates](/enterprise/updating-apps).
Expand Down Expand Up @@ -141,4 +143,43 @@ To update KOTS in an existing air gap cluster:
* `RO_PASSWORD` with the password associated with the username.
* `NAMESPACE` with the namespace on your cluster where KOTS is installed.

For help information, run `kubectl kots admin-console upgrade -h`.
For help information, run `kubectl kots admin-console upgrade -h`.

## How the Admin Console Determines Version Precedence
Copy link
Contributor Author

@paigecalvert paigecalvert Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ I decided to try out moving this info over to the Performing Updates with KOTS in Existing Clusters page (rather than in About Channels and Releases).
This info was feeling pretty specific to updating with kots/viewing the Admin Console version history page, and probably isn't something most people would be needing to read out in a high level overview of channels and releases

I linked to this section from a couple places, as you'll see below


The Admin Console uses version precedence to determine which versions are available for upgrade. Version precedence also determines the order in which versions are displayed on the **Version history** page, as shown in the example below:
Copy link
Contributor Author

@paigecalvert paigecalvert Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ added this explanation of what version precedence is/how it's used


![Admin console version history page](/images/new-version-available.png)
[View a larger version of this image](/images/new-version-available.png)

The Admin Console uses the following logic to determine version precendence:

* For channels _without_ semantic versioning (SemVer) enabled, the Admin Console sequences releases by their promotion dates and times. For example, if you promote a release with version label abc at 10:00am, and then promote a release with version label xyz at 10:15am, then version xyz has higher precedence (abc < xyz).

* For channels _with_ SemVer enabled, the Admin Console sequences releases by their semantic version. For information about how precedence is determined in SemVer, see [11.
Precedence refers to how versions are compared to each other when ordered](https://semver.org/#spec-item-11) in the Semantic Versioning 2.0.0 documentation.

The following shows an example of version precendence in SemVer when pre-release fields are used:

- 2.13.0
- 2.12.1
- 2.12.0
- 2.12.0-2
- 2.12.0-1
- 2.11.0

:::note
Build metadata in the semantic version string is ignored when determining version precedence. For example, the Admin Console interprets 2.12.0, 2.12.0+1, and 2.12.0+2 as the same version. Instead of using build metadata in your semantic version labels, Replicated recommends that you increment the patch version. Or, use pre-release identifiers. For example, 1.0.0-alpha or 1.0.0-1.
:::

* For channels with SemVer enabled where there are one or more releases that do _not_ use SemVer, the Admin Console determines precedence based on the semantic version when possible. The release(s) with non-semantic versions stay in the order of their promotion dates.

For example, assume that you promote these releases in the following order to a channel without SemVer enabled:

- 1.0.0 promoted at 10:00 AM
- abc promoted at 10:15 AM
- 0.1.0 promoted at 10:30 AM
- xyz promoted at 10:45 AM
- 2.0.0 promoted at 11:00 AM

Then, you enable SemVer on that channel. The Admin Console assigns precedence as follows: 0.1.0 < 1.0.0 < abc < xyz < 2.0.0.
99 changes: 38 additions & 61 deletions docs/vendor/releases-about.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Replicated includes the following channels by default:

You can archive or edit any of the default channels, and create new channels. For more information, see [Create and Edit Channels](releases-creating-channels).

### Settings
### Channel Settings

Each channel has settings. You can customize the settings for a channel to control some of the behavior of releases promoted to the channel.

Expand Down Expand Up @@ -74,7 +74,15 @@ Each release is promoted to one or more channels. While you are developing and t

A release cannot be edited after it is promoted to a channel. This means that you can test a release on an internal development channel, and know with confidence that the same release will be available to your customers when you promote it to a channel where real customers are assigned.

### Properties
### Demotion

A channel release can be demoted from a channel. When a channel release is demoted, the release is no longer available for download, but is not withdrawn from environments where it was already downloaded or installed.

The demoted release's channel sequence and version are not reused. For customers, the release will appear to have been skipped. Un-demoting a release will restore its place in the channel sequence making it again available for download and installation.

For information about how to demote a release, see [Demote a Release](/vendor/releases-creating-releases#demote-a-release) in _Managing Releases with the Vendor Portal_.

### Release Properties

Each release has properties. You define release properties when you promote a release to a channel. You can edit release properties at any time from the channel **Release History** page in the Vendor Portal. For more information, see [Edit Release Properties](releases-creating-releases#edit-release-properties) in _Managing Releases with the Vendor Portal_.

Expand All @@ -88,7 +96,7 @@ As shown in the screenshot above, the release has the following properties:

* **Version label**: The version label for the release. Version labels have the following requirements:

* If semantic versioning is enabled for the channel, you must use a valid semantic version. For more information, see [Semantic Versioning](#semantic-versioning).
* If semantic versioning is enabled for the channel, you must use a valid semantic version. For more information, see [About Using Semantic Versioning](#semantic-versioning).

<VersionLabelReqsHelm/>

Expand All @@ -100,92 +108,61 @@ As shown in the screenshot above, the release has the following properties:

* **Release notes (supports markdown)**: Detailed release notes for the release. The release notes support markdown and are shown to your customer.

### Sequencing
## About Using Semantic Versioning {#semantic-versioning}

By default, Replicated uses release sequence numbers to organize and order releases, and uses instance sequence numbers in an instance's internal version history.
Semantic Versioning (SemVer) is a commonly-used and recommended versioning strategy that provides implicit information about the backwards compatibility of each version, using the format MAJOR.MINOR.PATCH:

#### Release Sequences
![semver graphic](/images/semver-graphic.png)

In the Vendor Portal, each release is automatically assigned a unique, monotonically-increasing sequence number. You can use this number as a fallback to identify a promoted or draft release, if you do not set the `Version label` field during promotion. For more information, see [Manage Releases with the Vendor Portal](releases-creating-releases).
[View a larger version of this image](/images/semver-graphic.png)

The following graphic shows release sequence numbers in the Vendor Portal:
Using SemVer for your releases is recommended because it makes versioning more predictable for users. It also lets you enforce a consistent versioning pattern for your application in the Replicated Platform. For more information about SemVer, including how precendence is determined when comparing different versions, see [Semantic Versioning 2.0.0](https://semver.org).

<img alt="Release sequence numbers" src="/images/release-sequences.png" width="750px"/>
You can enable and disable SemVer for releases on each channel in the channel settings. When you enable SemVer on a channel, the Vendor Portal checks all releases promoted to that channel to verify that the version label is valid SemVer. For more information about how to enable SemVer on a channel, see [Enable Semantic Versioning](/vendor/releases-creating-channels#enable-semantic-versioning) in _Create and Edit Channels_.

[View a larger version of this image](/images/release-sequences.png)
When SemVer is enabled, the Admin Console uses the version labels that you assign to releases to determine release precedence. This is important because precedence controls which versions are available to customers for upgrade. It also determines how versions are ordered on the Admin Console **Version history** page. For more information, see [How the Admin Console Determines Version Precedence](/enterprise/updating-app-manager#how-the-admin-console-determines-version-precedence) in _Performing Updates in Existing Clusters_.
Copy link
Contributor Author

@paigecalvert paigecalvert Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ Added this paragraph to explain how enabling semver likely affects the version precedence on the Admin Console version history page, with a link to more info


#### Instance Sequences
## Release and Instance Sequencing

When a new version is available for upgrade, including when KOTS checks for upstream updates as well as when the user syncs their license or makes a config change, the KOTS Admin Console assigns a unique instance sequence number to that version. The instance sequence in the Admin Console starts at 0 and increments for each identifier that is returned when a new version is available.
The Vendor Portal uses release sequence numbers to organize and order releases. The Admin Console uses instance sequence numbers to organize and order an instance's internal version history.

This instance sequence is unrelated to the release sequence dispalyed in the Vendor Portal, and it is likely that the instance sequence will differ from the release sequence. Instance sequences are only tracked by KOTS instances, and the Vendor Portal has no knowledge of these numbers.
### Vendor Portal Release Sequence

The following graphic shows instance sequence numbers on the Admin Console dashboard:
In the Vendor Portal, each release is automatically assigned a unique, monotonically-increasing sequence number. You can use this number as a fallback to identify a promoted or draft release, if you do not set the `Version label` field during promotion. For more information, see [Manage Releases with the Vendor Portal](releases-creating-releases).

<img alt="Instance sequence numbers" src="/images/instance-sequences.png" width="550px"/>
The following graphic shows release sequence numbers in the Vendor Portal:

[View a larger version of this image](/images/instance-sequences.png)
<img alt="Release sequence numbers" src="/images/release-sequences.png" width="750px"/>

[View a larger version of this image](/images/release-sequences.png)

### Channel Sequence

#### Channel Sequences
When a release is promoted to a channel, a channel sequence number is assigned. This unique sequence number increments by one and tracks the order in which releases were promoted to a channel.

When a release is promoted to a channel, a channel sequence number is assigned. This unique sequence number increments by one and tracks the order in which releases were promoted to a channel. You can view the channel sequence on the **Release History** page in the Vendor Portal, as shown in the image below:
You can view the channel sequence on the **Release History** page in the Vendor Portal, as shown in the image below:

<img alt="Channel sequence on Release History page" src="/images/release-history-channel-sequence.png" width="750px"/>

[View a larger version of this image](/images/release-history-channel-sequence.png)

The channel sequence is also used in certain URLs. For example, a release with a *release sequence* of `170` can have a *channel sequence* of `125`. The air gap download URL for that release can contain `125` in the URL, even though the release sequence is `170`.

Ordering is more complex if some or all of the releases in a channel have a semantic version label and semantic versioning is enabled for the channel. For more information, see [Semantic Versioning Sequence](#semantic-versioning-sequence).
### Admin Console Instance Sequence

#### Semantic Versioning Sequence
When a new version is available for upgrade (including when KOTS checks for upstream updates, when the user syncs their license, or when the user makes a config change) the KOTS Admin Console assigns a unique instance sequence number to that version. The instance sequence number starts at 0 and increments for each identifier that is returned when a new version is available.

For channels with semantic versioning enabled, the Admin Console sequences instance releases by their semantic versions instead of their promotion dates.
The purpose of the instance sequence number is to help the user track all new versions across upstream updates, config changes, and license syncs. Without the instance sequence number, this could be challegning as the version label does not change when the user makes config changes or syncs their license.
Copy link
Contributor Author

@paigecalvert paigecalvert Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ added this paragraph to explain the purpose of instance sequence (curious for feedback as this is basically my own understanding)


If releases without a valid semantic version are already promoted to a channel, the Admin Console sorts the releases that do have semantic versions starting with the earliest version and proceeding to the latest. The releases with non-semantic versioning stay in the order of their promotion dates. For example, assume that you promote these releases in the following order to a channel:
The instance sequence number does _not_ reflect version precedence. The Admin Console determines version precedence based on either the release's version label (if semantic versioning is enabled) or based on the date and time the release was promoted (if semantic versioning is disabled). This is important because precedence controls which versions are available to customers for upgrade. It also determines how versions are ordered on the Admin Console **Version history** page. For more information, see [How the Admin Console Determines Version Precedence](/enterprise/updating-app-manager#how-the-admin-console-determines-version-precedence) in _Performing Updates in Existing Clusters_.
Copy link
Contributor Author

@paigecalvert paigecalvert Jul 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ added this paragraph to differentiate between instance sequence number and version precedence

It includes a link to more info about how version precedence is calculated


- 1.0.0
- abc
- 0.1.0
- xyz
- 2.0.0
The instance sequence in the Admin Console is unrelated to the release sequence in the Vendor Portal. Instance sequences are only tracked by KOTS instances, and the Vendor Portal has no knowledge of these numbers. It is also likely that the instance sequence number is different than the Vendor Portal release sequence.

Then, you enable semantic versioning on that channel. The Admin Console sequences the version history for the channel as follows:
The following shows instance sequence numbers on the Admin Console dashboard:

- 0.1.0
- 1.0.0
- abc
- xyz
- 2.0.0

### Semantic Versioning

Semantic versioning is available with the Replicated KOTS v1.58.0 and later. Note the following:

- For applications created in the Vendor Portal on or after February 23, 2022, semantic versioning is enabled by default on the Stable and Beta channels. Semantic versioning is disabled on the Unstable channel by default.

- For existing applications created before February 23, 2022, semantic versioning is disabled by default on all channels.

Semantic versioning is recommended because it makes versioning more predictable for users and lets you enforce versioning so that no one uses an incorrect version.

To use semantic versioning:

1. Enable semantic versioning on a channel, if it is not enabled by default. Click the **Edit channel settings** icon, and turn on the **Enable semantic versioning** toggle.
1. Assign a semantic version number when you promote a release.

Releases promoted to a channel with semantic versioning enabled are verified to ensure that the release version label is a valid semantic version. For more information about valid semantic versions, see [Semantic Versioning 2.0.0](https://semver.org).

If you enable semantic versioning for a channel and then promote releases to it, Replicated recommends that you do not later disable semantic versioning for that channel.

You can enable semantic versioning on a channel that already has releases promoted to it without semantic versioning. Any subsequently promoted releases must use semantic versioning. In this case, the channel will have releases with and without semantic version numbers. For information about how Replicated organizes these release sequences, see [Semantic Versioning Sequences](#semantic-versioning-sequence).

### Demotion

A channel release can be demoted from a channel. When a channel release is demoted, the release is no longer available for download, but is not withdrawn from environments where it was already downloaded or installed.

The demoted release's channel sequence and version are not reused. For customers, the release will appear to have been skipped. Un-demoting a release will restore its place in the channel sequence making it again available for download and installation.
<img alt="Instance sequence numbers" src="/images/instance-sequences.png" width="550px"/>

For information about how to demote a release, see [Demote a Release](/vendor/releases-creating-releases#demote-a-release) in _Managing Releases with the Vendor Portal_.
[View a larger version of this image](/images/instance-sequences.png)

## Vendor Portal Pages

Expand Down
24 changes: 23 additions & 1 deletion docs/vendor/releases-creating-channels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ To create a channel:

1. Click **Create Channel**.

## Edit a Channel
## Edit Channel Settings

To edit the settings of an existing channel:

Expand All @@ -39,6 +39,28 @@ To edit the settings of an existing channel:

For more information about channel settings, see [Settings](releases-about#settings) in _About Channels and Releases_.

## Enable Semantic Versioning

You can enable and disable semantic versioning (SemVer) for releases on each channel. When you enable SemVer on a channel, the Vendor Portal checks all releases promoted to that channel to verify that the version label is valid SemVer.

You can enable SemVer on a channel that already has releases promoted to it that do not use semantic versioning. Any subsequently promoted releases must use semantic versioning. In this case, the channel will have releases with and without semantic version numbers. For more information, see [About Using Semantic Versioning](/vendor/releases-about#semantic-versioning) in _About Channels and Releases_.

:::note
If you enable SemVer for a channel and then promote releases to it, Replicated recommends that you do _not_ later disable SemVer for that channel.
:::

To enable semantic versioning on a channel:

1. In the Vendor Portal, go to **Channels** and click the **Edit channel settings** icon.

The **Channel settings** dialog opens. For example:

<img src="/images/channel-settings.png" alt="Channel Settings dialog in the Vendor Portal" width="500"/>

1. Enable the **Enable semantic versioning** toggle.

The next time that you promote a release to the channel, assign the release a semantic version number.

## Archive a Channel

You can archive an existing channel to prevent any new releases from being promoted to the channel.
Expand Down
Binary file added static/images/semver-graphic.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.