Best Practices for Executing Upgrades of KOTS/kURL infrastructure

Had a great question come in today that isn’t super well documented anywhere today.

We have several instances in the field across embedded and existing clusters. The app version is easy to keep up to date, but we’re wondering what are the best practices for upgrading the KOTS App Manager version for these installs in the field, as well as upgrading Kubernetes and other underlying kURL components.

Tactical Execution

  1. Test all upgrades in a representative environment in your infrastructure. That means, install the exact version of your app, KOTS App Manager, (and the kURL stack if applicable) and then test the upgrade path for upgrading App Manager or kURL or both. This will mean building an understanding of the state of each customer whom you’re looking to upgrade. You can review this in the Customer Reporting section of
  2. It is highly recommended that you enable and test Replicated’s Snapshot and Restore capabilities so that you can take a pre-upgrade snapshot in case anything goes wrong
  3. Minimize incremental upgrade scope. While it can be tempting to try to upgrade k8s, kots, and your network layer all in one go, it is much better to do 3 smaller upgrades, testing in isolation, than to try to upgrade all of these things at once. This is especially true for upgrades involving Kubernetes, network plugins, or storage providers.

Performing Upgrades

KOTS app Manager is released weekly, and today the way to upgrade it in an Existing Cluster to use the kots CLI.

  1. Install the latest version of the CLI with curl | bash (or download a release from the releases page Releases · replicatedhq/kots · GitHub)
  2. Run kubectl kots admin-console upgrade --namespace $NAMESPACE using the namespace where the kotsadm workloads are deployed.

For Embedded Cluster

  1. For embedded cluster, you can increase the versions of any components desired in your spec, publish a new version, and then instruct the user to run the same install command they used initially. This is usually some flavor of curl | sudo bash – this operation is idempotent and will upgrade any necessary components based on the latest kURL installer spec published to the the app (and channel) indicated by the URL path in the URL. See also: Upgrading kURL Clusters.