Skip to main content
Version: Next

Upgrade SmoothGlue

This document is intended for System Integrators to upgrade SmoothGlue versions. Upgrading SmoothGlue versions upgrades the infrastructure, supported applications, and the platform logic.

danger

SmoothGlue upgrades must be sequential on the minor version. If you are at 6.10 you must upgrade to 6.11 then to 6.12 and so on.

Before the Upgrade​

  • Check the release notes for available SmoothGlue versions (make sure to read manual actions).
  • Get access to the Bastion Host the cluster was installed with.
  • Check the prerequisites list for other upgrade list items.
  • Notify your customers of an upgrade.

Go to the Smoothglue Environment directory and source the .env file to set the environment variables needed to upgrade:

cd example-org-run
source .env
# These are the variables that terragrunt will use. Make sure that the workspace name is correct or you will modify a different cluster
echo $TF_PLUGIN_CACHE_DIR
echo $TERRAGRUNT_ENV_FILE
echo $WORKSPACE_NAME
danger

Make sure you run source .env and that echo $ZARF_CONFIG is set to the complied/zarf-config.yaml file. If a Zarf configuration file is not provided it may cause catastrophic damage to the cluster including data loss.

Download the Next Version​

Retrieve the cluster's SmoothGlue version; determine the next minor version that should be used in the upgrade (eg: 6.10 --> 6.11) and export that as and environment variable called $SMOOTHGLUE_VERSION.

tip

$SMOOTHGLUE_VERSION is the version you are upgrading to, not the current version. Available versions can be found in release notes.

Clean up the old SmoothGlue artifacts from the previous version:

rm -rf infra-iac
rm zarf-package-smoothglue-amd64-*

Get the artifacts for the next SmoothGlue version and unpack the SmoothGlue IaC:

# This is the version we are going to upgrade to
export SMOOTHGLUE_VERSION="v6.x.x"
aws s3 cp s3://structsure-releases/$SMOOTHGLUE_VERSION/terraform_bundle-$SMOOTHGLUE_VERSION.tar.gz .
aws s3 cp s3://structsure-releases/$SMOOTHGLUE_VERSION/zarf-package-smoothglue-amd64-$SMOOTHGLUE_VERSION.tar.zst .
tar -xzvf terraform_bundle-$SMOOTHGLUE_VERSION.tar.gz

Review Release Note​

New features for SmoothGlue can be applied either via IaC configurations, new Big Bang configurations, or the Zarf configuration.

Manual actions may be required for an upgrade, please review the release notes.

Infrastructure as Code Upgrades​

danger

The following requires valid AWS credentials. If session-based AWS credentials are being used, please ensure the session duration is at least an hour long. It is recommended to obtain fresh AWS credentials before deploying SmoothGlue packages. If the AWS credentials expire during deployment of the SmoothGlue IaC package, the Terraform state files will become locked and may require manual intervention to unlock, potentially leading to orphaned cloud resources.

Execute Terragrunt​

Init and run a terragrunt run-all plan to see what changes will be made:

terragrunt run-all init
terragrunt run-all workspace select $WORKSPACE_NAME
terragrunt run-all plan
warning

Any manual changes made via the AWS console are going to be reverted. Review the output of the terragrunt run-all plan.

Once your organization accepts the proposed changes from the plan, run terragrunt run-all apply to apply those changes:

terragrunt run-all apply
# Outputs: infra-iac/outputs

Zarf Package Upgrade​

warning

Ensure a compatible version of Zarf is being used. SmoothGlue Release Notes will indicate what version of Zarf should be used with a given SmoothGlue version.

The following requires valid AWS credentials. If session-based AWS credentials are being used, please ensure the session duration is at least an hour long. It is recommended to obtain fresh AWS credentials before deploying SmoothGlue packages. Active AWS credentials are required to talk to EKS and the zarf package deploy can take a while, refresh your credentials now.

Setting Big Bang Values and Secrets​

SmoothGlue remembers previously provided configurations, any values already set from a previous upgrade will persist. If a custom change needs to be made to bigbang-values.yaml or bigbang-secrets.yaml, reference this guide.

In the previous step Terragrunt created output files in infra-iac/outputs that need to be merged with bigbang-values.yaml and bigbang-secrets.yaml. From the root of the SmoothGlue Environment directory run compile-config.sh to merge them:

./compile-config.sh
# Outputs: compiled/bigbang-values.yaml and compiled/bigbang-secrets.yaml
warning

Failure to merge custom values may result in missed IaC configurations.

The script made compiled/bigbang-values.yaml and compiled/bigbang-secrets.yaml, compare those to the in-cluster values and secrets. If compiled values are different than in-cluster values, the in-cluster values with be overrode.

Optional: add any differences found from in-cluster values to bigbang-values.yaml or bigbang-secrets.yaml and recompile to not override them.

Apply the Zarf Package​

If Jira and Confluence are configured HA they must be scaled to 1 during the upgrade:

zarf tools kubectl scale statefulsets jira -n jira --replicas=1
zarf tools kubectl scale statefulsets confluence -n confluence --replicas=1

Ensure that critical applications backups are complete.

Apply the package upgrade:

zarf package deploy zarf-package-smoothglue-amd64-$SMOOTHGLUE_VERSION.tar.zst
note

If a package upgrade fails the Big Bang Helm Release will be suspended and will error with: Package installation will not complete if Big Bang HelmRelease is already suspended. Failing.

Resume the Big Bang Helm Release before attempting to upgrade again:

zarf tools flux resume hr bigbang -n bigbang

Validate the Upgrade​

Deploying the package may take some time as it has to upload all of the container images, configure and deploy the applications into the cluster. To determine when an upgrade is done watch the Helm Releases reconcile:

zarf tools kubectl get HR -A

To fully validate a cluster upgrade was successful:

Post-Upgrade Tasks​

If Jira and Confluence are configured HA scale up their stateful sets:

zarf tools kubectl scale statefulsets jira -n jira --replicas=2
zarf tools kubectl scale statefulsets confluence -n confluence --replicas=2

If Jira and Confluence are configured for SSO the addon MiniOrange must be upgraded.