Migrate from Embedded Cluster v2

This page describes how to migrate 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.

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 still requires the KOTS HelmChart v2 custom resource to process and deploy Helm charts. Embedded Cluster v3 also still uses KOTS custom resources like the KOTS Application and KOTS Config resources to define aspects of the installation experience.

Replicated SDK required for application status informers

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

Troubleshoot Preflight `v1beta3` required

Application preflight checks must use Troubleshoot v1beta3. v1beta2 preflight specs are not supported.

For more information, see v1beta3 overview in the Troubleshoot documentation.

HelmChart v2 required

Embedded Cluster v3 supports installing Helm charts with a corresponding HelmChart v2 custom resource (API version v1beta2).

Embedded Cluster v3 does not support Kustomize, Kubernetes manifests, or HelmChart v1.

Update your release to Embedded Cluster v3

To update your release to support installation with Embedded Cluster v3:

Remove any standalone Kubernetes manifests or kustomization.yaml files from your release. Embedded Cluster v3 only deploys resources that are managed by 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.
In your application Helm chart Chart.yaml file, add the SDK as a dependency. With Embedded Cluster v3, the SDK is required to get instance insights from status informers.

If your application is installed as 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://registry.replicated.com/library
  version: 1.18.2
```
For the latest version information for the Replicated SDK, see the replicated-sdk repository in GitHub.
Update your application Preflight specs to API version troubleshoot.sh/v1beta3. For more information, see Migrate from v1beta2 to v1beta3 in the Troubleshoot documentation.
Ensure that your release has a corresponding HelmChart v2 custom resource for each of your Helm charts. For information about how to configure the HelmChart v2 custom resource, see Support installations with HelmChart v2. For information about how to migrate from HelmChart v1 or Kubernetes manifests to HelmChart v2, see Migrate existing installations to HelmChart v2.
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.

Example:
```
apiVersion: embeddedcluster.replicated.com/v1beta1
kind: Config
spec:
  version: 3.0.0-alpha-31+k8s-1.34
```

Update any existing Helm extensions to use the extensions.helmChart format. See extensions.

Example:

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: ""

Promote the release to a development channel that you use for testing.
Test the installation using a development customer.

Migrate 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.

To migrate an existing installation to Embedded Cluster v3:

Get the customer's Embedded Cluster install instructions from the Vendor Portal or from the Enterprise Portal.
For application version, select the release that enables Embedded Cluster v3.
SSH into the VM where the Embedded Cluster v2 installation is running.
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.
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.

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

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

When the upgrade command completes, go to the URL provided to access the upgrade wizard.

Installation started. Connect to the web interface to continue the installation.

Open the following URL in your browser:

https://kotsadm.default.svc.cluster.local:30080

Note: You may see a browser warning for the self-signed certificate.
Click "Advanced" > "Proceed" to continue.

Press Ctrl+C when the installation is complete to stop the web interface.

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

View a larger version of this image
Follow the steps in the wizard to upgrade any other nodes in the cluster, configure the application, and then deploy the application.

View a larger version of this image
Press Ctrl+C when the upgrade is complete to close the wizard.

Comparison to Embedded Cluster v2​

Removal of KOTS​

Replicated SDK required for application status informers​

Troubleshoot Preflight v1beta3 required​

HelmChart v2 required​

Update your release to Embedded Cluster v3​

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

On this page