STAC-24630: Add stackgraph backup v2 documentation [DRAFT] - #360
Open
craffit wants to merge 3 commits into
Open
Conversation
✅ Deploy Preview for suse-obs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
viliakov
reviewed
Jul 20, 2026
viliakov
reviewed
Jul 20, 2026
viliakov
reviewed
Jul 21, 2026
viliakov
left a comment
viliakov
left a comment
Contributor
There was a problem hiding this comment.
A few documentation-style points on the new v2 sections. The surrounding docs use third-person, imperative voice and avoid first-person/marketing phrasing, so the new prose reads a bit out of style. Also flagged two typos/grammar fixes and a content mismatch with the Helm chart default. Details inline.
|
|
||
| === 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`. |
Contributor
There was a problem hiding this comment.
Style + content on this paragraph:
- First-person voice: "we make backups" — the rest of the docs are third-person. Suggest: "As of {next-release-version}, backups are made in two versions, v1 and v2."
- Marketing/anthropomorphizing: "battle-tested", "fast and feature-rich but has to prove itself". Suggest something neutral like: "v1 is the established but slower system; v2 is faster and adds incremental backups but is newer. By default both run so v2 can be validated alongside v1."
- Content mismatch: this says the default is
all, but helm-charts-internal#100 setsbackup.stackGraph.scheduled.implementationdefault tov1(only v1 runs by default; v2 is suspended). The docs and chart need to agree — either change the chart default toallor update this to say v1-only by default.
Contributor
There was a problem hiding this comment.
Ignore Content mismatch: this says the default is all, but helm-charts-internal#100 sets backup.stackGraph.scheduled.implementation default to v1 (only v1 runs by default; v2 is suspended). The docs and chart need to agree — either change the chart default to all or update this to say v1-only by default.. The AI missed you comment in the helm-charts pr....
Collaborator
Author
There was a problem hiding this comment.
I will now merge helm with v1 but move to 'all' when i release this feature. I will be testing first on noghtly while v2 is disabled for end-users
Collaborator
Author
There was a problem hiding this comment.
applied suggestions
|
|
||
| == 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. |
Contributor
There was a problem hiding this comment.
First-person voice + jargon: "we are rolling out" and "we'll sunset v1 backups". Suggest: "SUSE Observability {next-release-version} introduces v2 of StackGraph backup/restore. Both v1 and v2 backups are created until v2 is considered stable, after which v1 backups will be discontinued."
|
|
||
| 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. |
Contributor
There was a problem hiding this comment.
Tone down the marketing phrasing "offer significant improvements". Suggest: "v2 backups improve backup and restore speed and add incremental backups." Also note "V2" here vs "v2" elsewhere — standardize on lowercase v2.
|
|
||
| === List StackGraph v2 backups | ||
|
|
||
| To list the StackGraph V2 backups, execute the following command: |
Contributor
There was a problem hiding this comment.
Capitalization: "StackGraph V2" should be "StackGraph v2" to match the rest of the document.
|
|
||
| === 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: |
Contributor
There was a problem hiding this comment.
Two nits:
- "takes down the system" is informal — prefer "takes the system offline".
- Quoting is inconsistent:
'live'/'backfill'are single-quoted here but`backfill`is in backticks in the same paragraph. Use backticks for literals throughout to match the rest of the doc.
|
|
||
| ==== 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. |
Contributor
There was a problem hiding this comment.
Grammar + consistency:
- "fails due to instability the cluster" → "fails due to instability of the cluster".
- "CTRL-C" — the existing doc uses "Ctrl+C"; standardize on that.
| ==== 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. |
Contributor
There was a problem hiding this comment.
Informal phrasing: "This command is really a last resort" → "This command is a last resort".
|
|
||
| * `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. |
Contributor
There was a problem hiding this comment.
Typo + consistency:
- "incling a
--waitoption" → "including". - "Ctrl-C" → "Ctrl+C" to match the existing doc.
viliakov
approved these changes
Jul 21, 2026
fvlankvelt
reviewed
Jul 22, 2026
|
|
||
| [,bash] | ||
| ---- | ||
| Setting up port-forward to suse-observability-minio:9000 in namespace <NAMESPACE>... |
Contributor
There was a problem hiding this comment.
is the minio still there? I thought we switched to s3proxy?
fvlankvelt
reviewed
Jul 22, 2026
|
|
||
| [,bash] | ||
| ---- | ||
| sts-backup stackgraph-v2 list --namespace <NAMESPACE> |
Contributor
There was a problem hiding this comment.
is the namespace argument optional? We can default to suse-observability
fvlankvelt
reviewed
Jul 22, 2026
|
|
||
| It can be configured to store the backups in three locations: | ||
|
|
||
| * xref:/setup/data-management/backup_restore/backup_enable.adoc[AWS S3] |
Contributor
There was a problem hiding this comment.
this is a confusing set of links
fvlankvelt
approved these changes
Jul 22, 2026
akashraj4261
reviewed
Aug 4, 2026
|
|
||
| === Enable/disable v1 and v2 backups | ||
|
|
||
| As of {next-release-version}, backups are made in two versions, v1 and v2. The old v1 is the established but slower system; v2 is faster and adds incremental backups but is newer. By default both run so v2 can be used while having v1 to fall back on. 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`. |
Contributor
There was a problem hiding this comment.
Suggested change
| As of {next-release-version}, backups are made in two versions, v1 and v2. The old v1 is the established but slower system; v2 is faster and adds incremental backups but is newer. By default both run so v2 can be used while having v1 to fall back on. 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`. | |
| As of {next-release-version}, backups are made in two versions, v1 and v2. v1 is the older, established but slower system whereas v2 is the newer, faster system that adds incremental backups. Since both systems run, by default, v2 can be primarily used while having v1 to fall back on. 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`. |
"this can be done through" - What is 'this' here? Is it "backup can be performed"?
akashraj4261
reviewed
Aug 4, 2026
|
|
||
| == Configuration and topology data v2 (StackGraph) | ||
|
|
||
| SUSE Observability {next-release-version} introduces v2 of StackGraph backup/restore. Both v1 and v2 backups are created until v2 is considered stable, after which v1 backups will be discontinued. |
Contributor
There was a problem hiding this comment.
Suggested change
| SUSE Observability {next-release-version} introduces v2 of StackGraph backup/restore. Both v1 and v2 backups are created until v2 is considered stable, after which v1 backups will be discontinued. | |
| {stackstate-product-name} {next-release-version} introduces v2 of StackGraph backup/restore. Both v1 and v2 backups are created until v2 is considered stable, after which v1 backups will be discontinued. |
Are there any parameters that we might want to suggest keeping an eye on to ensure the stability of v2? Or is this something the customers will always know?
akashraj4261
reviewed
Aug 4, 2026
|
|
||
| SUSE Observability {next-release-version} introduces v2 of StackGraph backup/restore. Both v1 and v2 backups are created until v2 is considered stable, after which v1 backups will be discontinued. | ||
|
|
||
| V2 backups improve backup and restore speed and add 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| V2 backups improve backup and restore speed and add 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. | |
| V2 backups improve backup and restore speed and add incremental backups. Also, the StackGraph v2 restore procedure allows restoring historical (backfill) data while the system is running resulting in quicker system backups. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds documentation for stackgraph backup/restore v2