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..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 @@ -181,6 +181,77 @@ 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 (backfill) 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 `backfill` portion will be restored while the system is running. 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 +---- + +==== 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 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.