Skip to content

Upgrade an existing MKE 4k cluster#

Typically, each MKE 4k CLI (mkectl) version is tethered to a particular MKE 4k release and should only be used with that release. Thus, for example, you must use mkectl x.y.1 with MKE 4k release x.y.1 and not with MKE 4k release x.y.2. An exception to this, though, is when you upgrade MKE 4k to a later release, wherein you should use the mkectl version that aligns with the target MKE 4k release.

The current upgrade paths for MKE 4k clusters are detailed below:

Source release Target release mkectl version required
4.1.0 4.1.4 4.1.4
4.1.1 4.1.4 4.1.4
4.1.2 4.1.4 4.1.4
4.1.3 4.1.4 4.1.4

Info

As MKE 4.1.0 is built on an alpha version of k0rdent, upgrading from that MKE 4k release involves a complete reinstallation of MKE 4k and k0rdent, resulting in a more prolonged upgrade process.

Important

You cannot change the registries once a cluster is operational.

To upgrade your MKE 4k cluster:

  1. Verify that you have the latest version of the mkectl binary. For information on how to download and install mkectl, refer to Install the MKE 4k CLI.

  2. Back up MKE 4k prior to initiating the upgrade.

    Info

    If you do not provide a path to an MKE 4k backup as part of the mkectl upgrade command, mkectl automatically generates a pre-upgrade backup prior to initiating the upgrade.

  3. Run the upgrade.

    mkectl upgrade --upgrade-version <version_to_upgrade_to> \
               --backup-path <path_to_pre-upgrade_backup>

Important

For MKE 4k upgrades from version 4.1.2 to versions 4.1.4 and later (Mirantis does not support upgrades to version 4.1.3), you must specify NodePorts for the Gateway API. In addition, you must identify a listener port to which the Logon UI can be directed and configure your load balancer to ensure that the listener port redirects to your specified Gateway API HTTPS NodePort. You can select 443 or any other unused listener port, indicating your choice with the --gateway-listener-port parameter when you run the mkectl upgrade command.

Specify the NodePort values, using the --gateway-https-node-port parameter for HTTPS and the --gateway-http-node-port parameter for HTTP. Note that the load balancer only needs to route traffic from the listener port to the HTTPS NodePort.

Be aware that you must set all four Gateway API parameters when you use the --keep-ingress-nginx option to upgrade from MKE 4k 4.1.2 or earlier to MKE 4k 4.1.4 or later. Specifically, if you opt to specify any of the following four parameters with the mkectl upgrade command, you must specify all of them:

  • --keep-ingress-nginx
  • --gateway-listener-port
  • --gateway-https-node-port
  • --gateway-http-node-port

If you are upgrading an MKE 4k 4.1.3 cluster to version 4.1.4 or later, do not use these Gateway API parameters.

Failed upgrade rollback

If an upgrade from a previous MKE 4k release fails at any stage, the cluster automatically rolls back to the original version using a backup. If you specified a backup with the --backup-path flag when running mkectl upgrade, that backup is used for the restore. Otherwise, the system restores the cluster from the backup it created automatically before the upgrade began.

A support bundle is automatically collected as a result of the rollback operation, which you can use to troubleshoot the upgrade procedure.

If the upgrade fails after the Pre Upgrade Backup step, rollback is initiated, restoring the cluster to the state that was captured by that step. If, though, the failure occurs during the Pre Upgrade Checks step or the Pre Upgrade Backup step, no rollback is performed, as no destructive steps have yet taken place.

Rollback runs in reverse order of the upgrade steps that have been executed.