Upgrade
Upgrade SecurSpaces by running the Docker-based installer, preparing the internal database if you use Percona, and applying the Helm command printed by the installer.
For an upgrade from SDS 2026.9 to the chart with Percona Operator 1.23.0, run the supplied Percona upgrade script before Helm. Percona supports operator upgrades one minor version at a time. The script takes the database through 1.21.2 and 1.22.0; Helm completes the upgrade to 1.23.0.
Deployments using external MongoDB follow the usual installer and Helm flow without the Percona step.
Prerequisites
Before starting the upgrade, ensure the following:
- A recent backup of the SecurSpaces configuration database. See Back up the database.
- Access to the terminal with Docker installed.
- Current working directory
${PWD}contains the correct configuration file for your existing deployment. - Necessary permissions to run Docker and apply Helm upgrades to your cluster.
- Kubernetes context is correctly configured.
- For internal Percona,
kubectland permission to apply cluster-scoped custom resource definitions (CRDs), update the operator Deployment and database custom resource, and access database pods for the backup. - Space in the working directory for the
mongodumparchive written by the upgrade script. - Only the intended Percona operator watches this database. Check for other operators watching all namespaces.
Run the Installer
Launch the installer for the target release. Replace <target-version> with the installer version that
supplies the chart with Percona Operator 1.23.0:
docker run -it --rm -v ${PWD}:/strong-network/shared \
strongnetwork/strong_installer:<target-version>
<!--NeedCopy-->
Note:
${PWD}refers to your current working directory. This directory must contain the configuration file used in your current deployment.
Execute the Upgrade Command
Once inside the Docker container, run the upgrade command using your existing configuration file:
sds-cli upgrade -c config_<your-current-version>.yaml
<!--NeedCopy-->
Example:
sds-cli upgrade -c config_2026.9.0.yaml
<!--NeedCopy-->
The installer downloads the new chart, updates the configuration, prints the usual
helm upgrade --install ... release command, and pushes the images. There are no new Percona questions
in sds-cli upgrade.
If platform.deployPerconaMongoDB is unset or true, it also copies the Percona upgrade kit to
/strong-network/shared/percona-upgrade/ and prints the upgrade, restore, and backup-delete instructions.
The kit contains three scripts and the CRDs for 1.21.2 and 1.22.0. A rerun replaces this copy so that the
scripts match the installer version. The directory is available as ./percona-upgrade/ on the host through
the shared-directory mount.
For external MongoDB (platform.deployPerconaMongoDB: false), the Percona kit and instructions are skipped.
Prepare internal Percona MongoDB for 1.23
Run this step after sds-cli upgrade finishes and before the printed Helm command. Use a terminal with
access to the cluster, and work from the shared directory containing the chart and percona-upgrade/.
The script takes the namespace, Helm release name, and chart archive path, in that order:
./percona-upgrade/upgrade-percona.sh <namespace> <release> ./ninjahchart-<version>.tgz
<!--NeedCopy-->
For namespace default and release release:
./percona-upgrade/upgrade-percona.sh default release ./ninjahchart-<version>.tgz
<!--NeedCopy-->
The script:
- Exits with “nothing to do” if the database is already on 1.23.
- Checks that the supplied chart contains the 1.23 CRDs.
- Asks you to enter
yes, waits for the database to beready, and writes amongodumpbackup to the current directory. Keep this archive until you have validated the platform. - Upgrades through the intermediate versions below. At each step it applies that version’s CRDs, sets
the operator image, patches the database custom resource (
crVersion, MongoDB image, and PBM image), and waits forreadywith every database pod on the new image. - Applies the 1.23 CRDs from the chart and scales the old operator to
0, ready for Helm to start 1.23.0.
| Stage | Operator and database crVersion
|
MongoDB image version |
|---|---|---|
| Starting deployment (SDS 2026.9) | 1.20.1 | 7.0.26-14 |
| First script step | 1.21.2 | 7.0.28-15 |
| Second script step | 1.22.0 | 7.0.30-16 |
| Final Helm upgrade | 1.23.0 | 7.0.37-20 |
CRDs must be applied outside Helm. Helm 3 does not upgrade existing CRDs. Running the script performs these explicit CRD updates, including the 1.23 CRDs needed before the final Helm upgrade.
Each version step is a rolling restart. Expect a write pause of up to about 15 seconds per step; plan the upgrade window accordingly.
Apply the Helm Upgrade
After the Percona script completes successfully, run the Helm command printed by the installer. For external MongoDB, run it directly after the installer finishes.
Helm starts Percona Operator 1.23.0, which moves the database to crVersion: 1.23.0, MongoDB
7.0.37-20, and PBM 2.15.0.
The chart blocks an existing Percona deployment that has not reached 1.22 or lacks the required 1.23 CRDs. An already-upgraded 1.23 deployment can undergo subsequent Helm upgrades.
Post-Upgrade Verification
Once the Helm upgrade is applied:
-
Verify that all pods are running and healthy:
kubectl get pods -n <your-namespace> <!--NeedCopy--> -
Check service availability and logs:
kubectl logs <pod-name> -n <your-namespace> <!--NeedCopy--> - Confirm that the platform version has been updated successfully.
-
For Percona, confirm the database is
ready,crVersionis1.23.0, and database pods use MongoDB7.0.37-20and PBM2.15.0:kubectl get psmdb <release>-psmdb-db -n <namespace> kubectl get psmdb <release>-psmdb-db -n <namespace> -o yaml kubectl get pods -n <namespace> -o wide <!--NeedCopy--> - Sign in as the platform administrator and confirm organizations, projects, and services are available.
- If backups are enabled, confirm that they continue to complete and the storage, schedule, and PITR settings are retained. For keyless GCS backups, see Back up the database.
Clean up or restore the upgrade backup
After platform validation, delete the upgrade backup from the directory where you ran the script:
./percona-upgrade/delete-percona-backup.sh
<!--NeedCopy-->
If you need to recover the data, use the restore script with the archive created during the upgrade:
./percona-upgrade/restore-percona-backup.sh default release <backup>.archive.gz
<!--NeedCopy-->
Replace default and release with your namespace and Helm release. This restores data only; it does
not downgrade the operator, CRDs, MongoDB, or PBM. Follow the quiesce and validation guidance in
Restore the database.
Troubleshooting
Helm blocks the Percona upgrade
Running Helm before preparing Percona can produce the following error (wrapped here for readability):
Error: UPGRADE FAILED: execution error at (ninjahchart/templates/percona-instance.yaml:14:4):
The Percona MongoDB database protein-psmdb-db is on operator version 1.20.1 with CRDs unknown.
This chart needs it on 1.22 or later with CRDs 1.23:
run percona-upgrade/upgrade-percona.sh from the SDS installer first.
<!--NeedCopy-->
Run upgrade-percona.sh with the correct namespace, release, and new chart, then rerun the printed Helm
command. Do not skip the intermediate operator versions or the explicit CRD updates.
Conflicting Percona operators
If the database does not settle at the expected version or become ready, check whether another Percona
operator watches the same namespace, including operators configured to watch all namespaces. A leftover
operator can reconcile the database back to a competing configuration. Identify and scale the unintended
operator to 0 before continuing.
Other upgrade issues
If you encounter issues during the upgrade:
- Review the installer output for error messages.
- Ensure your configuration file matches the expected format.
- Check Docker and Kubernetes logs for additional context.