WIP: rewrite Cloud Pods docs to use lstk snapshot commands

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>

Author: peter-smith-phd

public/images/aws/pods-workflow.png

@@ -10,89 +10,64 @@ sidebar:
 import { Tabs, TabItem, FileTree } from '@astrojs/starlight/components';
 import { Badge } from '@astrojs/starlight/components';
 
-Cloud pods are persistent state snapshots of your LocalStack instance that can easily be stored, versioned, shared, and restored.
-Cloud Pods can be used for various purposes, such as:
+In [the previous section](/aws/developer-tools/snapshots/save-snapshots-locally/) you learned how to save a snapshot of the emulator's state to a local file,
+then to re-load the snapshot into a different emulator instance. However, when working in a team environment, it's important to have a standard mechanism for sharing
+snapshot files across your team, and for managing updates as new versions are published.
 
-- Save and manage snapshots of active LocalStack instances.
-- Share state snapshots with your team to debug collectively.
-- Automate your testing pipelines by pre-seeding CI environments.
-- Create reproducible development and testing environments locally.
+<div style="padding: 1em 0;">
+  <img src="/images/aws/pods-workflow.png" alt="Cloud Pods workflows" width="90%" style="margin: 0 auto;" />
+</div>
 
-![Cloud Pods Web UI](/images/aws/pods-ui.png)
+LocalStack provides the web-based _Cloud Pods_ repository for exactly this purpose, accessible only to the users in your organization. Snapshots can be
+generated by an emulator instance, then automatically published to your Cloud Pods repository. From there, snapshots can be loaded 
+back into an emulator instance, either on a desktop environment or a CI environment.
 
-## Installation
+<div style="padding: 1em 0;">
+  <img src="/images/aws/pods-ui.png" alt="Cloud Pods Web UI" width="90%" style="margin: 0 auto;" />
+</div>
 
-You can save and load the persistent state of Cloud Pods, you can use the [`lstk snapshot` command](/aws/developer-tools/running-localstack/lstk/#snapshot).
-LocalStack provides a remote storage backend that can be used to store the state of your running application and share it with your team members.
-You can interact with the Cloud Pods over the storage backend via the LocalStack Web Application.
+Each organization has their own private Cloud Pods repository, securely managed in LocalStack's cloud. Each user or organization is allocated a dedicated and 
+isolated Amazon S3 bucket. The LocalStack CLI utilizes secure S3 presigned URLs to directly interface with the S3 bucket, bypassing the need to
+transmit the snapshot files through LocalStack Platform APIs.
 
-Cloud Pods CLI is included in the [LocalStack CLI installation](/aws/getting-started/installation/#install-localstack-cli), so there's no need for additional installations to begin using it.
-If you're a licensed user, we suggest setting the `LOCALSTACK_AUTH_TOKEN` as an environment variable.
-This enables you to access the complete range of LocalStack Cloud Pods features.
+## Using the `lstk` CLI
 
-You can access the Cloud Pods CLI by running the `pod` command from your terminal.
+You can save and load the snapshots to/from your Cloud Pods repository using the [`lstk snapshot`](/aws/developer-tools/running-localstack/lstk/#snapshot) command.
 
 ```bash
-localstack pod --help
+lstk snapshot --help
 ```
+
 ```bash
-Usage: localstack pod [OPTIONS] COMMAND [ARGS]...
-  Manage the state of your instance via Cloud Pods.
+Manage emulator snapshots
 
-Options:
-  -h, --help  Show this message and exit.
+Usage: lstk snapshot [flags]
 
 Commands:
-  delete    Delete a Cloud Pod
-  inspect
-  list      List all available Cloud Pods
-  load
-  remote    Manage cloud pod remotes
-  save      Create a new Cloud Pod
-  versions
+  list        List Cloud Pod snapshots available on the LocalStack platform
+  load        Load a snapshot into the running emulator
+  remove      Delete a cloud snapshot from the LocalStack platform
+  save        Save a snapshot of the emulator state
+  show        Show metadata for a cloud snapshot
 ```
 
-:::note
-These Cloud Pods are securely stored within an AWS storage backend, where each user or organization is allocated a dedicated and isolated S3 bucket.
-The LocalStack Cloud Pods CLI utilizes secure S3 presigned URLs to directly interface with the S3 bucket, bypassing the need to transmit the state files through LocalStack Platform APIs.
-:::
-
-## Getting started
-
-This guide is designed for users new to Cloud Pods and assumes basic knowledge of the LocalStack CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script.
-
-Start your LocalStack container using your preferred method.
-We will demonstrate how you can save a snapshot of your active LocalStack instance into your LocalStack account, and pull it to a running instance.
 
-### Create AWS resources
+### Saving a snapshot to Cloud Pods
 
-You can use the `awslocal` CLI to create new AWS resources within your active LocalStack instance.
-For example, you can create an S3 bucket and add data to it using the `awslocal` CLI:
+The command for saving a snapshot to Cloud Pods is similar to saving locally, but instead of a file name, provide the `pod:` prefix followed by a valid Pod name.
 
 ```bash
-awslocal s3 mb s3://test
-echo "hello world" > /tmp/hello-world
-awslocal s3 cp /tmp/hello-world s3://test/hello-world
-awslocal s3 ls s3://test/
+lstk snapshot save pod:sample-application
 ```
 
-### Save your Cloud Pod state
-
-You can now save your Pod state using the `save` command, specifying the desired Cloud Pod name as the first argument.
-This action will save the pod and register it with the LocalStack Web Application:
-
 ```bash
-localstack pod save s3-test
+✔︎ Snapshot saved to pod:sample-application
+• Version: 1
+• Services: s3, sns, sqs, lambda
+• Size: 64.2 KB
 ```
 
-```bash
-Cloud Pod `s3-test` successfully created ✅
-Version: 1
-Remote: platform
-Services: s3
-```
-
-Optionally, you can include a message with the saved Cloud Pod using the `--message` flag.
+Optionally, you can include a message with the saved snapshot using the `--message` flag.
 
 You can access the list of available Cloud Pods for both you and your organization by utilizing the `list` command:
 
@@ -124,20 +99,11 @@ Remote: platform
 Services: s3,sqs
 ```
 
-We can now use the command `versions` to list all the created version for a Cloud Pod.
-
-```bash
-localstack pod versions s3-test
-```
-
-```bash
-┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
-┃ Version ┃ Creation Date       ┃ LocalStack Version      ┃ Services ┃ Description ┃
-┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
-│ 1       │ 2024-01-04 11:03:00 │ 3.1.1.                  │ s3       │             │
-│ 2       │ 2024-02-28 14:01:45 │ 3.1.1.                  │ s3,sqs   │             │
-└─────────┴─────────────────────┴─────────────────────────┴──────────┴─────────────┘
-```
+:::note
+Permission on Cloud Pods are assigned at organization level.
+This means that every individual in the organization can view, load, and delete Cloud Pods created by other team members.
+Similarly, everyone can save a new version of a Cloud Pod on top of a Pod originally created by someone else.
+:::
 
 ### Pull your Pod state
 
@@ -174,39 +140,26 @@ Cloud Pod s3-test:1 successfully loaded
 
 After loading the Cloud Pod's content, you can use the `state inspect` command to observe the state of the running LocalStack instance.
 
+TBD: lstk snapshot show
+
 ```bash
-localstack state inspect --format json
+lstk status
 ```
 
 ```bash
-{
-    "000000000000": {
-        "S3": {
-            "global": {
-                "listBuckets": {
-                    "Buckets": [
-                        {
-                            "Name": "test",
-                            "CreationDate": "2023-10-03T07:19:31.000Z"
-                        }
-                    ],
-                }
-            }
-        }
-    }
-}
+xxx
 ```
 
+TBD: lstk snapshot remove
+
 For comprehensive instructions, navigate to our [`lstk` CLI Guide](/aws/developer-tools/running-localstack/lstk/#snapshot).
-To access your Cloud Pods through the LocalStack Web Application, navigate to the [Cloud Pods browser](https://app.localstack.cloud/pods).
 
 :::note
-Permission on Cloud Pods are assigned at organization level.
-This means that every individual in the organization can view, load, and delete Cloud Pods created by other team members.
-Similarly, everyone can save a new version of a Cloud Pod on top of a Pod originally created by someone else.
+The snapshots stored in a Cloud Pod may not remain compatible if used with a different version of LocalStack.
+LocalStack applies [snapshot compatibility rules](/aws/developer-tools/snapshots/service-coverage#snapshot-compatibility) to block loading snapshots known to be incompatible with the running LocalStack version.
 :::
 
-## Web Application
+## Using the LocalStack Console
 
 The LocalStack Web Application enables you to :
 
@@ -414,47 +367,6 @@ The process is the following:
 - It is not possible to have both encrypted and non-encrypted versions for a Cloud Pod.
   Encryption is set at the moment of the creation and it cannot be changed.
 
-### Miscellaneous
-
-Unless explicitly specified, all Cloud Pods commands default to targeting the LocalStack Platform as the storage remote.
-It's important to note that the CLI must be authenticated correctly with our Platform.
-
-Custom remote configurations are stored within the [LocalStack volume directory](/aws/customization/advanced/filesystem/#localstack-volume-directory) and are managed by the LocalStack container.
-Consequently, when sharing Cloud Pods among your team using a custom remote, each team member must define the identical remote configuration.
-Once added, a remote persists even after LocalStack restarts.
-
-## Cloud Pods & Persistence
-
-[Persistence](/aws/developer-tools/snapshots/persistence) ensures that the service state persists across container restarts.
-You can enable persistence via a LocalStack config flag `PERSISTENCE=1` to restore your local resources, in case you’re stopping and re-starting the LocalStack instance on the same machine.
-
-In contrast, Cloud Pods provide more detailed control over your state.
-Rather than just restoring a state during LocalStack restarts, Cloud Pods enable you to capture snapshots of your local instance using the `save` command and inject these snapshots into a running instance using the `load` command, all without needing to perform a full restart.
-
-### Current Limitations
-
-Cloud Pods (and state management in general), come with a few limitation.
-In particular, Cloud Pods states might not be correctly restored if the LocalStack version used to create the pod and the target one differ.
-We detect version miss-matches when using the `pod load` and prompt a confirmation message to the user.
-
-```bash
-localstack pod load old-pod
-```
-
-```bash
-This Cloud Pod was created with LocalStack 2.1.0.
-but you are running LocalStack 3.2.1.
-Cloud Pods might be incompatible across different LocalStack versions.
-Loading a Cloud Pod with mismatching version might lead to a corrupted state of the emulator.
-Do you want to continue? [y/N]:
-```
-
-In addition to this prompt, Cloud Pods are subject to the [snapshot compatibility rules](/aws/developer-tools/snapshots/service-coverage#state-compatibility) shared with snapshot-based persistence.
-Pods that were saved before `v2026.03` cannot be loaded into LocalStack `v2026.03` or later, because persistence was rewritten for several services in that release.
-Set `DISABLE_COMPATIBILITY_RULES=1` to bypass the checks at your own risk.
-
-We are working to extend Cloud Pods support to all AWS services emulated in LocalStack.
-However, state management might not yet work reliably for every service.
 
 ## Troubleshooting
 

src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx

@@ -162,3 +162,12 @@ The Auto Load from remote feature does not automatically configure the remote.
 This needs to be done with the `localstack pod remote add ...` command.
 This commands creates a configuration file for the remote in the [LocalStack volume directory](/aws/customization/advanced/filesystem/#localstack-volume-directory).
 :::
+
+### Miscellaneous
+
+Unless explicitly specified, all Cloud Pods commands default to targeting the LocalStack Platform as the storage remote.
+It's important to note that the CLI must be authenticated correctly with our Platform.
+
+Custom remote configurations are stored within the [LocalStack volume directory](/aws/customization/advanced/filesystem/#localstack-volume-directory) and are managed by the LocalStack container.
+Consequently, when sharing Cloud Pods among your team using a custom remote, each team member must define the identical remote configuration.
+Once added, a remote persists even after LocalStack restarts.