Upgrading KOTS

Upgrading KOTS

This page contains instructions for how to upgrade KOTS (the platform and the Admin Console). This is normally done as part of upgrading SwaggerHub and is not required for every install.

Note

Be aware that upgrading the single-node VM install will require downtime, so schedule at least 3 hours to complete the process.

If your version of KOTS is too old, then you will see a message on the Admin Console. If you do not see this message, then there is no need to continue with this step of the installation.

check-kot-required.png

Before beginning to install KOTS, note the version number at the bottom of the Admin Console. When your upgrade is successfully installed, the version number will be updated.

kots-version-number.png

How to Upgrade KOTS on an Existing Cluster

These instructions apply to all existing clusters except OpenShift with minimal RBAC. For existing OpenShift clusters with minimal RBAC, click here. For embedded clusters, click here.

Upgrading KOTS on an existing cluster - online

First, you need to update the KOTS CLI:

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

Then, the Admin Console needs to be updated as well.

kubectl kots admin-console upgrade -n <namespace>

The field at the very bottom of the page indicates the current KOTS version - it’ll change when the page is refreshed.

Upgrading KOTS on an existing cluster - airgapped

Step 1: Follow the instructions here.

Important

The KOTS CLI version must match the airgap bundle version.

Step 2: Update the Admin Console with:

kubectl kots admin-console push-images ./kotsadm.tar.gz private.registry.host/application-name \ 
  --registry-username rw-username \
  --registry-password rw-password
  
kubectl kots admin-console upgrade \ 
  --kotsadm-registry private.registry.host/application-name \ 
  --registry-username ro-username \ 
  --registry-password ro-password \ 
  -n <namespace>

How to Upgrade KOTS on an Existing OpenShift Cluster with Minimal RBAC

These instructions apply only to existing OpenShift clusters with minimal RBAC. For embedded clusters, click here.

Upgrading KOTS on an existing OpenShift cluster with minimal RBAC - online

First, you need to update the KOTS CLI:

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

Then, the Admin Console needs to be updated as well with namespace-scoped access.

kubectl kots admin-console upgrade -n <namespace> --skip-rbac-check --ensure-rbac=false

The field at the very bottom of the page indicates the current KOTS version - it’ll change when the page is refreshed.

Upgrading KOTS on an existing OpenShift cluster with minimal RBAC - airgapped

Step 1: Follow the instructions here.

Important

The KOTS CLI version must match the airgap bundle version.

Step 2: Update the Admin Console with namespace-scoped access:

kubectl kots admin-console push-images ./kotsadm.tar.gz private.registry.host/application-name \ 
  --registry-username rw-username \
  --registry-password rw-password
  
kubectl kots admin-console upgrade \ 
  --kotsadm-registry private.registry.host/application-name \ 
  --registry-username ro-username \ 
  --registry-password ro-password \ 
  -n <namespace> \
  --skip-rbac-check \
  --ensure-rbac=false

How to Upgrade KOTS on a VM/Embedded Cluster

Caution

Before doing any system upgrades, be sure to do a complete system backup.

These instructions apply only to VM/embedded clusters. For existing clusters, check the Upgrading KOTS on an existing cluster - air-gapped section.

When using SwaggerHub with an embedded Kubernetes cluster, KOTS is delivered as an add-on to the kURL cluster. Therefore, upgrading KOTS requires upgrading the entire kURL cluster.

Before initiating the kURL upgrade, ensure that all Longhorn volumes are in a healthy state. Verify that the volumes are functional and not experiencing any issues that could impact the migration process. Before proceeding with the 2.7 migration, familiarize yourself with the necessary prerequisites to ensure a smooth and successful transition.

For VM installs, it is normal for ROBUSTNESS to be degraded as the default configuration for Longhorn is to have 3 Replicas configured, but as in a single instance VM, only 1 is available. However, verify that no other issues are being reported before proceeding.

Use the following command to do so:

kubectl get volumes.longhorn.io -A

Note

This information is specific to the 2.7 release and may not be applicable to future versions.

Note

When upgrading KOTS on a VM, you will be asked to confirm certain component upgrades and when needed to drain a node. Please enter 'y' when asked to proceed with the process.

Upgrading KOTS on an embedded cluster - online

The whole cluster needs to be updated by running one of the two commands below.

Note

For customers migrating to 2.7, when upgrading KOTS, you will encounter a false-positive error: Error from server (NotFound): namespaces "rook-ceph" not found that you can proceed safely if you use the manual confirmation method.

To confirm confirmation prompts manually, use:

curl -sSL https://kurl.sh/swaggerhub | sudo bash

To skip confirmation prompts, use:

curl -sSL https://kurl.sh/swaggerhub | sudo bash -s yes

Upgrading KOTS on an embedded cluster - air-gapped

To update the KOTS platform and Admin Console, the customer needs to get the swaggerhub.tar.gz file from the download portal and copy it to the VM. For more information, go to VM (Embedded Cluster) - Airgapped Installation. To do that, follow the procedure:

  1. Unpack archive: tar xzvf swaggerhub.tar.gz

  2. Load / check images: cat tasks.sh | sudo bash -s load-images

  3. Execute installation script: cat install.sh | sudo bash -s airgap

If you encounter missing packages during kURL cluster upgrade on an air-gapped environment:

  1. Download the missing packages from the provided curl command on another machine with Internet access.

    Example:

    curl -LO https://kurl.sh/bundle/version/v2024.01.02-0/swaggerhub/packages/kubernetes-1.24.17,kubernetes-1.25.14,kubernetes-1.26.12.tar.gzcurl -LO https://kurl.sh/bundle/version/v2024.1201-0/swaggerhub/packages/kubernetes-1.24.17,kubernetes-1.25.14,kubernetes-1.26.12.tarcurl -LO https://kurl.sh/bundle/version/v2024.01.02-0/swaggerhub-unstable/packages/kubernetes-1.24.17,kubernetes-1.25.14,kubernetes-1.26.12.tar.gzcurl -LO https://kurl.sh/bundle/version/v2024.1201-0/swaggerhub-unstable/packages/kubernetes-1.24.17,kubernetes-1.25.14,kubernetes-1.26.12.tar

    Note

    Note that the provided curl command is just an example. The actual command displayed during the installation may differ.

  2. Copy the downloaded archive with missing packages to the target VM where SwaggerHub is installed.

    Example:

    /home/<name>/your-folder/kubernetes-1.24.17,kubernetes-1.25.14,kubernetes-1.26.12.tar

  3. Provide the absolute path to the archive when prompted by the kURL installer.

  4. If the path is incorrect, the kURL upgrade will be aborted, and you'll need to start the procedure again.

Alternatively:

  1. Copy the downloaded archive to the /var/lib/kurl/assets/ directory.

  2. Manually restart the kURL installer.

  3. Note that the assets folder needs to be created manually before copying the archive.

Note

This procedure is specific to the 2.7 update and may not be applicable to future versions of kURL.

The kURL upgrade process will temporarily disrupt access to both the SwaggerHub UI and Admin Console. Plan your upgrade accordingly to minimize downtime.

Example:

kURL-upgrade.png

See Also

In this section:
© 2024
Publication date: