Skip to main content

Upgrade from Embedded Cluster v2

This page describes how to upgrade from Embedded Cluster v2 to Embedded Cluster v3.

It includes information about how to update your application release to support Embedded Cluster v3. It also describes how to upgrade existing installations from Embedded Cluster v2 to v3.

Benefits of Embedded Cluster v3​

Embedded Cluster v3 delivers the following improvements over v2. For the release changes required to adopt them, see Comparison to Embedded Cluster v2.

One guided experience from the first step. In v2, cluster infrastructure was set up on the command line before a separate UI handled the application. In v3, a single binary drives cluster configuration, preflight checks, node setup, and application deployment in one wizard. See Embedded Cluster overview.

A smaller footprint for customers to secure. The cluster runs your application and Embedded Cluster's own infrastructure components, with no Replicated management component holding cluster-scoped privileges. The KOTS operator's cluster-scoped RBAC grants and cross-namespace access are not part of a v3 install, which takes them out of a customer's security review. The installer wizard and the admin console are served by a system service on the host, not by a component running in the cluster. See Removal of KOTS.

Installs no longer reach out to chart repositories. v3 resolves every Helm extension from a .tgz archive bundled in the release instead of pulling it from an HTTP repository or OCI registry at install time. Installs no longer depend on the customer's network reaching those hosts. See Helm extension charts must be bundled in the release.

Private image pulls work for pods you don't control. In v2, the Replicated pull secret had to be injected into every Pod definition that referenced a proxied image, which meant pods created at runtime by an operator, a Job, or a third-party subchart would fail to pull unless you threaded the secret through. v3 configures the cluster to authenticate to the Replicated proxy registry for all pods, so this is handled regardless of what creates the pod. See Automatic authentication to the Replicated proxy registry.

Support for customer-controlled registries. The cluster can pull every image, your application and the infrastructure components alike, from a single OCI registry that the customer operates. See Install with a customer-managed registry.

The full lifecycle can be automated. Install, upgrade, and node join each run from the CLI or the Embedded Cluster API with no console interaction. See Install using the CLI (Headless) and Upgrade using the CLI (headless).

Changes for end users​

You can adapt these lists for your own customer communications.

During the upgrade from v2​

These apply once, when an existing v2 installation moves to v3.

Customers won't see the v3 release in their Admin Console. Releases that use Embedded Cluster v3 don't appear as available updates in the Embedded Cluster v2 KOTS Admin Console. This is by design, to prevent accidental upgrades. To get the v3 release, customers use the Enterprise Portal or download the binary directly. If customers get releases from your own distribution portal, see One-time upgrade from Embedded Cluster v2 to v3 in Headless Enterprise Portal: Vendor API. Plan to communicate this when you promote a v3-enabled release.

The upgrade is one-way and asks for confirmation. The v3 binary detects the existing v2 installation and prompts the user to confirm before it proceeds. There's no path back to v2.

Configuration carries forward. Values the customer already set, such as the application domain, are preserved, so nothing has to be re-entered.

Backup settings carry forward, but backups taken on v2 can't be restored on v3. Starting in Embedded Cluster 3.18.0-beta.1, if the customer configured backups in v2, the upgrade keeps the backup storage location, schedule, and retention period, so backups continue to the same destination. Backups taken on v2 stay in the backup location until their v2 retention period ends, but the admin console doesn't list them, and Embedded Cluster v3 can't restore them. The upgrade itself is one-way, but if the customer needs to return to v2, they can restore one of these backups on a new machine with Embedded Cluster v2. See Restore from a backup in Disaster recovery for Embedded Cluster. So that the newest v2 backup matches the cluster as it was just before the upgrade, tell customers with backups configured to take one in the v2 Admin Console immediately before they upgrade. See Configure backup storage and take backups in the Admin Console in Disaster recovery for Embedded Cluster. When the upgrade finishes, the wizard prompts the user to create a new backup, which becomes the first recovery point on v3. Tell customers to create it right away, because until they do, they have no backup they can restore. If the upgrade can't read the v2 backup settings, it warns the user and asks whether to continue, and the user then configures backups in the admin console after the upgrade. See Backups after an upgrade from Embedded Cluster v2 in Back up and restore Embedded Cluster v3.

Customers more than one Kubernetes minor version behind need an intermediate release first. Kubernetes supports upgrading only one minor version at a time, and Embedded Cluster blocks an upgrade that would skip one. See Increase the Kubernetes minor version for how to lead customers through the versions in order.

Hosts on cgroup v1 must switch to cgroup v2 before the upgrade. Current Embedded Cluster v3 versions run Kubernetes 1.35 or later, which requires cgroup v2. Because Kubernetes can't skip minor versions, the upgrade from v2 always passes through 1.35, so this applies whichever v3 version the customer upgrades to. RHEL 8 and other Enterprise Linux 8 distributions use cgroup v1 by default. Customers on those hosts must switch every node to cgroup v2 and reboot before they upgrade to any release that runs Kubernetes 1.35 or later, including an intermediate Embedded Cluster v2 release. Embedded Cluster v2 runs on either cgroup version, so the switch can happen ahead of time. If a host is still on cgroup v1 when the upgrade starts, the host preflight checks fail partway through, after the upgrade can no longer be undone. See cgroup v2 in Embedded Cluster installation requirements.

Multi-node clusters upgrade the remaining nodes manually, this one time. Streamed upgrades require every remote node to already be running Embedded Cluster 3.2 or later, and nodes still on v2 do not qualify. The wizard detects this and displays manual instructions for those nodes. The user runs the displayed commands on each remaining node to download the upgrade bundle from the primary controller, extract it, and run node upgrade. Once every node is on v3, later upgrades stream automatically with no copying. See create-upgrade-bundle and node upgrade.

v3 reuses the v2 Admin Console port. Embedded Cluster v3 serves the installer UI, the admin console, and the API that other nodes use to join and receive upgrades on one port. After the upgrade from v2, that port is the one the v2 Admin Console used, which is 30000/TCP by default. For multi-node clusters, the port must also be open between nodes. See Port requirements.

On any v3 installation​

These are the ongoing differences after the upgrade.

A guided wizard handles install and upgrade. Install and upgrade operations launch a wizard that walks the user through configuration, preflight checks, node setup, and deployment, then hands off to the admin console when the operation finishes. It replaces the KOTS Admin Console that handled these steps in v2.

An always-on console is available. The admin console gives end users a browser dashboard without command-line access. From it they can see available updates, view release notes, trigger an upgrade, upload air gap releases, and generate support bundles. It is available automatically after installation. The initial install requires command-line access.

Customers find updates in the admin console. Available updates appear in the admin console. Customers can also get updates from the Enterprise Portal or by running the upgrade command directly. See Perform updates in embedded clusters.

Multi-node clusters upgrade themselves one node at a time. The user runs the upgrade on the primary controller, and its daemon streams the upgrade to each remaining node over the network. Controllers upgrade first, one at a time to preserve etcd quorum, then workers. Nobody copies files between machines or runs commands on the other nodes. If a node can't be reached, or is running a version that predates streamed upgrades, the wizard reports it and shows manual instructions for that node. See Multi-node clusters.

Cluster settings are collected in the wizard. The v3 wizard includes a Set Up page where end users provide cluster-level settings such as proxy configuration. In v2 these were passed as CLI flags at install time.

Comparison to Embedded Cluster v2​

This section describes the key differences between Embedded Cluster v2 and v3.

Removal of KOTS​

Embedded Cluster v3 removes Replicated KOTS from the architecture. This reduces the number of dependencies that are running in the cluster, which improves reliability.

The KOTS CLI does not work with Embedded Cluster v3, and there is no KOTS Admin Console. Embedded Cluster v3 replaces it with two interfaces:

  • A guided install and upgrade UI that walks end users through configuration, preflight checks, node setup, and application deployment. This UI launches automatically during install and upgrade operations. See Set up the wizard's Configure screen.
  • An admin console that provides an always-on web dashboard for browser-driven upgrades, air gap release uploads, and support bundle generation without SSH access.

Embedded Cluster v3 still requires the Replicated HelmChart v2 custom resource to process and deploy Helm charts. Embedded Cluster v3 also still uses Replicated custom resources like the Replicated Application and Replicated Config resources to define aspects of the installation experience.

Replicated SDK required for instance status reporting​

Because Embedded Cluster v3 removes KOTS, you must include the Replicated SDK in your application for application status informers to report instance status to the Vendor Portal.

Continue to configure status informers in the Replicated Application custom resource. Embedded Cluster v3 passes them to the SDK. For more information, see Enable and understand application status.

Application preflight specs must use v1beta3​

Application preflight checks must use API version troubleshoot.sh/v1beta3. Embedded Cluster v3 does not support v1beta2 application preflight specs.

In v3, you can package preflight specs inside your Helm charts or as a release-level YAML file. Embedded Cluster renders the spec through the Helm template engine at install time, giving your preflight spec access to the full Helm rendering context, including chart values, defaults, and helper functions. Because Embedded Cluster renders the spec through Helm, the spec uses Helm template syntax (not repl{{ }} Replicated template syntax).

v1beta3 supports this model because it treats the spec as Helm template YAML rather than a static Kubernetes resource.

note

You do not need to migrate host preflight, support bundle, or Redactor specs. The v1beta3 requirement applies only to the Preflight custom resource. HostPreflight, SupportBundle, and Redactor specs continue to work with v1beta2 in Embedded Cluster v3. There is no v1beta3 version of the HostPreflight custom resource. For more information about host preflight checks, see Embedded Cluster host preflight checks. For more information about where redactors live in v3, see Add custom redactors.

Key differences from v1beta2 for application preflight specs:

  • The spec can live inside a labeled Secret or ConfigMap in your Helm chart (Embedded Cluster 3.18.0-beta.1 and later), or at the release level.
  • The spec uses Helm template syntax ({{ .Values.something }}, {{ include "helper" . }}) instead of repl{{ }} Replicated template syntax.
  • The spec is not valid YAML before rendering. Standard YAML linters will not work on it directly.
  • For release-level specs with multiple Helm charts, you can use {{ if eq .Chart.Name "my-chart" }} conditionals to gate specific collectors or analyzers to the chart they belong to. Embedded Cluster renders the spec one time per chart in the release, each time in that chart's context. Chart-packaged specs already render in their own chart's context.
  • The connectivity collectors (http, postgres, mysql, mssql, redis, and clickhouse) run wherever the preflight process runs, which is the host in Embedded Cluster v3, rather than inside the cluster as they did under KOTS. To run these checks from within the cluster, wrap them in a runPod collector. See Run connectivity checks inside the cluster.
  • For air gap installations, images referenced by the preflight spec (such as the Troubleshoot image used to run checks inside the cluster) are not automatically included in the air gap bundle and must be added to the Application additionalImages field. See Include preflight images in air gap bundles.

For details about the rendering pipeline and multi-chart examples, see Add preflight checks. For more information about the v1beta3 spec format, see v1beta3 overview in the Troubleshoot documentation.

Package your application with Helm​

To use Embedded Cluster v3, package your application as one or more Helm charts. Embedded Cluster v3 does not support Kustomize or Kubernetes manifests.

HelmChart v2 required​

Embedded Cluster v3 supports only HelmChart v2 (kots.io/v1beta2). Extension charts defined in the Embedded Cluster Config do not need a separate HelmChart custom resource.

HelmChart v1 (kots.io/v1beta1) is a deprecated format from KOTS versions earlier than v1.99.0. If your releases already use HelmChart v2, including any release built for Embedded Cluster v3 or the Helm CLI, no action is required.

If your releases still use HelmChart v1, migrate to HelmChart v2 on Embedded Cluster v2 before you upgrade any customer to Embedded Cluster v3. For more information, see Migrate existing installations to HelmChart v2.

Helm extension charts must be bundled in the release​

In Embedded Cluster v2, Helm extensions defined under extensions.helm.charts were pulled at install time from an HTTP Helm repository or an OCI registry, based on the chartname and version fields (and any repositories listed under extensions.helm.repositories).

Embedded Cluster v3 does not pull extension charts at install time from any source, whether an HTTP Helm repository or an OCI registry. Instead, it resolves each extension chart from a .tgz chart archive that is bundled in the release, matching by chart name and version. The v3 extensions.helmCharts schema has no repository or registry field.

As a result, upgrading a repo-sourced or OCI-sourced v2 extension is not only a change to the Config YAML shape. You must also package the chart as a .tgz archive and include it in the release. For the steps, see Update your release to Embedded Cluster v3 below.

Automatic authentication to the Replicated proxy registry​

If your application uses the Replicated proxy registry, Embedded Cluster v3 configures the cluster to automatically authenticate to the proxy registry for all pods. This means that it's no longer necessary to manually inject a Replicated pull secret using the ImagePullSecretName template function.

Templates read only the config items in the current release​

In Embedded Cluster v3, templates read config values only for items defined in the release's Config custom resource. This keeps your application's behavior tied to the configuration that end customers can see and change.

In Embedded Cluster v2, the value saved for a config item stayed on the installation after you removed the item from your Config, and templates continued to read it. Because the Admin Console config page shows only the items in the current Config, a removed item could keep turning parts of your application on or off with no way for the end customer to see or change it. For example, repl{{ ConfigOptionEquals "nats.enabled" "1" }} kept evaluating to true on any installation that had saved 1 for nats.enabled before the item was removed.

If your release still references config items that you removed, those templates render differently after the upgrade to v3. A reference to an item that the Config custom resource does not define resolves to an empty string, and ConfigOptionEquals evaluates to false. In the statusInformers field of the Application custom resource, the install or upgrade still succeeds, but the informer is dropped and the Replicated SDK does not report status for that resource. If every informer is dropped, the application status at the end of the install wizard and in the admin console reports that the application did not provide resources to verify.

Before you upgrade, remove or update any template references to config items that your Config custom resource no longer defines.

Repeatable config items aren't supported​

Embedded Cluster v3 doesn't support repeatable config items. Releases that use them aren't rejected. Instead, Embedded Cluster v3 ignores the repeatable, valuesByGroup, and templates fields, so it doesn't create a copy of the template target for each entry, and the ConfigOptionIndex template function returns an empty string.

If your application depends on repeatable items, contact your Replicated account team before you upgrade installations to Embedded Cluster v3.

Changes to Application custom resource fields​

Because Embedded Cluster v3 removes the KOTS Admin Console, several fields in the Application custom resource no longer have a meaningful equivalent in v3. These fields can be safely removed from your Application manifest during the upgrade. If left in place, they are silently ignored.

The following Application spec fields are not used in Embedded Cluster v3:

FieldPurpose in Embedded Cluster v2 (KOTS)
allowRollbackEnabled the rollback button in the Admin Console
graphsDisplayed Prometheus metric graphs in the Admin Console
minKotsVersion / targetKotsVersionGated installations to specific KOTS versions
requireMinimalRBACPrivileges / supportMinimalRBACPrivilegesControlled KOTS operator RBAC mode
consoleFeatureFlagsEnabled feature flags in the Admin Console UI
portsConfigured KOTS port forwarding and dashboard link rewriting. See Application access and links.

The following Application spec fields are still used in Embedded Cluster v3:

FieldHow it is used in Embedded Cluster v3
titleDisplayed in the Embedded Cluster install and upgrade wizard header. See Customize the wizard branding.
iconDisplayed next to the title in the wizard. For air gap installations, use a Base64 encoded image since remote URLs are not accessible. See Customize the wizard branding.
releaseNotesUsed as the default release notes for the channel release when no notes are provided at promote time. See Include release notes.
additionalImagesImages listed here are included in air gap bundles, even if not directly referenced in Helm chart templates.
excludedImagesImages listed here are excluded from air gap bundles.
additionalNamespacesCreates the listed namespaces and provisions registry image pull secrets and, when a custom CA bundle is configured, the private CA ConfigMap in each. Embedded Cluster also provisions these resources in the application namespace and namespaces specified by HelmChart resources. Keep this field for other namespaces your application uses, such as those where an Operator creates workloads.
proxyPublicImagesEvaluated by the Vendor Portal when building the Embedded Cluster bundle to determine which public images can use the Replicated proxy registry. Embedded Cluster uses the resulting image metadata.
statusInformersInjected into the Replicated SDK Helm values for instance reporting in the Vendor Portal. Requires the Replicated SDK.

Embedded Cluster v3 does not use the KOTS Application spec.ports fields (serviceName, servicePort, localPort, or applicationUrl) to forward ports or rewrite application links. In KOTS, a descriptor link that matches ports.applicationUrl is rewritten to use the Admin Console browser hostname and localPort. In v3, the rendered descriptor URL is used as supplied.

To make your application accessible in v3:

  1. Expose it through your Helm chart. For example, use a NodePort Service and set spec.ports[].nodePort to 30888. Users can then access the application at http://<node-address>:30888. A ClusterIP Service alone does not expose the application outside the cluster. You can also use an Ingress with an ingress controller.
  2. Have customers allow the required traffic through their network and firewall.
  3. In the Kubernetes SIG Application custom resource (app.k8s.io/v1beta1), set the url field for each entry in spec.descriptor.links to an address users can reach. Because the hostname is not known when you create the release, use template functions to build the URL. For example, url: 'http://repl{{ ConfigOption "hostname" }}:30888', where hostname is an item in your Config custom resource. These links appear on both the Installation Complete page and the admin console dashboard. Adding a link does not expose the service.

Migration preserves the existing Application manifest, but links that relied on KOTS URL rewriting need to be updated. For example, replace a URL that matched ports.applicationUrl, such as http://nginx, with the application's reachable URL. If you already expose the service with a NodePort for Embedded Cluster v2, only the link needs to change. See Add application links to the Finish page.

Update your release to Embedded Cluster v3​

To update a release from Embedded Cluster v2 to v3:

  1. Remove any standalone Kubernetes manifests or kustomization.yaml files from your release. Embedded Cluster v3 only deploys resources defined in Helm charts. If you need to deploy any resources before Embedded Cluster deploys your application, you can use Helm chart extensions in the Embedded Cluster Config.

  2. In your application Helm chart Chart.yaml file, add the SDK as a dependency. With Embedded Cluster v3, you must include the SDK to get instance insights from status informers.

    If your application uses multiple charts, declare the SDK as a dependency of the chart that customers install first. Do not declare the SDK in more than one chart.

    # Chart.yaml
    dependencies:
    - name: replicated
      repository: oci://proxy.replicated.com/library
      version: 1.19.6

    For the latest version information for the Replicated SDK, see the replicated-sdk repository in GitHub.

  3. If you use the Replicated proxy registry, update your release to remove the ImagePullSecretName template function from your HelmChart values key. Embedded Cluster v3 configures the cluster to automatically authenticate to the proxy registry for all pods, so you don't need to manually inject a pull secret. See the Embedded Cluster v3 steps in Configure your application to use the proxy registry.

  4. If you support air gap installations on Embedded Cluster versions earlier than 3.16.0-beta.1, update your image references to use the Embedded Cluster ReplicatedImageName and ReplicatedImageRegistry template functions. This ensures that image references resolve correctly in both online and air gap installations. See Add support for air gap installations.

    note

    Embedded Cluster 3.16.0-beta.1 and later also support the KOTS template functions for local registry image references. ReplicatedImageName and ReplicatedImageRegistry remain available as alternatives. For more information about support in Embedded Cluster, see KOTS template functions in Template Functions for Embedded Cluster (Beta).

  5. Update your application preflight specs to API version troubleshoot.sh/v1beta3:

    • Change apiVersion from troubleshoot.sh/v1beta2 to troubleshoot.sh/v1beta3.
    • Preflight specs can remain in your Helm chart's templates/ directory, wrapped in a Secret or ConfigMap labeled troubleshoot.sh/kind: preflight with the spec under the preflight.yaml key. Change the API version of the Preflight spec inside the wrapper to troubleshoot.sh/v1beta3, because Embedded Cluster skips a wrapped spec that still uses v1beta2. Chart-packaged specs require Embedded Cluster 3.18.0-beta.1 or later.
    • If you use a release-level spec instead, keep it as a plain troubleshoot.sh/v1beta3 Preflight resource.
    • Replace any repl{{ }} Replicated template syntax with Helm template syntax. For example, use {{ .Values.image.tag }} instead of repl{{ ConfigOption "image_tag" }}.
    • You do not need to update the API version of support bundle or Redactor specs. They continue to work with v1beta2 in Embedded Cluster v3.

    Replicated recommends that every release use a single troubleshoot.sh/v1beta3 application preflight spec, packaged in a labeled Secret in your Helm chart. One spec then works with every installation method:

    • Embedded Cluster v3 requires v1beta3. Chart-packaged specs require 3.18.0-beta.1 or later. Earlier versions skip chart-packaged specs without an error, so use a release-level spec on those versions.
    • KOTS v1.134.0 and later runs v1beta3 specs. This includes Embedded Cluster v2 2.19.16 and later, and kURL installations with KOTS v1.134.0 or later.
    • Helm CLI installations run them with the Troubleshoot Preflight plugin (kubectl preflight) v0.123.0 or later.

    Don't include both a v1beta2 and a v1beta3 Preflight spec in the same release. KOTS v1.134.0 and later runs both, so checks appear twice. Don't expect KOTS versions earlier than v1.134.0 to run a v1beta3 spec. Customers on those versions need to upgrade KOTS.

    The v1beta3 requirement applies only to the Preflight custom resource. HostPreflight, SupportBundle, and Redactor specs continue to use v1beta2.

    If you also distribute your application with the Helm CLI, you can use the same labeled Secret in your chart without a separate release-level copy for Embedded Cluster 3.18.0-beta.1 and later. For more information, see Helm and troubleshoot template example.

    For more information about the v1beta3 migration, see Migrate from v1beta2 to v1beta3 in the Troubleshoot documentation.

  6. Ensure that your release has a corresponding HelmChart v2 custom resource for each of your application Helm charts. If your release uses HelmChart v1, complete the migration to HelmChart v2 on Embedded Cluster v2 first. See HelmChart v2 required. Extension charts defined in the Embedded Cluster Config do not need a separate HelmChart CR. See HelmChart v2.

  7. In your Embedded Cluster Config, update version to the latest version of Embedded Cluster v3. You can also optionally increment the Kubernetes version by one minor version.

    Replace EC_VERSION with the version to install, including the Kubernetes suffix. For example, 3.12.0-beta.1+k8s-1.36. Each entry in the Embedded Cluster v3 release notes lists the full version strings available for that release.

    Example:

    apiVersion: embeddedcluster.replicated.com/v1beta1
    kind: Config
    spec:
      version: EC_VERSION

  8. Update any existing Helm extensions to the v3 extensions.helmCharts format. See extensions.

    Because Embedded Cluster v3 resolves extension charts from bundled .tgz archives rather than pulling them from a repository or registry (see Helm extension charts must be bundled in the release), updating the Config YAML is not sufficient on its own. For each Helm extension you defined in v2:

    1. Pull the chart to a local .tgz archive at the version you want to install.

      For a chart hosted in an HTTP Helm repository (for example, a v2 chartname such as ingress-nginx/ingress-nginx):

      helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
      helm repo update
      helm pull ingress-nginx/ingress-nginx --version 4.11.3

      For a chart hosted in an OCI registry (for example, a v2 chartname such as oci://quay.io/jetstack/charts/cert-manager):

      helm pull oci://quay.io/jetstack/charts/cert-manager --version 1.19.2

    2. Add the resulting .tgz archive to your release.

    3. Reference the chart in the Embedded Cluster Config under extensions.helmCharts, using a chart.name and chart.chartVersion that match the packaged archive's Chart.yaml.

    Example Config:

    apiVersion: embeddedcluster.replicated.com/v1beta1
    kind: Config
    spec:
      extensions:
        helmCharts:
          - chart:
              name: ingress-nginx
              chartVersion: "4.11.3"
            releaseName: ingress-nginx
            namespace: ingress-nginx
            values:
              controller:
                service:
                  type: NodePort
                  nodePorts:
                    http: "80"
                    https: "443"
                image:
                  digest: ""
                  digestChroot: ""

  9. Promote the release to a development channel that you use for testing.

  10. In the VM where you plan to test the installation, create a firewall opening for port 30000/TCP. Embedded Cluster v3 serves the installer UI and admin console on port 30000 by default.

  11. Test the installation using a development customer.

Upgrade an installation from Embedded Cluster v2 to Embedded Cluster v3​

Embedded Cluster supports upgrading existing installations from v2 to v3 without having to reinstall the application. The upgrade uses the same upgrade command as any v3-to-v3 upgrade. The v3 binary automatically detects the v2 installation and handles the upgrade, prompting the user to confirm. Running install on a node with an existing v2 installation is blocked — use upgrade instead.

important

If your v3 release uses a newer Kubernetes minor version than the customer's v2 installation, the upgrade also upgrades Kubernetes. Kubernetes supports upgrading only one minor version at a time, so Embedded Cluster blocks the upgrade if the customer's Kubernetes version is more than one minor version behind the version in your v3 release.

To avoid this, ensure that customers step through the intermediate Kubernetes minor versions before they upgrade to v3. Replicated recommends that you mark each release that increases the Kubernetes minor version as required so that customers cannot skip it. For more information, see Increase the Kubernetes minor version.

To find out which of your customers are affected, check the Kubernetes version reported by each active instance on the Instances tab for the customer in the Vendor Portal. For more information, see Cluster status in Instance Details. Air gap instances report this data less frequently than online instances, so plan for air gap customers to be further behind than their last reported version shows.

note

Releases that use Embedded Cluster v3 will not appear as available updates in the Embedded Cluster v2 KOTS Admin Console. This is by design to prevent accidental upgrades. Your customers will need to get the v3 release from the Enterprise Portal or by downloading the binary directly. Plan to communicate this to your customer base when you promote a v3-enabled release.

To upgrade an existing installation to Embedded Cluster v3:

  1. Get the customer's Embedded Cluster install instructions from the Vendor Portal or from the Enterprise Portal.

  2. For application version, select the release that enables Embedded Cluster v3.

  3. SSH into the VM where the Embedded Cluster v2 installation is running.

  4. On the VM, run the commands to download and extract the installation assets for the target release. The installation assets include the Embedded Cluster binary, the license file, and the release assets.

  5. Run the following command to upgrade using the Embedded Cluster v3 upgrade wizard:

    sudo ./APP_SLUG upgrade --license license.yaml

    Where APP_SLUG in the unique application slug.

  6. When prompted, type yes to confirm that you want to upgrade to v3.

    Detected EC v2 installation. This will upgrade the cluster from v2 to v3.
    This is a one-way upgrade and cannot be undone.
    Do you want to proceed with the upgrade? (yes/NO): yes

  7. When the upgrade command completes, open the URL that it prints to access the upgrade wizard. For example:

    Open https://10.0.0.11:30000 to continue.

    You might see a browser warning for the self-signed certificate.

  8. Log in to the upgrade wizard using the existing password for the Admin Console.

    upgrade wizard log in screen

    View a larger version of this image

  9. Follow the steps in the wizard to upgrade any other nodes in the cluster, configure the application, and then deploy the application.

    upgrade wizard app upgrade screen

    View a larger version of this image

On this page