Skip to content

edit limitations for ec about downgrading and skip upgrades #3880

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
paigecalvert merged 3 commits into from
Mar 13, 2026
Merged

edit limitations for ec about downgrading and skip upgrades #3880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
25e185a
edit limitations for ec about downgrading and skip upgrades
paigecalvert Mar 12, 2026
f0436ee
edits
paigecalvert Mar 12, 2026
f35560a
small edit
paigecalvert Mar 12, 2026
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
5 changes: 0 additions & 5 deletions docs/enterprise/updating-embedded.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
import UpdateAirGapAdm from "../partials/embedded-cluster/_update-air-gap-admin-console.mdx"
import UpdateAirGapCli from "../partials/embedded-cluster/_update-air-gap-cli.mdx"
import UpdateAirGapOverview from "../partials/embedded-cluster/_update-air-gap-overview.mdx"
import DoNotDowngrade from "../partials/embedded-cluster/_warning-do-not-downgrade.mdx"
import Overview from "../partials/embedded-cluster/_update-overview.mdx"

# Perform updates in embedded clusters
Expand All @@ -26,8 +25,6 @@ As shown in the diagram above, users check for available updates from the KOTS A

## Update in online clusters

<DoNotDowngrade/>

To perform an update with Embedded Cluster:

1. In the Admin Console, go to the **Version history** tab.
Expand Down Expand Up @@ -70,8 +67,6 @@ To perform an update with Embedded Cluster:

## Update in air gap clusters

<DoNotDowngrade/>

<UpdateAirGapOverview/>

### Upload the new version from the command line
Expand Down
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, 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_.
Don't downgrade the Embedded Cluster version or the Kubernetes version. Also, only increase the Kubernetes version by one minor version at a time. For more information, see [Limitations](/vendor/embedded-overview#ec-limitations) in _Embedded Cluster Overview_.
Copy link
Contributor Author

@paigecalvert paigecalvert Mar 12, 2026

Choose a reason for hiding this comment

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

this shows up in the Config reference page in the version section

:::
9 changes: 5 additions & 4 deletions docs/reference/embedded-config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The Embedded Cluster Config lets you define several aspects of the Kubernetes cl
apiVersion: embeddedcluster.replicated.com/v1beta1
kind: Config
spec:
version: 2.13.3+k8s-1.33
version: 2.14.0+k8s-1.34
roles:
controller:
name: app
Expand Down Expand Up @@ -69,11 +69,12 @@ spec:

## version

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 the versions of Embedded Cluster and Kubernetes to install. The version of Kubernetes is appended to the Embedded Cluster version in the format `+k8s-1.34`. For example, Embedded Cluster 2.14.0+k8s-1.34 uses Embedded Cluster 2.14.0 and Kubernetes 1.34.

Additionally, each version of Embedded Cluster also specifies a version of Kubernetes. For example, Embedded Cluster 2.6.0+k8s-1.31 uses Kubernetes 1.31, while 2.6.0+k8s-1.30 uses Kubernetes 1.30.
Each version of Embedded Cluster includes specific versions of components like KOTS (Admin Console) and OpenEBS.
For more information, see the [Embedded Cluster Release Notes](/release-notes/rn-embedded-cluster).

For a full list of versions, see the [Embedded Cluster Release Notes](/release-notes/rn-embedded-cluster). Replicated recommends that you update the version frequently to ensure that you are using the latest version of Embedded Cluster.
Replicated recommends that you update the version frequently to ensure that you are using the latest version of Embedded Cluster.
Copy link
Contributor Author

@paigecalvert paigecalvert Mar 12, 2026

Choose a reason for hiding this comment

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

made some semi-related edits to this section for clarity.


<DoNotDowngrade/>

Expand Down
6 changes: 3 additions & 3 deletions docs/vendor/embedded-overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ The built-in extensions installed by Embedded Cluster include:

* **(Air Gap Only) Image registry:** For air gap installations in environments with limited or no outbound internet access, Embedded Cluster installs an image registry where the images required to install and run the application are pushed. For more information about installing in air-gapped environments, see [Air Gap Installation with Embedded Cluster](/enterprise/installing-embedded-air-gap).

## Limitations
## Limitations {#ec-limitations}

Embedded Cluster has the following limitations:

Expand All @@ -161,9 +161,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 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.
* **Downgrading Embedded Cluster or Kubernetes not supported**: Embedded Cluster does not support downgrading the version of Embedded Cluster or Kubernetes. Only promote new releases that use the same or later versions of Embedded Cluster and Kubernetes.

* **Upgrading by more than one Kubernetes version at a time not supported**: Kubernetes does not support upgrading by more than one minor version 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 [Release Properties](/vendor/releases-about#release-properties) in _About Channels and Releases_.
* **Upgrading by more than one Kubernetes version at a time not supported**: Kubernetes does not support upgrading by more than one minor version at a time. To upgrade Kubernetes by more than one minor version, promote multiple releases, incrementing the version of Kubernetes by one minor version in each release.

* **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 [Replicated 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
Loading