Upgrading Structsure Enterprise
This guide provides instructions on how to upgrade an instance of Structsure to its latest version.
Prerequisites
Before upgrading Structsure, ensure that you meet the following prerequisites.
Validate Current Version of Structsure
Determining the existing version of Structsure is vital for a successful upgrade, as only incremental version upgrades are supported. Use the following command to retrieve the current Structsure version:
kubectl get configuration structsure-enterprise -o jsonpath='{.spec.package}'
Assess Available Storage
During the deployment of Structsure, Zarf utilizes the /tmp directory to create logs, unpack images, and allocate other necessary resources. Insufficient space in this directory may lead to upgrade complications. Verify adequate storage availability in the /tmp directory before initiating the upgrade.
Export Zarf Config
Ensure that your Zarf configuration file is exported for the cluster you are planning on upgrading.
export ZARF_CONFIG=/home/user/my-structsure-config.yaml
It is recommended to keep all configuration files related to a cluster in the same directory in the case you have multiple clusters deployed.
If a Zarf configuration file is not provided prior to upgrading, this may cause catastrophic damage to your cluster including data loss.
Upgrade Installation
After satisfying all prerequisites, you can initiate the upgrade using the Zarf package with the following command:
zarf package deploy zarf-package-structsure-amd64-5.0.1.tar.zst --no-progress --confirm
Note that all previous custom values and secrets that are applied to the cluster are preserved and carried over automatically during the upgrade. If desired, these values can be overridden by passing in the BIGBANG_VALUES_FILE and BIGBANG_SECRETS_FILE, as described in How to Override Big Bang Values.
Upon successful completion of the upgrade, all web applications should remain accessible via their existing URLs.
Post-Upgrade Tasks
After the upgrade, you may want to consider the following optional post-upgrade task.
Zarf Cleanup
Once the upgrade is successfully completed, you may safely remove the decompressed Zarf folder and delete any temporary files residing in the /tmp directory.
By carefully following this guide, you will be well-equipped for a smooth upgrade to Structure's latest version.
Note for Upgrading a Cluster that Ever Ran Structsure Versions v5.0.1 to v5.3.0
Note that if you have an existing cluster that was ever running any Structsure versions between (and including) v5.0.1 to v5.3.0, you will need to use the exact same example procedure shown in Unsetting Previously Overridden Config or Secret Values to remove the pinned GitLab 7.7.0-bb.0 tag when upgrading Structsure. These versions have the bug fix for updating GitLab webservice to 16.7.0 to patch cve 121ea7b. Unfortunately, this fix resulted in a change to the gitlab-overrides configmap (instead of the gitlab-values configmap). This requires a one-time manual change to unset this value so that GitLab can default back to the Big Bang chart value when upgrading to Structsure version v5.4.0 onwards.