The Okctl team is continously updating the okctl command line tool in order to bring new features and bug fixes to the infrastructure and applications that Okctl sets up.

Existing Okctl environments need to be upgraded in order to stay up to date with new versions of Okctl. This is what okctl upgrade does.

With "environment", we mean the things you get when you run okctl apply cluster, which consists of the components described in the Architecture documentation. This command does not upgrade applications made with okctl create application. See the Upgrade application documentation for how to do this.

An example of how upgrades work:

  • In a new version of Okctl, when you run okctl apply cluster, you get version 2.1.7 of ArgoCD. Existing clusters made with previous versions of Okctl, however, run ArgoCD 1.7.2.
  • Since ArgoCD already exists, running okctl apply cluster won't change anything. To upgrade ArgoCD and other resources that are lagging behind, you can run okctl upgrade.

Upgrade

# Usage
okctl --cluster-declaration <path to cluster declaration> upgrade

# Example:
okctl --cluster-declaration cluster.yaml upgrade

You will be prompted before continuing.

Example output:

$ okctl -c cluster-dev.yaml upgrade
Found 2 applicable upgrade(s):
0.0.50, 0.0.51

Simulating upgrades...

--- Simulating upgrade: okctl-upgrade_0.0.50 ---
Simulating the upgrade, not doing any changes.
Upgrading ArgoCD
Upgrading ArgoCD complete!
--- Simulating upgrade: okctl-upgrade_0.0.51 ---
Simulating the upgrade, not doing any changes.
Upgrading Some Other Component
Upgrading Some Other Component complete!

Simulating upgrades complete.

? This will upgrade your okctl cluster, are you sure you want to continue? Yes

--- Running upgrade: okctl-upgrade_0.0.50 ---
Upgrading ArgoCD
Upgrading ArgoCD complete!
--- Running upgrade: okctl-upgrade_0.0.51 ---
Upgrading Some Other Component
Upgrading Some Other Component complete!

Upgrade complete! Cluster version is now 0.0.70.

Questions and answers

okctl upgrade fails, what do I do?

First, attempt to run okctl upgrade again.

If the error persists, make sure you've read the blog article concerning the upgrade that fails, if it exists. It may contain details about how to recover.

If the error still persists, contact support.

Is there any way of knowing more in detail what okctl upgrade will do?

The source code is available in the okctl upgrade repository. Each upgrade is located in a separate folder in repository root directory.

Also, as you can see from the example output above, upgrades are being simulated before actually applied.

Can I downgrade after upgrading?

No. If you want to know that everything works as expected after upgrading, we advise you to create an additional cluster for testing. This test cluster should be as similar as possible to your production cluster, running the same applications and with the same configuration. Run okctl upgrade on this cluster to see that everything works as expected after upgrading.

Okctl says something about initializing parts of the cluster state. What does it mean?

When we released the upgrade feature, parts of the state (the state.db file) in okctl needed to be initialized before the user could run the upgrade command. Okctl prints this information because user action is needed, that is, commit the state.db file and push it.

Specficially, the cluster initialization means setting up data structures in the state for storing cluster versions, which is needed by upgrade to calculate which upgrades to apply.