From ff47103b4501c62ab074f2e4f3b3aa6517a25459 Mon Sep 17 00:00:00 2001 From: Bram Schuur Date: Thu, 16 Jul 2026 16:31:12 +0200 Subject: [PATCH 1/2] STAC-24630: Add stackgraph backup v2 documentation --- .../backup_restore/backup_enable.adoc | 13 ++++ .../backup_restore/backup_restore.adoc | 63 +++++++++++++++++++ 2 files changed, 76 insertions(+) diff --git a/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_enable.adoc b/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_enable.adoc index ff75a3695..15694c536 100644 --- a/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_enable.adoc +++ b/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_enable.adoc @@ -368,6 +368,19 @@ backup: schedule: '0 0 1 1 1970' # January 1, 1970 (epoch start) ---- + +=== Enabling/disabling v1 and v2 backups + +As of {next-release-version} we make backups in two versions, v1 and v2. The old v1 system is battle-tested but slow, the v2 system is fast and feature-rich but has to prove itself, hence both systems are active by default. If for some reason one of the systems should be disabled, this can be done through `backup.stackGraph.scheduled.implementation` which can be `v1`, `v2` or `all`. The default is `all`. + +[,yaml] +---- +backup: + stackGraph: + scheduled: + implementation: 'v2' # Example: disable v1 to save space. +---- + == Settings Settings (Configuration previously) includes installed instances of StackPacks with their configuration and other customizations created by the user, such as monitors, custom views, and service tokens. diff --git a/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_restore.adoc b/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_restore.adoc index 7b12920e8..7c884fb21 100644 --- a/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_restore.adoc +++ b/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_restore.adoc @@ -181,6 +181,69 @@ The `check-and-finalize` command: If a restore running without `--background` is interrupted (for example, by Ctrl+C), you must run `check-and-finalize` to scale up deployments and clean up resources. ==== +== Configuration and topology data v2 (StackGraph) + +Since SUSE Observability {next-release-version} we are rolling out v2 of StackGraph backup/restore. For now both v1 and v2 backups will be made, until v2 is deemed completely stable, at which point we'll sunset v1 backups. + +V2 backups offer significant improvements in backup and restore speed, as well as incremental backups. Also, the stackgraph v2 restore procedure allows for restoring historical data while the system is running, which means much quicker time to get the system back up. + +=== List StackGraph v2 backups + +To list the StackGraph V2 backups, execute the following command: + +[,bash] +---- +sts-backup stackgraph-v2 list --namespace +---- + +Replace `` with the namespace where {stackstate-product-name} is installed. + +The output should look like this: + +[,bash] +---- +Setting up port-forward to suse-observability-minio:9000 in namespace ... +✓ Port-forward established successfully +Listing Stackgraph backups in bucket 'sts-stackgraph-backup'... +NAME LAST MODIFIED +sts-backup-20251128-0300.graph.v2 2025-11-28 03:08:42 UTC +---- + +The timestamp when the backup is taken is part of the backup name. + + +=== Restore a StackGraph v2 backup + +The restore has a 'live' and 'backfill' portion of the backup. The 'live' part takes down the system and will restore the latest data. After the 'live' part is done, the system will scale up and is accessible by end-users. The following message appears to signify when the system is accessible again: + +[,bash] +---- +The system is back up and accessible. Continuing with backfilling historical data, this will happen while the system is running. +During this process not all historical data might be available. +---- + +To restore a StackGraph v2 backup, use one of the following commands: + +==== Restore a specific backup + +[,bash] +---- +sts-backup stackgraph-v2 restore --namespace --archive +---- + +==== Restore the latest backup + +[,bash] +---- +sts-backup stackgraph-v2 restore --namespace --latest +---- + +==== Common flags + +* `--yes` or `-y` - Skip confirmation prompt (useful for automation) + +==== + == Settings Settings backups include installed StackPacks with their configuration and other customizations created by the user, such as monitors, custom views, and service tokens. Settings backups are lightweight (typically only several megabytes) and quick to restore with minimal downtime. From 9f365d3fb6453841949971aa25dbd0ca9bee0246 Mon Sep 17 00:00:00 2001 From: Bram Schuur Date: Mon, 20 Jul 2026 09:40:45 +0200 Subject: [PATCH 2/2] STAC-24630: Add some more docs on stackgraph v2 commands --- .../backup_restore/backup_restore.adoc | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_restore.adoc b/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_restore.adoc index 7c884fb21..13ed5e342 100644 --- a/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_restore.adoc +++ b/docs/latest/modules/en/pages/setup/data-management/backup_restore/backup_restore.adoc @@ -185,7 +185,7 @@ If a restore running without `--background` is interrupted (for example, by Ctrl Since SUSE Observability {next-release-version} we are rolling out v2 of StackGraph backup/restore. For now both v1 and v2 backups will be made, until v2 is deemed completely stable, at which point we'll sunset v1 backups. -V2 backups offer significant improvements in backup and restore speed, as well as incremental backups. Also, the stackgraph v2 restore procedure allows for restoring historical data while the system is running, which means much quicker time to get the system back up. +V2 backups offer significant improvements in backup and restore speed, as well as incremental backups. Also, the StackGraph v2 restore procedure allows for restoring historical (backfill) data while the system is running, which means much quicker time to get the system back up. === List StackGraph v2 backups @@ -211,10 +211,9 @@ sts-backup-20251128-0300.graph.v2 2025-11-28 03:08:42 UTC The timestamp when the backup is taken is part of the backup name. - === Restore a StackGraph v2 backup -The restore has a 'live' and 'backfill' portion of the backup. The 'live' part takes down the system and will restore the latest data. After the 'live' part is done, the system will scale up and is accessible by end-users. The following message appears to signify when the system is accessible again: +The restore has a 'live' and 'backfill' portion of the backup. The 'live' part takes down the system and will restore the latest data. After the 'live' part is done, the system will scale up and is accessible by end-users. The `backfill` portion will be restored while the system is running. The following message appears to signify when the system is accessible again: [,bash] ---- @@ -238,11 +237,20 @@ sts-backup stackgraph-v2 restore --namespace --archive sts-backup stackgraph-v2 restore --namespace --latest ---- -==== Common flags +==== Additional flags * `--yes` or `-y` - Skip confirmation prompt (useful for automation) +[NOTE] ==== +If a restore running is interrupted (for example, by Ctrl+C), you must run `check-and-finalize` to scale up deployments and clean up resources. If the backfill phase of restoring was not started yet, also `sts-backup stackgraph-v2 backfill` must be run to complete restoring `backfill` data. +==== + +==== Additional commands + +* `sts-backup stackgraph-v2 backfill`. The restore command will automatically restore both the `live` and `backfill` portion of a backup. If, however, the restore command gets interrupted (through CTRL-C) or fails due to instability the cluster, this command can be used to restart the backfill job, restoring the `backfill` portion of the data. +* `sts-backup stackgraph-v2 abort`. If restoring the `backfill` portion of a backup cannot be recovered or is lost somehow, `abort` can be used to wrap up the restore command with the data that got already ingested successfully. This command is really a last resort and should not be needed in normal operation. +* `sts-backup stackgraph-v2 check-and-finalize`. When any command (`restore`/`backfill`/`abort`) gets interrupted with Ctrl-C, the `check-and-finalize` command can be used to keep track of its progress, incling a `--wait` option which allows waiting for the job to finish. == Settings