# 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](/vendor/replicated-sdk-overview) 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](https://troubleshoot.sh/docs/preflight/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: 1. 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`](embedded-config#extensions) in the Embedded Cluster Config. 1. 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. ```yaml # Chart.yaml dependencies: - name: replicated repository: oci://registry.replicated.com/library version: 1.19.1 ``` For the latest version information for the Replicated SDK, see the [replicated-sdk repository](https://github.com/replicatedhq/replicated-sdk/releases) in GitHub. 1. Update your application Preflight specs to API version `troubleshoot.sh/v1beta3`. For more information, see [Migrate from v1beta2 to v1beta3](https://troubleshoot.sh/docs/preflight/v1beta3-migration) in the Troubleshoot documentation. 1. 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](/vendor/helm-native-v2-using). For information about how to migrate from HelmChart v1 or Kubernetes manifests to HelmChart v2, see [Migrate existing installations to HelmChart v2](/vendor/helm-v2-migrate). 1. 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:** ```yaml apiVersion: embeddedcluster.replicated.com/v1beta1 kind: Config spec: version: 3.0.0-alpha-31+k8s-1.34 ``` 1. Update any existing Helm extensions to use the `extensions.helmChart` format. See [`extensions`](embedded-config#extensions). **Example:** ```yaml 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: "" ``` 1. Promote the release to a development channel that you use for testing. 1. 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: 1. Get the customer's Embedded Cluster install instructions from the Vendor Portal or from the Enterprise Portal. 1. For application version, select the release that enables Embedded Cluster v3. 1. SSH into the VM where the Embedded Cluster v2 installation is running. 1. 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. 1. Run the following command to upgrade using the Embedded Cluster v3 upgrade wizard: ```bash sudo ./APP_SLUG upgrade --license license.yaml ``` Where `APP_SLUG` in the unique application slug. 1. When prompted, type `yes` to confirm that you want to migrate to v3. ```bash 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 ``` 1. When the upgrade command completes, go to the URL provided to access the upgrade wizard. ```bash 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. ``` 1. Log in to the upgrade wizard using the existing password for the Admin Console. ![upgrade wizard log in screen](/images/embedded-cluster-v3-slackernews-upgrade-wizard.png) [View a larger version of this image](/images/embedded-cluster-v3-slackernews-upgrade-wizard.png) 1. 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](/images/embedded-cluster-v3-slackernews-upgrade-progress.png) [View a larger version of this image](/images/embedded-cluster-v3-slackernews-upgrade-progress.png) 1. Press Ctrl+C when the upgrade is complete to close the wizard.