Upgrading KOTS

Overview

As explained in the dependencies section, customer managed deployments rely on the Kubernetes-Off-The-Shelf (KOTS) appliance to configure and deploy the dbt Cloud application. When installing the dbt Cloud application for the first time as described in the installation section, the latest version of KOTS will be downloaded and installed along with the Admin Console. The KOTS version should be periodically upgraded to stay current with the latest release

To see the current installed version of KOTS the following command can be run:

kubectl kots version

The KOTS version is also visible at the bottom of the Admin Console UI next to "Terms" and "Privacy".

For newer versions of KOTS, the following command may be run to upgrade your installation to the latest stable version in place:

kubectl kots admin-console upgrade -n <namespace>

If you are upgrading your KOTS installation and have not tried the previous command, try this first before proceeding to the following section as manually upgrading may not be necessary. If the current installed version of KOTS is too old the upgrade command may fail and then the following instructions should be followed to manually upgrade the KOTS installation.

Manually upgrading the KOTS installation

This section describes the steps needed to manually upgrade KOTS by deleting the current installation and re-installing the latest version. This process necessitates updating dbt Cloud to the latest stable version and as such is it is recommended that this process be executed along with a planned dbt Cloud upgrade. This process will not cause any downtime of the dbt Cloud application.

Note: This process will erase the Version History in the Admin Console and force you to update to the latest stable version (meaning that you will lose the ability to roll back to prior versions). If you need to deploy a previous version of dbt Cloud please reach out to the Fishtown Analytics team.

Prerequisites

The following prerequisites are required prior to starting the manual upgrade process.

  • Latest KOTS Plugin: If you are deploying into an existing Kubernetes cluster, make sure the latest kots plugin is installed locally by running the following command.
curl https://kots.io/install | bash

If deploying into a VM, make sure the VM has the latest version installed by running the same command.

  • Backup configuration: This process will generate a backup of your configuration, but it is always a good idea to create a manual backup of your dbt Cloud configuration (especially the encryption settings and database settings, which can cause dbt Cloud to break if lost or not entered correctly).

  • License file: You will need to re-upload your license file when re-installing. If you do not have your license file a new one can be generated by reaching out to the Fishtown Analytics team.

Download the existing KOTS configuration

The following command will download the current application manifests from the Kubernetes cluster, including config values entered into the Admin Console.

kubectl kots download dbt-cloud-v1 --namespace <namespace> --dest ./dist

In older versions of KOTS, the config values will be stored at ./dist/upstream/userdata/config.yaml while newer versions store the config values at ./dist/dbt-cloud-v1/upstream/userdata/config.yaml.

This file will be used later when re-installing KOTS to restore the previous configuration. For more information about the kots download see here.

Note: In newer versions of KOTS the --decrypt-password-values flag can be set to decrypt password values. If this flag is not set the password values in the downloaded config file will be encrypted. As such, all secret values should be manually backed up as described in the prerequisites section.

Delete all 'kots' and 'kotsadm' Kubernetes objects

Deleting all of the 'kots' and 'kotsadm' Kubernetes objects will allow us to perform a clean slate install of the KOTS plugin. The following script will delete these objects:

kubectl delete deployment kotsadm kotsadm-api kotsadm-operator
kubectl delete statefulset kotsadm-minio kotsadm-postgres
kubectl delete pvc kotsadm-minio-kotsadm-minio-0 \
kotsadm-postgres-kotsadm-postgres-0
kubectl delete secret kotsadm-authstring kotsadm-cluster-token \
kotsadm-encryption kotsadm-minio kotsadm-password kotsadm-postgres \
kotsadm-replicated-registry kotsadm-session
kubectl delete configmap kotsadm-application-metadata

Note: In certain KOTS installations some of the resources in this script may not be present and create error messages in the terminal. This is fine and will not impact the deletion of other resources.

Re-install KOTS and upload the saved configuration

Once all the 'kots' and 'kotsadm' Kubernetes objects are deleted we can re-install KOTS with the latest version using the following two commands. The first command will make sure the latest kots release is downloaded and the second will re-install KOTS into the desired namespace with the pre-populated config values from the previous step. The second command will also prompt the user to enter a password for the Admin Console. This does not have to be the same password as previously entered for the Admin Console.

curl https://kots.io/install | bash
kubectl kots install dbt-cloud-v1 --namespace <cluster_namespace> \
--config-values "./dist/<dbt-cloud-v1?/>upstream/userdata/config.yaml"

Note that the config values path may need modified based on the current version of KOTS that is being upgraded from.

After the KOTS installer finishes, login to the Admin Console and verify that the config values are populated correctly in the console. Once verified click continue to proceed to the preflight checks. Once the preflight checks run successfully click continue again to deploy the latest stable version of dbt Cloud.

Re-install kURL proxy (VM only)

If running dbt Cloud in a VM (not recommended) the kURL installer will need to be run to re-install the kURL proxy to serve up the Admin Console.

Note: Before running this step it is recommended that you reach out to Fishtown Analytics as a slightly different version of this command may be needed depended on your license channel.

curl -sSL https://k8s.kurl.sh/dbt-cloud-v1 | sudo bash