Skip to main content

Performing Updates in Existing Clusters

This topic describes how to perform updates in existing cluster installations with Replicated KOTS. It includes information about how to update applications and the version of KOTS running in the cluster.

Update an Application​

You can perform an application update using the KOTS Admin Console or the KOTS CLI. You can also set up automatic updates. See Configuring Automatic Updates.

Using the Admin Console​

Online Environments​

To perform an update from the Admin Console:

  1. In the Admin Console, go to the Version History tab.

  2. Click Check for updates.

    A new upstream version displays in the list of available versions.

    New Version Available

    View a larger version of this image

  3. (Optional) When there are multiple versions of an application, you can compare the changes between them by clicking Diff releases in the right corner.

    You can review changes between any two arbitrary releases by clicking the icon in the header of the release column. Select the two versions to compare, and click Diff releases to show the relative changes between the two releases.

    Diff Releases

    View a larger version of this image

    New Changes

    View a larger version of this image

  4. (Optional) Click the View preflight checks icon to view or re-run the preflight checks.

    Preflight checks

    View a larger version of this image

  5. Return to the Version History tab and click Deploy next to the target version.

Air Gap Environments​

To perform an air gap update from the Admin Console:

  1. In the Vendor Portal, go the channel where the target release is promoted to build and download the new .airgap bundle:

    • If the Automatically create airgap builds for newly promoted releases in this channel setting is enabled on the channel, watch for the build status to complete.

    • If automatic air gap builds are not enabled, go to the Release history page for the channel and build the air gap bundle manually.

      Release history link on a channel card

      View a larger version of this image

      Build button on the Release history page

      View a larger version of this image

  2. After the build completes, download the bundle. Ensure that you can access the downloaded bundle from the environment where you will install the application.

  3. (Optional) View the contents of the downloaded bundle:

    tar -zxvf AIRGAP_BUNDLE

    Where AIRGAP_BUNDLE is the filename for the .airgap bundle that you downloaded.

  4. In the Admin Console, go to the Version History tab.

  5. Click Upload a new version.

    A new upstream version displays in the list of available versions.

    New Version Available

  6. (Optional) When there are multiple versions of an application, you can compare the changes between them by clicking Diff releases in the right corner.

    You can review changes between any two arbitrary releases by clicking the icon in the header of the release column. Select the two versions to compare, and click Diff releases to show the relative changes between the two releases.

    Diff Releases New Changes

  7. (Optional) Click the View preflight checks icon to view or re-run the preflight checks.

    Preflight Checks

  8. Return to the Version History tab and click Deploy next to the target version.

Using the KOTS CLI​

You can use the KOTS CLI upstream upgrade command to update an application in existing cluster installations.

Online Environments​

To update an application in online environments:

kubectl kots upstream upgrade APP_SLUG -n ADMIN_CONSOLE_NAMESPACE

Where:

  • APP_SLUG is the unique slug for the application. See Get the Application Slug in Managing Applications.
  • ADMIN_CONSOLE_NAMESPACE is the namespace where the Admin Console is running.
note

Add the --deploy flag to automatically deploy this version.

Air Gap Environments​

To update an application in air gap environments:

  1. In the Vendor Portal, go the channel where the target release is promoted to build and download the new .airgap bundle:

    • If the Automatically create airgap builds for newly promoted releases in this channel setting is enabled on the channel, watch for the build status to complete.

    • If automatic air gap builds are not enabled, go to the Release history page for the channel and build the air gap bundle manually.

      Release history link on a channel card

      View a larger version of this image

      Build button on the Release history page

      View a larger version of this image

  2. After the build completes, download the bundle. Ensure that you can access the downloaded bundle from the environment where you will install the application.

  3. (Optional) View the contents of the downloaded bundle:

    tar -zxvf AIRGAP_BUNDLE

    Where AIRGAP_BUNDLE is the filename for the .airgap bundle that you downloaded.

  4. Run the following command to update the application:

    kubectl kots upstream upgrade APP_SLUG \
      --airgap-bundle NEW_AIRGAP_BUNDLE \
      --kotsadm-registry REGISTRY_HOST[/REGISTRY_NAMESPACE] \
      --registry-username RO_USERNAME \
      --registry-password RO_PASSWORD \
      -n ADMIN_CONSOLE_NAMESPACE

    Replace:

    • APP_SLUG with the unique slug for the application. See Get the Application Slug in Managing Applications.
    • NEW_AIRGAP_BUNDLE with the .airgap bundle for the target application version.
    • REGISTRY_HOST with the private registry that contains the Admin Console images.
    • REGISTRY_NAMESPACE with the registry namespace where the images are hosted (Optional).
    • RO_USERNAME and RO_PASSWORD with the username and password for an account that has read-only access to the private registry.
    • ADMIN_CONSOLE_NAMESPACE with the namespace where the Admin Console is running.
note

Add the --deploy flag to automatically deploy this version.

Update KOTS​

This section describes how to update the version of Replicated KOTS running in your cluster. For information about the latest versions of KOTS, see KOTS Release Notes.

note

Downgrading KOTS to a version earlier than what is currently deployed is not supported.

Online Environments​

To update KOTS in an online existing cluster:

  1. Run one of the following commands to update the KOTS CLI to the target version of KOTS:

    • Install or update to the latest version:

      curl https://kots.io/install | bash

    • Install or update to a specific version:

      curl https://kots.io/install/VERSION | bash

      Where VERSION is the target KOTS version.

    For more KOTS CLI installation options, including information about how to install or update without root access, see Installing the KOTS CLI.

  2. Run the following command to update the KOTS Admin Console to the same version as the KOTS CLI:

    kubectl kots admin-console upgrade -n NAMESPACE

    Replace NAMESPACE with the namespace in your cluster where KOTS is installed.

Air Gap Environments​

To update KOTS in an existing air gap cluster:

  1. Download the target version of the following assets from the Releases page in the KOTS GitHub repository:

    • KOTS Admin Console kotsadm.tar.gz bundle
    • KOTS CLI plugin

    Ensure that you can access the downloaded bundles from the environment where the Admin Console is running.

  2. Install or update the KOTS CLI to the version that you downloaded. See Manually Download and Install in Installing the KOTS CLI.

  3. Extract the KOTS Admin Console container images from the kotsadm.tar.gz bundle and push the images to your private registry:

    kubectl kots admin-console push-images ./kotsadm.tar.gz REGISTRY_HOST \
      --registry-username RW_USERNAME \
      --registry-password RW_PASSWORD

    Replace:

    • REGISTRY_HOST with the hostname for the private registry. For example, private.registry.host or my-registry.example.com/my-namespace.

    • RW_USERNAME and RW_PASSWORD with the username and password for an account that has read and write access to the private registry.

      note

      KOTS does not store or reuse these read-write credentials.

  4. Run the following command using registry read-only credentials to update the KOTS Admin Console:

    kubectl kots admin-console upgrade \
      --kotsadm-registry REGISTRY_HOST \
      --registry-username RO_USERNAME \
      --registry-password RO_PASSWORD \
      -n NAMESPACE

    Replace:

    • REGISTRY_HOST with the same private registry from the previous step.
    • RO_USERNAME with the username for credentials with read-only permissions to the registry.
    • RO_PASSWORD with the password associated with the username.
    • NAMESPACE with the namespace on your cluster where KOTS is installed.

    For help information, run kubectl kots admin-console upgrade -h.