Upgrades
This guide describes the steps to follow to upgrade the SIGHUP Distribution from one versions to the next using furyctl.
If you are running a custom set of modules, or different versions than the ones included with each release of SD, please refer to each module's release notes and upgrade manually.
We strongly recommend reading the whole guide before starting the upgrade process to identify possible blockers.
Upgrade procedure
The overall upgrade procedure is as follows:
- Upgrade the furyctl CLI to the latest version.
- Identify the upgrade path.
- Read the release notes for the target version.
- Check the cluster status.
- Run the upgrade.
1. Upgrade the furyctl CLI
To upgrade furyctl, follow the installation instructions for your operating system.
2. Identify the upgrade path
Each version of furyctl supports a set of upgrade paths for a specific version of SIGHUP Distribution. These are the tested and suggested upgrade paths to be used. You can create your own custom upgrade paths and use them with the --upgrade-paths flag command.
We recommend using the latest version of furyctl available. furyctl is backwards compatible with older versions and may include new upgrade paths in a release, even for older versions of the distribution and it may include additional bugfixes and patches to the Distribution.
To get the available upgrade paths for your cluster version run the following command:
furyctl get upgrade-paths
This will read the cluster configuration file and give you the available target versions you can upgrade the current version to.
You can get the paths for other versions and even other provider kinds too, using the --from and --kind flags:
furyctl get upgrade-paths --from 1.29.3 --kind OnPremises
See furyctl get upgrade-paths --help for more options.
3. Read the release notes for the target version
Read the release notes for the target version to understand the changes and potential impact on your cluster.
You can find the release notes for the target version at the SIGHUP Distribution GitHub releases page and here in the documentation site at the Releases page.
Take note of any breaking changes or changes that might affect your configuration and adjustments to the configuration file that you might need to make.
4. Check the cluster status
Before running the upgrade, it's recommended to check the cluster status to ensure that all nodes are healthy and ready for the upgrade.
You can use the following command to check the cluster status:
kubectl get nodes
and verify that all nodes are in the Ready state.
Check also that all the pods are in the Running state:
kubectl get pods --all-namespaces
5. Run the upgrade
To proceed with the upgrade, first adjust any parameters in the configuration file that you identified in the step number 3.
Then, change the value of .spec.distributionVersion on your furyctl.yaml file to the new vX.X.X version.
Finally, validate the configuration file against the new version schema using the following command:
furyctl validate config
We recommend to first upgrade the cluster and only afterwards change any configuration to avoid any potential issues, unless otherwise specified in the release notes.
Now you are ready to upgrade by applying the new configuration on the cluster with:
There are some additional flags that can be used when upgrading. See the Additional useful flags when upgrading section for more information.
furyctl apply --upgrade
Additional useful flags when upgrading
Skip pods running check
furyctl will check that all the pods are running after upgrading each node. This can cause some upgrades to fail, when for example there are some pods that are misbehaving but that are not critical to the upgrade (like non-infra workloads).
To skip the pods running check, use the --force pods-running-check flag.
OnPremises
In the OnPremises provider, during the upgrade, you can use the --skip-nodes-upgrade flag to skip the upgrade of the worker nodes and only do the upgrade of the control plane.
In a second moment, you can upgrade each worker, using the command:
furyctl apply --upgrade-node <node name>
where <node name> is the node's name in the furyctl.yaml file
Other flags
You can find all the available parameters with the furyctl apply --upgrade --help command.
Upgrade failures
If for some reason the upgrade process fails, you can run the upgrade command again:
furyctl apply --upgrade
and furyctl will start from the last successful phase.
If you want to start from a different phase, you can use the flag --start-from like this:
furyctl apply --upgrade --start-from pre-distribution
Custom Upgrade Paths
This is an advanced feature that allows you to upgrade your cluster to a version for which furyctl does not define an upgrade path starting from the current version. Notice that this feature is dangerous and should be used with caution.
You are responsible for ensuring that the upgrade path is correct and that the cluster is in a healthy state before starting the upgrade and after the upgrade.
To use this feature, you need to create a custom upgrade path. This path is folder that contains the scripts to be executed during the upgrade.
The folder structure is as follows:
custom-upgrade-path/
└── <kind>
└── <start version>-<end version>
├── post-infrastructure.sh.tpl
├── post-kubernetes.sh.tpl
├── post-distribution.sh.tpl
├── pre-distribution.sh.tpl
├── pre-infrastructure.sh.tpl
└── pre-kubernetes.sh.tpl
where kind is the kind of cluster (e.g. onpremises) and <start version> is the version from which you want to start the upgrade and <end version> is the version to which you want to upgrade. Not all files are required.
You can see the embedded upgrade paths in furyctl in the GitHub repository.
Manual upgrade procedure
To upgrade your cluster to the next version manually, follow the release notes for each module and installer.