# Perform updates in embedded clusters (Beta)

This topic describes how to upgrade, redeploy, or reconfigure an application installed with Replicated Embedded Cluster 3.x. For an introduction to Embedded Cluster, see [Embedded Cluster overview](embedded-overview).

## Overview

Each Embedded Cluster binary that you download targets a particular application version. Running `install` or `upgrade` with that binary installs or upgrades to that version. Upgrades can update both your application and cluster infrastructure (including Kubernetes and Embedded Cluster components), depending on what changed in the release.

You can upgrade interactively in the browser or headlessly from the command line. To change configuration or redeploy without moving to a newer application version, run `upgrade` using the binary for the version that is already installed.

## Upgrade using the Embedded Cluster UI

### Use the Enterprise Portal for a guided upgrade

To use the guided upgrade experience in the Enterprise Portal:

1. Log in to the [Replicated Enterprise Portal](/vendor/enterprise-portal-about) with a user for your test customer.

1. Open the **Update** tab and follow the instructions to upgrade the instance.

### Upgrade using the instructions in the Vendor Portal

To upgrade more directly from the Vendor Portal:

1. In the [Vendor Portal](https://vendor.replicated.com), open the **Customers** page and select a customer that you assigned to the channel you use for testing.

1. At the top of the customer page, click **Install instructions** and select **Embedded Cluster**. (The control may appear as **Embedded Cluster install instructions**.)

   :::note
   You can also open the Enterprise Portal to get install and upgrade instructions.
   :::

1. In the **Select a version** section (or equivalent), choose the application version to upgrade to.

1. On a Linux machine, run the first two commands from the dialog (download the archive, then extract it).

1. For the third command, use `upgrade` instead of `install`, then run the command. For example:

   ```bash
   sudo ./APP_SLUG upgrade --license LICENSE_FILE
   ```

   Replace `APP_SLUG` with your application slug and `LICENSE_FILE` with the path to the license file. Add any other flags you use for this environment. For the full set of flags, see [upgrade](embedded-cluster-upgrade).

1. When prompted, enter the password you set during installation to log in to the installer. To set a different password for the installer, use the `--installer-password` flag.

1. On the **Configure** page, change any application configuration you need.

1. On the **Upgrade** page, start the upgrade and wait for it to finish.

1. On the **Finish** page, confirm completion. Use the provided links to open your application if needed.

### From the persistent admin console

If the [persistent admin console](embedded-persistent-console) is installed on a controller, end users can upgrade from the browser without SSH access to the controller:

1. Open the console at `https://<controller-hostname>:30080/console` and log in with the installer password.

1. In the **Available updates** section, locate the target version and click **Upgrade**.

   The dashboard handles the fetch, prepare, restart, and binary swap, then redirects into the upgrade wizard.

1. On the **Configure** page, change any application configuration you need.

1. On the **Upgrade** page, start the upgrade and wait for it to finish.

1. On the **Finish** page, confirm completion. This redirects back to the dashboard page.

The persistent admin console is not enabled by default. For setup instructions, see [Persistent admin console](embedded-persistent-console).

## Upgrade using the CLI (headless)

To perform a headless upgrade from the CLI:

1. In the Vendor Portal, open the **Customers** page and select the target customer.

1. At the top of the customer page, click **Install instructions** and select **Embedded Cluster**. (The label might also appear as **Embedded Cluster install instructions**).

1. In the **Select a version** section, choose the application version to upgrade to.

1. On a Linux machine, run the first two commands from the dialog to download the archive and extract it.

1. For the third command, do the following:

   * Use `upgrade` instead of `install`.
   * Pass `--headless` to run without the interactive installer UI.
   * (Optional) Pass `--config-values` with the path to your [ConfigValues](/reference/custom-resource-configvalues) file to change configuration.
   * (Optional) Pass `--installer-password` to change the installer password.

   Example:

   ```bash
   sudo ./APP_SLUG upgrade --license LICENSE_FILE --headless
   ```

1. Monitor the command output until the upgrade completes.

## Reconfigure an application without upgrading the application version

To redeploy or reconfigure an instance without upgrading, include the installation assets for the currently installed version when you perform the upgrade.

### UI-based upgrade

To change an application's configuration without upgrading the application version, follow the path that matches your setup:

#### If the persistent admin console is **not** installed

1. Run `upgrade` using the binary for the application version that you already have installed (not a newer version). For example, if you installed 1.2.3, download and run `upgrade` with the 1.2.3 assets:

   ```bash
   sudo ./APP_SLUG upgrade --license LICENSE_FILE
   ```

1. When prompted, log in with the installer password.

1. On the **Configure** page, change the target values, then follow the interactive upgrade process to apply the new configuration.

#### If the persistent admin console is installed

1. Open the console at `https://<controller-hostname>:30080/console`.

1. On the dashboard, click **Redeploy** next to the current version.

1. Follow the interactive upgrade process to apply the new configuration.

### Headless upgrade

To change an application's configuration without upgrading the application version:

1. Update the ConfigValues to make the application configuration changes.
1. Run the `upgrade` command using the binary for the application version that you already have installed. For example, if you installed version 1.2.3, download and run `upgrade` with the assets for version 1.2.3. Pass the updated configuration values with `--config-values`.

## Change the customer-managed (BYO) registry configuration

The `upgrade` command can also enable a [customer-managed (BYO) registry](installing-embedded-byo-registry) on an existing cluster, rotate the registry credentials or certificates, switch to a different BYO registry, or revert to the default registry. See [Change BYO registry configuration on upgrade](installing-embedded-byo-registry#upgrade-byo).

## Upgrade in air-gapped environments

To perform an upgrade with Embedded Cluster in air-gapped environments:

1. In the Vendor Portal, open the **Customers** page and select the target customer.

1. At the top of the customer page, click **Install instructions > Embedded Cluster** or **Embedded Cluster install instructions**.

1. In the **Embedded Cluster install instructions** dialog, enable the air gap option.

1. Run the first command to download the installation assets to a machine with internet access.

1. Transfer them to the air-gapped host. Run the second command to untar.

1. Copy the `install` command and replace `install` with `upgrade`. For example, `sudo ./app-slug upgrade --license license.yaml`.

    Embedded Cluster automatically detects the air gap installation, and performs an air gap upgrade.

### From the persistent admin console

If the [persistent admin console](embedded-persistent-console) is installed on a controller, you can perform air gap upgrades from the browser without SSH access:

1. Open the console at `https://<controller-hostname>:30080/console` and log in with the installer password.

1. In the **Available updates** section, upload the release archive (`.tgz`). The console validates the archive against the installed license, uploads it, and adds the new release to the list.

   Uploads are resumable across browser sessions. If you close or refresh the browser mid-upload, the dashboard prompts you to resume the next time you open it — re-picking the same file continues from where the upload left off.

1. Click **Upgrade** on the new release row to run through the standard upgrade wizard.

#### Re-upload the current release

The currently-installed release can also be updated from the dashboard. Two common reasons to do this:

* **To update the license.** Re-upload the release archive containing the new license, then click **Redeploy** to apply it.

* **To enable redeploy.** Redeploy requires a local copy of the release archive. If that copy is missing, re-upload to restore it.

### Headless air-gapped upgrade

To perform a headless upgrade in an air-gapped environment, pass `--headless` along with the upgrade command:

```bash
sudo ./APP_SLUG upgrade --license LICENSE_FILE --headless
```

Optionally pass `--config-values` with the path to your [ConfigValues](/reference/custom-resource-configvalues) file to change configuration during the upgrade. Embedded Cluster automatically detects the air gap installation.