Revamp Snapshots section: major restructuring (largely by hand), and support for `lstk` by peter-smith-phd · Pull Request #800 · localstack/localstack-docs

peter-smith-phd · 2026-07-20T22:44:51Z

Migrate the entire "Snapshots" section to use lstk, and perform major restructuring on the existing content.

The Snapshots section had grown organically around Cloud Pods and the legacy localstack CLI. Content had been added over time, in a way that didn't make sense to many readers I talked with. In addition to migrating to lstk, we needed to rethink how the content was structured, making it far easier for novice readers to understand the important concepts.

This change restructures the section around the user's actual goal — where do I want to put my snapshot? — and moves every example to lstk.

Note that most of this work was done by Peter, using AI as an assistant. I reviewed all the content, made conscious decisions about how it should be restructured, and wrote many of the paragraphs myself. In many cases it was easier to write it myself, than to instruct Claude on what should have been written. In the end, Claude was great for testing examples and sanity-testing my grammar.

What changed

Page structure — one page per destination, ordered as a reading path:

Page	Purpose
Overview	What snapshots are and why they help
Saving snapshots locally	Save/load a snapshot file on disk
Saving snapshots to Cloud Pods	Share snapshots via the LocalStack platform
Saving snapshots to S3	Save to your own bucket (data-sovereignty cases)
Merging snapshots	Merge strategies, extracted to their own page
Persistence	Automatic snapshotting for durability
Service coverage	Compatibility rules and per-service support

Removed cli-commands.md (now covered by the lstk CLI guide), launchpad.md (no longer works), and export-import-state.md (replaced by "saving locally").

cloudflare-workers-and-pages · 2026-07-20T22:46:21Z

Deploying localstack-docs with Cloudflare Pages

Latest commit:	`2c0ee13`
Status:	✅ Deploy successful!
Preview URL:	https://8911d81f.localstack-docs.pages.dev
Branch Preview URL:	https://pro-275-rewrite-snapshots-se.localstack-docs.pages.dev

View logs

…o other pages yet. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…itch documented commands to the lstk CLI Move the Remotes section from cloud-pods.mdx into other-snapshot-storage-options.md, and the (now Snapshot Merging) section into save-snapshots-locally.md. Update save-snapshots-locally.md to document the lstk snapshot save/load commands instead of the legacy localstack CLI, and fix inbound links to the relocated sections across the docs. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Work in progress towards rewriting cloud-pods.mdx around the lstk CLI's snapshot commands instead of the legacy localstack pod CLI, plus a new workflow diagram and a remotes miscellaneous note. Not yet complete (contains a TBD placeholder). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Renames several cloud-pods.mdx headings to better distinguish the Cloud Pod (the repository) from the snapshot (the saved emulator state), fixes the one cross-doc link that referenced the old heading anchor, and cleans up assorted grammar/typo/consistency issues found in a pass over the page (subject-verb agreement, singular/plural Cloud Pod references, a broken image markdown tag, a directory-name typo, and stale export/import wording left over after the heading renames).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Delete launchpad.md and its images, drop the dead card link from the Snapshots overview, and repoint legacy launchpad redirects to the Snapshots overview page instead of the now-removed page. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Rebuild the "Using the lstk CLI" section around a single worked example that builds a Cloud Pod over three versions, adding one service at a time (S3, then SQS, then SNS). Document the `snapshot versions` command and loading a specific version with the `:<version>` suffix. All command output in the section is captured from a real run against a fresh emulator, with the LocalStack version normalised to 2026.8.0. Also remove the End-to-End Encryption section, which is no longer part of this page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

athomas-lstk · 2026-08-07T16:40:59Z

 ```

-More information about state import and export [here](/aws/developer-tools/snapshots/export-import-state).
+More information about state import and export [here](/aws/developer-tools/snapshots/saving-snapshots-locally).


Suggested change

More information about state import and export [here](/aws/developer-tools/snapshots/saving-snapshots-locally).

More information about state import and export [here](/aws/developer-tools/snapshots/cloud-pods/).

Given the example above this is using the Cloud Pod backend, should we link to the cloud pods page instead?

Agreed, that makes sense. Also, the text should say "More information about Cloud Pods", because the incorrect mention of "state import and export" would imply that it's local files only (that's the old name for "saving locally").

athomas-lstk · 2026-08-07T17:07:28Z

 - **License activation**: The standard image performs online activation using your `LOCALSTACK_AUTH_TOKEN`. See [Auth Token](/aws/getting-started/auth-token) for activation behavior and fallbacks.
 - **Event reporting (telemetry)**: Used for Stack Insights and related usage analytics. You can disable this via `DISABLE_EVENTS=1`.
- **Cloud Pods (platform remote)**: Saving/loading pods against the default platform remote uses LocalStack-managed infrastructure. For stricter data residency, configure your own Cloud Pods [remote storage](/aws/developer-tools/snapshots/cloud-pods#remotes).
+- **Cloud Pods (platform remote)**: Saving/loading pods against the default platform remote uses LocalStack-managed infrastructure. For stricter data residency, consider other [remote storage options](/aws/developer-tools/snapshots/saving-snapshots-to-s3).


LocalStack-managed infrastructure

This probably goes beyond the the scope of this PR, but I wonder if it's worth mentioning somewhere in our docs the region in which the LocalStack platform (Console + hosted resources like CloudPods and Ephem Instances) is hosted (e.g. eu-central-1?). From my experience, enterprises like to know this and it can help them think about which Snapshot backend is right for them. Perhaps we could add a note on this page: https://docs.localstack.cloud/aws/connecting/console/ and then link to it from here, Cloud Pods page, and Ephemeral Instances page.

Thanks, I'll definitely add that here, but it probably should go in a Console-centric page as well. The Cloud Pods feature is the only part of the Console that has long-term storage of data, so the eu-central-1 fact is important to mention.

athomas-lstk · 2026-08-07T17:28:39Z

 /user-guide/aws/cloudfront/ /aws/services/cloudfront/ 301
 /applications/note-taking-application-using-aws-sdk-for-javascript/ https://github.com/localstack-samples/sample-notes-app-dynamodb-lambda-apigateway 301
-/user-guide/state-management/export-import-state/ /aws/developer-tools/snapshots/export-import-state/ 301
+/user-guide/state-management/export-import-state/ /aws/developer-tools/snapshots/save-snapshots-locally/ 301


Suggested change

/user-guide/state-management/export-import-state/ /aws/developer-tools/snapshots/save-snapshots-locally/ 301

/user-guide/state-management/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

Thanks for catching this! I had asked Claude to change the name of the file, and update incoming links, but for some reason it didn't make the _redirects change. I'll go back and review all the relevant changes, to make sure this wasn't the only thing that was missed.

athomas-lstk · 2026-08-07T17:29:01Z

 /user-guide/aws/cloudfront /aws/services/cloudfront/ 301
 /applications/note-taking-application-using-aws-sdk-for-javascript https://github.com/localstack-samples/sample-notes-app-dynamodb-lambda-apigateway 301
-/user-guide/state-management/export-import-state /aws/developer-tools/snapshots/export-import-state/ 301
+/user-guide/state-management/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301


Suggested change

/user-guide/state-management/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301

/user-guide/state-management/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

athomas-lstk · 2026-08-07T17:29:58Z

-/aws/capabilities/state-management/export-import-state/ /aws/developer-tools/snapshots/export-import-state/ 301
+/aws/capabilities/state-management/cli-commands /aws/developer-tools/running-localstack/lstk/#snapshot 301
+/aws/capabilities/state-management/cli-commands/ /aws/developer-tools/running-localstack/lstk/#snapshot 301
+/aws/capabilities/state-management/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301


Suggested change

/aws/capabilities/state-management/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301

/aws/capabilities/state-management/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

athomas-lstk · 2026-08-07T17:30:21Z

+/aws/capabilities/state-management/cli-commands /aws/developer-tools/running-localstack/lstk/#snapshot 301
+/aws/capabilities/state-management/cli-commands/ /aws/developer-tools/running-localstack/lstk/#snapshot 301
+/aws/capabilities/state-management/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301
+/aws/capabilities/state-management/export-import-state/ /aws/developer-tools/snapshots/save-snapshots-locally/ 301


Suggested change

/aws/capabilities/state-management/export-import-state/ /aws/developer-tools/snapshots/save-snapshots-locally/ 301

/aws/capabilities/state-management/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

athomas-lstk · 2026-08-07T17:31:04Z

 /aws/capabilities/state-management/ /aws/developer-tools/snapshots/ 301
-/aws/capabilities/state-management/launchpad /aws/developer-tools/snapshots/launchpad/ 301
-/aws/capabilities/state-management/launchpad/ /aws/developer-tools/snapshots/launchpad/ 301
+/aws/developer-tools/snapshots/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301


Suggested change

/aws/developer-tools/snapshots/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301

/aws/developer-tools/snapshots/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

athomas-lstk · 2026-08-07T17:31:13Z

-/aws/capabilities/state-management/launchpad /aws/developer-tools/snapshots/launchpad/ 301
-/aws/capabilities/state-management/launchpad/ /aws/developer-tools/snapshots/launchpad/ 301
+/aws/developer-tools/snapshots/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301
+/aws/developer-tools/snapshots/export-import-state/ /aws/developer-tools/snapshots/save-snapshots-locally/ 301


Suggested change

/aws/developer-tools/snapshots/export-import-state/ /aws/developer-tools/snapshots/save-snapshots-locally/ 301

/aws/developer-tools/snapshots/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

athomas-lstk · 2026-08-07T17:31:47Z

-/aws/configuration/state-management/export-import-state/ /aws/developer-tools/snapshots/export-import-state/ 301
-/aws/configuration/state-management/launchpad /aws/developer-tools/snapshots/launchpad/ 301
-/aws/configuration/state-management/launchpad/ /aws/developer-tools/snapshots/launchpad/ 301
+/aws/configuration/state-management/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301


Suggested change

/aws/configuration/state-management/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301

/aws/configuration/state-management/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

athomas-lstk · 2026-08-07T17:31:56Z

-/aws/configuration/state-management/launchpad /aws/developer-tools/snapshots/launchpad/ 301
-/aws/configuration/state-management/launchpad/ /aws/developer-tools/snapshots/launchpad/ 301
+/aws/configuration/state-management/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301
+/aws/configuration/state-management/export-import-state/ /aws/developer-tools/snapshots/save-snapshots-locally/ 301


Suggested change

/aws/configuration/state-management/export-import-state/ /aws/developer-tools/snapshots/save-snapshots-locally/ 301

/aws/configuration/state-management/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

athomas-lstk · 2026-08-07T17:35:29Z

-
-<PersistenceCoverage client:load />
-
-### Terminology


should this section carry over to the Service Coverage page, given we moved the PersistenceCoverage table there?

I had deliberately excluded it because this describes our internal engineering processes rather than describing the actual product feature. But, I now see there's a column in the service coverage page that uses this term, so on second thoughts I'll move it across.

athomas-lstk · 2026-08-07T17:36:34Z

-
-Please help us improve persistence support by reporting bugs on our [GitHub Discussion](https://github.com/orgs/localstack/discussions/new/choose).
-
-## Technical Details


Looks like this section didn't get carried over to Service Coverage page. Was that on purpose?

Looks like this section didn't get carried over to Service Coverage page. Was that on purpose?

Yes, it was excluded on purpose. Not only has the internal implementation changed recently (making this information incorrect), but there's no reason for the customer to be exposed to how it works internally.

quetzalliwrites · 2026-08-08T10:09:49Z

@peter-smith-phd let's give you a chance to address @andrewrjones 's feedback. Since i'm ooo next week, @remotesynth will own this PR for docs side.

- Correct save-snapshots-locally -> saving-snapshots-locally in all 8 redirect rules; the page slug is saving-snapshots-locally. - Add missing redirects for /aws/developer-tools/snapshots/launchpad, whose page was deleted in this branch. - Repoint /persistence/supported and /user-guide/state-management/support at the new service-coverage page, since the coverage content moved out of persistence. - Update the stale /aws/capabilities/state-management/ links in ci-cd.mdx to their current paths. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

- github-actions.md: the surrounding example uses the cloud-pods state backend, so link to the Cloud Pods page and drop the "state import and export" wording, which implied local files only. - cloud-pods.mdx: add a Data residency callout noting that Cloud Pods are stored in eu-central-1, and point readers at self-managed S3 remotes if they need snapshots to stay on their own infrastructure. - enterprise-image.md: link the platform remote bullet to that callout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The terminology entry defining this term was dropped when the coverage table moved out of the Persistence page, leaving the column header undefined. Restore it as a paragraph below the table. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

peter-smith-phd · 2026-08-09T17:58:05Z

@peter-smith-phd let's give you a chance to address @andrewrjones 's feedback. Since i'm ooo next week, @remotesynth will own this PR for docs side.

Thanks, I've made the changes suggested by @athomas-lstk (except for one that was an intentional omission). @remotesynth, any feedback from you?

peter-smith-phd changed the base branch from main to doc-312-aws-docs-to-use-lstk July 20, 2026 22:46

peter-smith-phd force-pushed the doc-312-aws-docs-to-use-lstk branch from 3d31485 to b0fb87d Compare July 23, 2026 21:55

peter-smith-phd force-pushed the pro-275-rewrite-snapshots-section branch from e508757 to 9caeb99 Compare July 23, 2026 22:26

peter-smith-phd changed the title ~~Revamp Snapshots section: overview cards, page restructuring, lstk CLI~~ Revamp Snapshots section: major restructuring (largely by hand), and support for lstk Jul 26, 2026

peter-smith-phd and others added 12 commits July 31, 2026 10:44

Revamp of overview page, and structuring of other pages. No changes t…

6b5aeed

…o other pages yet. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Move Service Coverage section out of persistence.mdx into its own page

18133c3

Clean up the persistence.mdx page

3324492

Fix the examples for local snapshots.

94f3fe4

Rename save-locally to saving-snapshots-locally.

6bdeec3

Updates to Cloud Pod docs

8c9bd54

WIP for saving snapshots to S3

204d32e

Rename Cloud Pods page title for consistency with other snapshot pages

3c62f98

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

peter-smith-phd force-pushed the pro-275-rewrite-snapshots-section branch from 48c85bf to 39fb0fa Compare July 30, 2026 22:45

peter-smith-phd and others added 8 commits August 4, 2026 13:10

Clean up index.mdx page.

dde2095

Extract merge strategies into separate page.

4113823

Expand the saving-locally examples.

9f145f9

Clean up cloud pod content.

c41fb95

Clean up Persistence, and fix output boxes.

c23cf9f

clean up service-coverage

320d3f9

Final clean-up before code review.

78ca32f

peter-smith-phd marked this pull request as ready for review August 4, 2026 23:33

peter-smith-phd requested review from HarshCasper, quetzalliwrites and remotesynth as code owners August 4, 2026 23:33

athomas-lstk reviewed Aug 7, 2026

View reviewed changes

peter-smith-phd and others added 3 commits August 10, 2026 05:18

	More information about state import and export [here](/aws/developer-tools/snapshots/saving-snapshots-locally).
	More information about state import and export [here](/aws/developer-tools/snapshots/cloud-pods/).

	/user-guide/state-management/export-import-state/ /aws/developer-tools/snapshots/save-snapshots-locally/ 301
	/user-guide/state-management/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

	/aws/capabilities/state-management/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301
	/aws/capabilities/state-management/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

	/aws/developer-tools/snapshots/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301
	/aws/developer-tools/snapshots/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

	/aws/configuration/state-management/export-import-state /aws/developer-tools/snapshots/save-snapshots-locally/ 301
	/aws/configuration/state-management/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301


		Please help us improve persistence support by reporting bugs on our [GitHub Discussion](https://github.com/orgs/localstack/discussions/new/choose).

		## Technical Details


		<PersistenceCoverage client:load />

		### Terminology

Uh oh!

Conversation

peter-smith-phd commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying localstack-docs with Cloudflare Pages

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quetzalliwrites commented Aug 8, 2026

Uh oh!

peter-smith-phd commented Aug 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

peter-smith-phd commented Jul 20, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 20, 2026 •

edited

Loading