Skip to main content

Updating Kubernetes Installer Clusters

This topic describes how to upgrade the versions of Kubernetes, the Replicated app manager, and add-ons in a cluster created by the Replicated Kubernetes installer.

About Updating Clusters​

The application vendor uses a Kubernetes installer specification file to specify the add-ons and the version of Kubernetes that are deployed to your cluster. To update your cluster based on this installer specification file, you run the Kubernetes installer installation script.

For more information about how the script updates the versions of Kubernetes, the app manager, and any additional add-ons running in your cluster, see the following sections:

Kubernetes Updates​

The installation script automatically detects when the Kubernetes version in your cluster must be updated. When a Kubernetes upgrade is required, the script first prints a prompt: Drain local node and apply upgrade?. When you confirm the prompt, it drains and upgrades the local primary node where the script is running.

Then, if there are any remote primary nodes to upgrade, the script drains each sequentially and prints a command that you must run on the node to upgrade. For example, the command that that script prints might look like the following: curl -sSL https://kurl.sh/myapp/upgrade.sh | sudo bash -s hostname-check=master-node-2 kubernetes-version=v1.24.3.

The script polls the status of each remote node until it detects that the Kubernetes upgrade is complete. Then, it uncordons the node and proceeds to cordon and drain the next node. This process ensures that only one node is cordoned at a time. After upgrading all primary nodes, the script performs the same operation sequentially on all remote secondary nodes.

Multi-version Kubernetes Updates​

The Kubernetes installer supports upgrading at most two minor versions of Kubernetes at a time. When upgrading two minor versions at one time, the installation script first installs the skipped minor version before installing the target version. For example, when you upgrade directly from Kubernetes 1.22.x to 1.24.x, the script first completes the installation of 1.23.x before installing 1.24.x.

If the script detects that the version of Kubernetes in your cluster is more than two minor versions earlier than the target version, it prints an error message similar to the following: The currently installed kubernetes version is 1.23.16. The requested version to upgrade to is 1.26.0. Kurl can only be upgraded two minor versions at time. Please install 1.25.x. first.

To update Kubernetes when your currently installed version is more than two minor versions behind the target version, contact your application vendor for an additional Kubernetes installer installation script that specifies the prerequisite Kubernetes version indicated in the error message.

After you update Kubernetes in your cluster to the prerequisite version, you can continue with the upgrade by running the target installation script. For example, to upgrade from Kubernetes 1.23.x to 1.26.x, first run an installation script that specifies Kubernetes 1.25.x. Then, run the target installation script that specifies 1.26.x.

Add-ons and App Manager Updates​

If the application vendor updated any add-ons in the Kubernetes installer specification since the last time that you ran the installation script in your cluster, the script automatically updates the add-ons after completing any required Kubernetes upgrade.

For a complete list of add-ons that can be included in the Kubernetes installer specification, including the KOTS add-on, see Add-ons in the kURL documentation.

Containerd and Docker Add-on Updates​

The installation script upgrades the version of the Containerd or Docker container runtime if required by the installer specification file. For example, if your cluster uses Containerd version 1.6.4 and the specification file is updated to use 1.6.18, then Containerd is updated to 1.6.18 in your cluster when you run the installation script.

The installation script also supports migrating from Docker to Containerd as Docker is not supported in Kubernetes versions 1.24 and later. If the install script detects a change from Docker to Containerd, it installs Containerd, loads the images found in Docker, and removes Docker.

For information about the container runtime add-ons, see Containerd Add-On and Docker Add-On in the kURL documentation.

App Manager Updates (KOTS Add-on)​

The version of the app manager installed in your cluster is set by the KOTS add-on provided in the Kubernetes installer specification file. For example, if the version of the app manager running in your cluster is 1.92.0, and the vendor updates the KOTS add-on in the Kubernetes installer specification to use 1.92.1, then the app manager version in your cluster is updated to 1.92.1 when you run the installation script.

Update​

This section includes procedures for updating Kubernetes installer clusters in online and air gapped environments.

note

The Kubernetes scheduler automatically reschedules Pods to other nodes during maintenance. Any deployments or StatefulSets with a single replica experience downtime while being rescheduled.

Online Environments​

To update the cluster in an online environment:

  1. Run the Kubernetes installer script on any primary node in the cluster:

    curl -sSL https://k8s.kurl.sh/APP_SLUG | sudo bash -s ADVANCED_OPTIONS

    Replace:

    • APP_SLUG with the unique slug for the application from your application vendor.

    • ADVANCED_OPTIONS optionally with any flags listed in Advanced Options in the kURL documentation.

      To use no advanced installation options, remove -s ADVANCED_OPTIONS from the command.

      See the following recommendations for advanced options:

      • installer-spec-file: If you used the installer-spec-file flag to pass a patch.yaml file when you ran the installation script previously, you must include the installer-spec-file flag with the same patch.yaml file when you rerun the installation script. This prevents the installer from overwriting any configuration from your patch.yaml file and making changes to the add-ons in your cluster. For example: curl https://kurl.sh/latest | sudo bash -s installer-spec-file="./patch.yaml"

      • app-version-label: By default, the KOTS add-on in the Kubernetes installer specification also upgrades your application to the latest version when you run the installation script.

        You can specify a target application version with the app-version-label flag. Or, to avoid upgrading your application version, set the app-version-label flag to the currently installed application version.

        Example

        In the following example, the script updates the application to version 1.5.0:

        curl https://kurl.sh/latest | sudo bash -s app-version-label=1.5.0

  2. (Kubernetes Upgrades Only) If the script detects that the version of Kubernetes in your cluster must be upgraded, it prints a Drain local node and apply upgrade? prompt. Confirm the prompt to drain the local primary node and apply the Kubernetes upgrade to the control plane.

    The script continues to drain and upgrade nodes sequentially. For each node, the script prints a command that you must run on the node to upgrade Kubernetes.

    After the Kubernetes upgrade on each node is complete, the script automatically updates any add-ons in your cluster.

    For more information about this update process, see About Updating Kubernetes Installer Clusters above.

Air Gap Environments​

For air gap installations, you must load images on each node in the cluster before you can run the installation script to update Kubernetes and any add-ons. This is because upgraded components might have Pods scheduled on any node in the cluster.

To update the cluster in an air gap environment:

  1. Download and extract the .airgap bundle to every node in the cluster.

  2. Run the following script to ensure all required images are available:

    cat tasks.sh | sudo bash -s load-images
    note

    When you run the installation script in the next step, the script also performs a check for required images and prompts you to run the load-images command if any images are missing.

  3. Run the Kubernetes installer script on any primary node in the cluster with the airgap option:

    curl -sSL https://k8s.kurl.sh/APP_SLUG | sudo bash -s airgap OTHER_ADVANCED_OPTIONS

    Replace:

    • APP_SLUG with the unique slug for the application from your application vendor.

    • OTHER_ADVANCED_OPTIONS optionally with any flags listed in Advanced Options in the kURL documentation.

      See the following recommendations for advanced options:

      • installer-spec-file: If you used the installer-spec-file flag to pass a patch.yaml file when you ran the installation script previously, you must include the installer-spec-file flag with the same patch.yaml file when you rerun the installation script. This prevents the installer from overwriting any configuration from your patch.yaml file and making changes to the add-ons in your cluster. For example: curl https://kurl.sh/latest | sudo bash -s installer-spec-file="./patch.yaml"

      • app-version-label: By default, the KOTS add-on in the Kubernetes installer specification also upgrades your application to the latest version when you run the installation script.

        You can specify a target application version with the app-version-label flag. Or, to avoid upgrading your application version, set the app-version-label flag to the currently installed application version.

        Example

        In the following example, the script updates the application to version 1.5.0:

        curl https://kurl.sh/latest | sudo bash -s app-version-label=1.5.0

  4. (Kubernetes Upgrades Only) If the script detects that the version of Kubernetes in your cluster must be upgraded, it prints a Drain local node and apply upgrade? prompt. Confirm the prompt to drain the local primary node and apply the Kubernetes upgrade to the control plane.

    The script continues to drain and upgrade nodes sequentially. For each node, the script prints a command that you must run on the node to upgrade Kubernetes.

    After the Kubernetes upgrade on each node is complete, the script automatically updates any add-ons in your cluster.

    For more information about this update process, see About Updating Kubernetes Installer Clusters above.