The SecurSpaces database
Citrix SecurSpaces™ stores its platform configuration and state in a MongoDB database. This database is the system of record for your deployment. If it is lost or corrupted, the platform cannot operate, even when every other component is healthy.
This section is for platform administrators who deploy and operate SecurSpaces. It assumes you are familiar with Kubernetes, Helm, and your MongoDB hosting model.
| Task | Page |
|---|---|
| Estimate how large the database will be | Database sizing |
| Back it up, on a schedule and before changes | Back up the database |
| Recover from a backup | Restore the database |
What the database stores
The SecurSpaces database (default name strong-network) holds the metadata and state that
define your platform. It does not store the contents of developer workspaces.
Workspace file systems, Docker volumes, and source code live on Kubernetes
Persistent Volume Claims (PVCs) and in your version control system, not in MongoDB.
The database stores, among other things:
-
Organizations, projects, and settings — organization, project, platform, and region configuration, section ordering, and setup checklists.
-
People and access — users, groups, roles, permissions, and identity-provider mappings.
-
Workspace definitions and state — workspace specifications, lifecycle status, schedules, SSH sessions, and the metadata that links a workspace to its project, owner, and persistent volumes.
-
Data mounts — data buckets and workspace mount-point definitions.
-
Integrations — connections to source control and other external services, plus their OAuth and access tokens.
-
Credentials and secrets — API keys and stored credentials. By default these are encrypted and stored in the database. If you configure HashiCorp Vault, secrets are stored in Vault instead of the database (see the next section).
-
Audit and event data — audit-trail and event-log records, plus usage, reporting, and compliance aggregates used by Insights and SIEM integration.
Note The exact collection layout is an internal implementation detail and can change between releases. Treat the database as an opaque unit for backup and restore — always back up and restore the whole database, not individual collections.
Where secrets live: database vs. HashiCorp Vault
By default, SecurSpaces encrypts secrets and credentials and stores them in the database, using an internal encryption key supplied at install time.
If you configure HashiCorp Vault (platform.hashicorpVault in the Helm values), SecurSpaces
stores secrets in Vault instead of the database.
This distinction matters for backups: when you use Vault, a database backup alone does not capture your secrets — you must also back up Vault. When you do not use Vault, the database backup contains the (encrypted) secrets, and you must protect both the backup and the encryption key.
Why the database is critical
The database is the single source of truth for platform configuration and state. SecurSpaces services are stateless by design and read their configuration from MongoDB on startup and during operation. As a result:
- No database, no platform. If MongoDB is unavailable, SecurSpaces services cannot start or serve requests, even when Kubernetes, networking, and storage are healthy.
- Configuration loss is unrecoverable without a backup. Organizations, projects, users, integrations, and workspace metadata exist only in the database. Losing it means rebuilding your platform configuration from scratch.
- Workspace access depends on it. Even though workspace file systems live on PVCs, the metadata that maps a developer to their workspace and its volumes lives in the database. Without that metadata, existing workspaces cannot be reattached.
For these reasons, treat the database as a tier-1, business-critical asset: run it with redundancy, back it up on a schedule, and test your restore procedure.
How the database is deployed
SecurSpaces supports three MongoDB hosting models. Your backup strategy depends on which one you use.
| Hosting model | When it is used | Who operates MongoDB |
|---|---|---|
| Internal MongoDB (Percona) | Deployed by SecurSpaces into your cluster using the Percona Operator. Used for proof of concept and evaluation, and in production where a managed service is not available. | You |
| External / hosted MongoDB | Recommended for production. SecurSpaces connects to an externally managed deployment such as MongoDB Atlas. | The managed service provider |
| Bitnami MongoDB (legacy) | Older internal deployments before the move to Percona. Being phased out. | You |
The updated chart bundles Percona Operator for MongoDB 1.23.0, Percona Server for MongoDB
7.0.37-20, and Percona Backup for MongoDB (PBM) 2.15.0. The operator manages the database as a
PerconaServerMongoDB custom resource with crVersion: 1.23.0.
By default the internal deployment uses:
- A single-member replica set (
rs0, size1). For production, increase the replica-set size to at least 3 for high availability. - A 10 GiB persistent volume for data.
- Resource requests of 500m CPU / 1 GiB memory and limits of 2000m CPU / 4 GiB memory.
Note:
A managed MongoDB service is the simplest route to production, because the provider handles redundancy, backups, and scaling for you.
The internal database is fully supported in production, and is the right choice for air-gapped deployments and environments where a managed service is not available. The difference is one of ownership rather than capability: you configure and operate its resilience. The defaults are set for a quick start — a single-member replica set, with backups available but not switched on — so plan for the following before you rely on it:
- A replica set with more than one member, so that the loss of a pod or node does not take the platform down. See Operating principles.
- Backups configured, scheduled, and restore-tested. See Back up the database.
- Resources sized for your own load rather than the defaults. See Sizing.
Internal Percona upgrades and backups
Upgrades from SDS 2026.9 (operator 1.20.1) must proceed one minor version at a time. After sds-cli upgrade,
run the supplied percona-upgrade/upgrade-percona.sh to back up the database, upgrade through 1.21.2 and
1.22.0, and apply the 1.23 CRDs. Then run the printed Helm command to complete the upgrade to 1.23.0.
Helm 3 does not upgrade existing CRDs; the script applies them explicitly. See
Upgrade for the full procedure and recovery commands.
Backups remain disabled by default. Configure perconaServerMongoDB.backup and
perconaServerMongoDB.serviceAccount in Helm values to enable backups and configure the database service
account. Operator 1.23 supports keyless GCS backups through GKE Workload Identity. Grant bucket access to
both the database and operator Kubernetes service accounts so backups, restores, and retention cleanup
work. See Back up the database.
Internal Percona MongoDB credentials
The Helm chart stores internal Percona MongoDB credentials in the
<release>-psmdb-secrets Kubernetes Secret. Leave the password values in
perconaServerMongoDB.adminUsers empty for normal operation. On the first install, the chart generates the
passwords. On later server-side Helm upgrades, the chart reuses the values from the live Secret instead of
generating new ones.
This behavior prevents routine upgrades from rotating the database passwords unexpectedly. If you explicitly set a password in the values file, that configured value takes precedence and rotates the corresponding credential. When the database administrator credential changes, SecurSpaces rolls the platform services that read it so they pick up the updated Secret.
Important:
lookupcan read the existing Secret only during a server-side Helm operation against the cluster. Client-side rendering, includinghelm template, client-side GitOps rendering, and--dry-run=client, cannot read the live Secret. In those modes, empty password values can still render as new generated passwords. Use server-side Helm upgrades for the internal Percona deployment, or pin the Percona database passwords in your values file.
Operating principles
- Run MongoDB with redundancy in production — a managed service, or a Percona replica set with more than one member that you operate — never a single member.
- Enable continuous / point-in-time backups, not only periodic snapshots.
- Store backups off-cluster and in a separate failure domain.
- Encrypt backups at rest and in transit, and restrict access to backup storage.
- Back up HashiCorp Vault alongside the database when Vault stores your secrets.
- Always back up before upgrades, migrations, and major configuration changes.
- Monitor database size. In-database audit data auto-expires after 360 days; forward events to your SIEM if you need retention beyond that window.
- Test restores on a schedule and document the runbook.