Skip to main content

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.

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 with a user for your test customer.

  2. 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, open the Customers page and select a customer that you assigned to the channel you use for testing.

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

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

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

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

    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.

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

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

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

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

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

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

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

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

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.

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

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

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

  5. 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 file to change configuration.
    • (Optional) Pass --installer-password to change the installer password.

    Example:

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

  6. 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:

    sudo ./APP_SLUG upgrade --license LICENSE_FILE

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

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

  2. On the dashboard, click Redeploy next to the current version.

  3. 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.
  2. 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 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.

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.

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

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

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

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

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

Headless air-gapped upgrade​

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

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

Optionally pass --config-values with the path to your ConfigValues file to change configuration during the upgrade. Embedded Cluster automatically detects the air gap installation.

On this page