Skip to content

don't skip minor versions of k8s during upgrades #3259

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 4 commits into from
May 16, 2025
Merged

don't skip minor versions of k8s during upgrades #3259

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e26fc57
don't skip minor versions of k8s during upgrades
paigecalvert May 15, 2025
d80d978
edits
paigecalvert May 15, 2025
883fb2e
edit
paigecalvert May 15, 2025
c9eaa96
edits
paigecalvert May 15, 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
2 changes: 1 addition & 1 deletion docs/partials/embedded-cluster/_warning-do-not-downgrade.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
:::important
Do not downgrade the Embedded Cluster version. This is not supported but is not prohibited, and it can lead to unexpected behavior.
Do not downgrade the Embedded Cluster version, downgrade the Kubernetes version, nor upgrade Kubernetes by more than one minor version at a time. These actions are not prevented by the Admin Console and can lead to unexpected behavior. For more information, see [Limitations](/vendor/embedded-overview#limitations) in _Embedded Cluster Overview_.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

^ updated this existing warning, which appears in the page on updating with EC, to include the info about how you also can't upgrade by more than one minor version

:::
10 changes: 8 additions & 2 deletions docs/reference/embedded-config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import DoNotDowngrade from "../partials/embedded-cluster/_warning-do-not-downgrade.mdx"

# Embedded Cluster Config

This topic is a reference for the Replicated Embedded Cluster Config custom resource. For more information about Embedded Cluster, see [Use Embedded Cluster](/vendor/embedded-overview).
Expand Down Expand Up @@ -67,9 +69,13 @@ spec:

## version

You must specify which version of Embedded Cluster to install. Each version of Embedded Cluster includes particular versions of components like KOTS (Admin Console) and OpenEBS.
Specify which version of Embedded Cluster to install. Each version of Embedded Cluster includes particular versions of components like KOTS (Admin Console) and OpenEBS.

Additionally, each version of Embedded Cluster also specifies a version of Kubernetes. For example, Embedded Cluster 2.1.3+k8s-1.30 uses Kubernetes 1.30, while 2.1.3+k8s-1.29 uses Kubernetes 1.29.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

^ added this paragraph


For a full list of versions, see the Embedded Cluster [releases page](https://github.com/replicatedhq/embedded-cluster/releases) in GitHub. Replicated recommends that you update the version frequently to ensure that you are using the latest version of Embedded Cluster.

For a full list of versions, see the Embedded Cluster [releases page](https://github.com/replicatedhq/embedded-cluster/releases) in GitHub. It's recommended to keep this version as up to date as possible because Embedded Cluster is changing rapidly.
<DoNotDowngrade/>
Copy link
Contributor Author

Choose a reason for hiding this comment

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

^ added the warning about how you can't downgrade or bump k8s by more than one minor version. This may or may not be overly "loud" for this page. Main idea was to make it easier for vendors to find these limitations when they might be checking the reference on bumping EC versions in their config.


## roles (Beta)

Expand Down
4 changes: 3 additions & 1 deletion docs/vendor/embedded-overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,9 @@ Embedded Cluster has the following limitations:

* **KOTS Auto-GitOps workflow not supported**: Embedded Cluster does not support the KOTS Auto-GitOps workflow. If an end-user is interested in GitOps, consider the Helm install method instead. For more information, see [Install with Helm](/vendor/install-with-helm).

* **Downgrading Kubernetes not supported**: Embedded Cluster does not support downgrading Kubernetes. The admin console will not prevent end-users from attempting to downgrade Kubernetes if a more recent version of your application specifies a previous Embedded Cluster version. You must ensure that you do not promote new versions with previous Embedded Cluster versions.
* **Downgrading Embedded Cluster or Kubernetes not supported**: Downgrading the versions of Embedded Cluster or Kubernetes that are installed in the cluster is not supported. However, the Admin Console does not prevent end-users from attempting to downgrade Emebdded Cluster or Kubernetes. To avoid issues in customer installations that could be caused by downgrading, do not promote new application releases with Embedded Cluster or Kubernetes versions that are earlier than the versions used by the previous release.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

^ updated to explain how you can't downgrade either version

Also some rewording for clarity


* **Upgrading by more than one Kubernetes version at a time not supported**: Embedded Cluster does not support upgrading by more than one minor version of Kubernetes at a time. However, the Admin Console does not prevent end-users from attempting to upgrade to a release that specifies a Kubernetes version more than one minor version later than what is currently installed. To avoid issues that could be caused by skipping a minor version of Kubernetes, Replicated recommends that you select **Prevent this release from being skipped during upgrades** when you promote a new application release that increases the Kubernetes version. For more information about required releases, see [Properties](/vendor/releases-about#properties) in _About Channels and Releases_.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

^ new limitation

Copy link
Member

Choose a reason for hiding this comment

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

kubernetes itself doesn't support being upgraded by more than one version at a time. saying that instead of EC might make this look like an inherited limitation rather than one we put on the product ourselves.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

ah yeah, I see what you mean. I'll rephrase so that's clearer


* **Templating not supported in Embedded Cluster Config**: The [Embedded Cluster Config](/reference/embedded-config) resource does not support the use of Go template functions, including [KOTS template functions](/reference/template-functions-about). This only applies to the Embedded Cluster Config. You can still use template functions in the rest of your release as usual.

Expand Down