Upgrade Konvoy CLI

Upgrade Konvoy image CLI version

NOTE: Before upgrading, keep in mind that your Konvoy CLI version can only be upgraded to a compatible Konvoy version.

Before you begin: Prepare for Konvoy CLI upgrade

If you’re using a newer version of the Konvoy CLI, it may require changes to your cluster.yaml, as described below.

A Konvoy upgrade consists of a few distinct steps.

  1. Download the Konvoy binary and extract it in your environment in the same manner as the initial install.
  2. Gain access to the cluster.yaml file, and the SSH keys that were generated during the initial install.
  3. Update the cluster.yaml file with the changes described below.
  4. Run konvoy up --upgrade, which upgrades the version of Kubernetes on all of the control-plane nodes, then upgrades the rest of the nodes and platform services, and installs any addons specified in the cluster.yaml file.

Konvoy CLI available versions

You can verify which version your CLI can be upgraded to by running the following command:

konvoy image list

This command lists all the available versions to which your current CLI can be upgraded. This list also shows the default Kubernetes version of each Konvoy version.

This command uses Docker Hub to fetch all the available Konvoy versions.

Using a private Docker registry

If you are using a private Docker registry for your clusters, you will have to follow the private Docker registry steps to pull the Konvoy images.

Konvoy CLI version upgrade

After you have the available Konvoy versions, you can upgrade your CLI by running the following command:

konvoy image upgrade --version=v1.8.0
Wrote Konvoy CLI version 'v1.8.0' to '.konvoy/cli_version'

After the upgrade command completes, you can start using the new Konvoy version.

Upgrading Konvoy from v1.7.x to v1.8.0

NOTE: You must modify your cluster.yaml file with these changes when upgrading from a previous Konvoy version:

  • Upgrade to the newest supported version of Kubernetes. Set spec.kubernetes.version: 1.20.6 for kind: ClusterConfiguration.

  • If you are using Kubernetes Base Addons, the version has changed. You must set your configRepository to https://github.com/mesosphere/kubernetes-base-addons and configVersion to spec.addons.configVersion: stable-1.20-4.0.0 for kind: ClusterConfiguration.

  • If you use Kommander, you must set the configVersion to spec.addons.configVersion: stable-1.20-1.4.0 and your configRepository to https://github.com/mesosphere/kubeaddons-kommander for kind: ClusterConfiguration.

  • If you have Dispatch enabled, you must set the configVersion to configVersion: stable-1.20-1.4.5 and your configRepository to https://github.com/mesosphere/kubeaddons-dispatch for kind: ClusterConfiguration.

The version of Konvoy is now v1.8.0, set spec.version: v1.8.0.

kind: ClusterProvisioner
  version: v1.8.0
kind: ClusterConfiguration
apiVersion: konvoy.mesosphere.io/v1beta1
    version: 1.20.6
    - configRepository: https://github.com/mesosphere/kubernetes-base-addons
      configVersion: stable-1.20-4.0.0
    - configRepository: https://github.com/mesosphere/kubeaddons-dispatch
      configVersion: stable-1.20-1.4.5
        - name: dispatch
          enabled: true
    - configRepository: https://github.com/mesosphere/kubeaddons-kommander
      configVersion: stable-1.20-1.4.0
        - name: kommander
          enabled: true
  version: v1.8.0

Upgrades and Running Workloads

NOTE: During the upgrade process, if the cluster has certain types of workloads running, the Konvoy CLI displays a warning. These warnings report skipped nodes in the upgrade process.

Konvoy preserves the availability of applications in the cluster by detecting:

  • All replicas of a ReplicaSet run on a single node. Draining that node interrupts the application.
  • ReplicaSets having a replica count less than 2. Draining this node interrupts the application.
  • Pods using an EmptyDir volume, or other host-based storage that binds the pod to a specific node, preventing it from migrating to another node.

To force the node to upgrade, you can run konvoy up --upgrade --force-upgrade, which upgrades all the nodes and ignores the safety checks. This can result in temporary interruptions to application availability.

IMPORTANT: During the node drain stage, Konvoy may exhibit a time-out error while waiting for workloads to reschedule. Users can bypass this process during upgrade by using konvoy up --upgrade --force-upgrade --without-draining. This usage can result in undefined behavior, interruptions to application availability and service downtime.

Konvoy avoids interrupting applications by default, and displays these warnings while deferring upgrade operations.

To avoid these warnings, and reduce risks to application availability:

  • Configure the application’s deployment to run multiple replicas for fault tolerance.
  • Using distributed or remote storage solutions instead of host-based storage.
  • Set Pod anti-affinity to ensure pods distribute across nodes for better fault tolerance.