diff --git a/public/_redirects b/public/_redirects index 1faafa5fa..f42ed907e 100644 --- a/public/_redirects +++ b/public/_redirects @@ -30,7 +30,7 @@ /applications/appsync-graphql-apis-for-dynamodb-and-rds-aurora-postgresql/ https://github.com/localstack-samples/sample-appsync-graphql-api 301 /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 /references/coverage/coverage_s3control/ /aws/services/s3/ 301 /references/custom-tls-certificates/ /aws/developer-tools/security-testing/custom-tls-certificates/ 301 /references/coverage/coverage_codecommit/ /aws/services/codecommit/ 301 @@ -379,7 +379,7 @@ /user-guide/aws/stepfunctions/ /aws/services/stepfunctions/ 301 /references/coverage/coverage_elasticache/ /aws/services/elasticache/ 301 /applications/mnist-handwritten-digit-recognition-model-running-on-a-local-sagemaker-endpoint/ https://github.com/localstack-samples/sample-mnist-digit-recognition-sagemaker 301 -/user-guide/state-management/pods-cli/ /aws/developer-tools/snapshots/cli-commands/ 301 +/user-guide/state-management/pods-cli/ /aws/developer-tools/running-localstack/lstk/#snapshot 301 /user-guide/aws/dynamodbstreams/ /aws/services/dynamodbstreams/ 301 /references/api-key/ /aws/getting-started/auth-token/#how-do-i-activate-older-versions-of-localstack-before-v30/ 301 /references/coverage/coverage_eks/ /aws/services/eks/ 301 @@ -430,7 +430,7 @@ /applications/appsync-graphql-apis-for-dynamodb-and-rds-aurora-postgresql https://github.com/localstack-samples/sample-appsync-graphql-api 301 /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 /references/coverage/coverage_s3control /aws/services/s3/ 301 /references/custom-tls-certificates /aws/developer-tools/security-testing/custom-tls-certificates/ 301 /references/coverage/coverage_codecommit /aws/services/codecommit/ 301 @@ -779,7 +779,7 @@ /user-guide/aws/stepfunctions /aws/services/stepfunctions/ 301 /references/coverage/coverage_elasticache /aws/services/elasticache/ 301 /applications/mnist-handwritten-digit-recognition-model-running-on-a-local-sagemaker-endpoint https://github.com/localstack-samples/sample-mnist-digit-recognition-sagemaker 301 -/user-guide/state-management/pods-cli /aws/developer-tools/snapshots/cli-commands/ 301 +/user-guide/state-management/pods-cli /aws/developer-tools/running-localstack/lstk/#snapshot 301 /user-guide/aws/dynamodbstreams /aws/services/dynamodbstreams/ 301 /references/api-key /aws/getting-started/auth-token/#how-do-i-activate-older-versions-of-localstack-before-v30/ 301 /references/coverage/coverage_eks /aws/services/eks/ 301 @@ -861,11 +861,15 @@ /aws/integrations/aws-native-tools /aws/connecting/ 301 /aws/integrations/infrastructure-as-code/ /aws/connecting/infrastructure-as-code/ 301 /aws/integrations/infrastructure-as-code /aws/connecting/infrastructure-as-code/ 301 -/aws/capabilities/state-management/cli-commands /aws/developer-tools/snapshots/cli-commands/ 301 -/aws/capabilities/state-management/cli-commands/ /aws/developer-tools/snapshots/cli-commands/ 301 -/aws/capabilities/state-management/export-import-state /aws/developer-tools/snapshots/export-import-state/ 301 -/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 +/aws/capabilities/state-management/export-import-state/ /aws/developer-tools/snapshots/save-snapshots-locally/ 301 /aws/capabilities/state-management/ /aws/developer-tools/snapshots/ 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 +/aws/developer-tools/snapshots/cli-commands /aws/developer-tools/running-localstack/lstk/#snapshot 301 +/aws/developer-tools/snapshots/cli-commands/ /aws/developer-tools/running-localstack/lstk/#snapshot 301 /aws/capabilities/state-management/launchpad /aws/developer-tools/snapshots/launchpad/ 301 /aws/capabilities/state-management/launchpad/ /aws/developer-tools/snapshots/launchpad/ 301 /aws/capabilities/state-management/cloud-pods /aws/developer-tools/snapshots/cloud-pods/ 301 @@ -1070,12 +1074,12 @@ /aws/configuration/security-testing/iam-policy-stream /aws/developer-tools/security-testing/iam-policy-stream/ 301 /aws/configuration/security-testing/iam-policy-stream/ /aws/developer-tools/security-testing/iam-policy-stream/ 301 /aws/configuration/state-management/ /aws/developer-tools/snapshots/ 301 -/aws/configuration/state-management/cli-commands /aws/developer-tools/snapshots/cli-commands/ 301 -/aws/configuration/state-management/cli-commands/ /aws/developer-tools/snapshots/cli-commands/ 301 +/aws/configuration/state-management/cli-commands /aws/developer-tools/running-localstack/lstk/#snapshot 301 +/aws/configuration/state-management/cli-commands/ /aws/developer-tools/running-localstack/lstk/#snapshot 301 /aws/configuration/state-management/cloud-pods /aws/developer-tools/snapshots/cloud-pods/ 301 /aws/configuration/state-management/cloud-pods/ /aws/developer-tools/snapshots/cloud-pods/ 301 -/aws/configuration/state-management/export-import-state /aws/developer-tools/snapshots/export-import-state/ 301 -/aws/configuration/state-management/export-import-state/ /aws/developer-tools/snapshots/export-import-state/ 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 /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/persistence /aws/developer-tools/snapshots/persistence/ 301 diff --git a/public/images/aws/merge-strategies.png b/public/images/aws/merge-strategies.png deleted file mode 100644 index 19423119c..000000000 Binary files a/public/images/aws/merge-strategies.png and /dev/null differ diff --git a/public/images/aws/persistence-pods-remote.png b/public/images/aws/persistence-pods-remote.png deleted file mode 100644 index 554e584e7..000000000 Binary files a/public/images/aws/persistence-pods-remote.png and /dev/null differ diff --git a/public/images/aws/pods-workflow.png b/public/images/aws/pods-workflow.png new file mode 100644 index 000000000..c732bbaee Binary files /dev/null and b/public/images/aws/pods-workflow.png differ diff --git a/public/images/aws/snapshot-lifecycle-overview.png b/public/images/aws/snapshot-lifecycle-overview.png new file mode 100644 index 000000000..09b03ffe1 Binary files /dev/null and b/public/images/aws/snapshot-lifecycle-overview.png differ diff --git a/public/images/aws/snapshot-merge-account-region.png b/public/images/aws/snapshot-merge-account-region.png new file mode 100644 index 000000000..a054a2a47 Binary files /dev/null and b/public/images/aws/snapshot-merge-account-region.png differ diff --git a/public/images/aws/snapshot-merge-overwrite.png b/public/images/aws/snapshot-merge-overwrite.png new file mode 100644 index 000000000..99ef510bd Binary files /dev/null and b/public/images/aws/snapshot-merge-overwrite.png differ diff --git a/public/images/aws/snapshot-merge-service.png b/public/images/aws/snapshot-merge-service.png new file mode 100644 index 000000000..9f097fc30 Binary files /dev/null and b/public/images/aws/snapshot-merge-service.png differ diff --git a/src/content/docs/aws/ci-pipelines/circleci.md b/src/content/docs/aws/ci-pipelines/circleci.md index f304bbd80..4904dfc00 100644 --- a/src/content/docs/aws/ci-pipelines/circleci.md +++ b/src/content/docs/aws/ci-pipelines/circleci.md @@ -520,7 +520,7 @@ jobs: - localstack-load-state ``` -More information about Localstack's [state import/export](/aws/developer-tools/snapshots/export-import-state). +More information about Localstack's [state import/export](/aws/developer-tools/snapshots/save-snapshots-locally). #### Cache @@ -586,4 +586,4 @@ workflows: ... ``` -More information about [state management](/aws/developer-tools/snapshots/export-import-state). \ No newline at end of file +More information about [state management](/aws/developer-tools/snapshots/save-snapshots-locally). \ No newline at end of file diff --git a/src/content/docs/aws/ci-pipelines/codebuild.md b/src/content/docs/aws/ci-pipelines/codebuild.md index f4e7060e8..486e64fdc 100644 --- a/src/content/docs/aws/ci-pipelines/codebuild.md +++ b/src/content/docs/aws/ci-pipelines/codebuild.md @@ -241,7 +241,7 @@ Find out more about [ephemeral instances](/aws/developer-tools/cloud-sandbox/eph #### Artifact -Find out more about [state management](/aws/developer-tools/snapshots/export-import-state/). +Find out more about [state management](/aws/developer-tools/snapshots/save-snapshots-locally/). ```yml showshowLineNumbers ... @@ -274,7 +274,7 @@ To use previously stored artifacts as inputs, set them as a source in the projec #### Cache -Additional information about [state export and import](/aws/developer-tools/snapshots/export-import-state/). +Additional information about [state export and import](/aws/developer-tools/snapshots/save-snapshots-locally/). ##### Native Runner diff --git a/src/content/docs/aws/ci-pipelines/github-actions.md b/src/content/docs/aws/ci-pipelines/github-actions.md index 64ad9fa55..240a248dd 100644 --- a/src/content/docs/aws/ci-pipelines/github-actions.md +++ b/src/content/docs/aws/ci-pipelines/github-actions.md @@ -171,7 +171,7 @@ Find out more about ephemeral instances [here](/aws/developer-tools/cloud-sandbo ... ``` -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/save-snapshots-locally). ## Current Limitations diff --git a/src/content/docs/aws/ci-pipelines/gitlab-ci.md b/src/content/docs/aws/ci-pipelines/gitlab-ci.md index 87a0dd3af..53b1a48dc 100644 --- a/src/content/docs/aws/ci-pipelines/gitlab-ci.md +++ b/src/content/docs/aws/ci-pipelines/gitlab-ci.md @@ -136,7 +136,7 @@ job: ... ``` -More info about Localstack's state export and import [here](/aws/developer-tools/snapshots/export-import-state/). +More info about Localstack's state export and import [here](/aws/developer-tools/snapshots/save-snapshots-locally/). #### Cache @@ -159,7 +159,7 @@ job: ... ``` -Additional information about state export and import [here](/aws/developer-tools/snapshots/export-import-state/). +Additional information about state export and import [here](/aws/developer-tools/snapshots/save-snapshots-locally/). #### Cloud Pod diff --git a/src/content/docs/aws/customization/advanced/initialization-hooks.mdx b/src/content/docs/aws/customization/advanced/initialization-hooks.mdx index 7f592dfc3..2eb720677 100644 --- a/src/content/docs/aws/customization/advanced/initialization-hooks.mdx +++ b/src/content/docs/aws/customization/advanced/initialization-hooks.mdx @@ -117,7 +117,7 @@ A common use case for init hooks is pre-seeding LocalStack with custom state. For example if you want to have a certain S3 bucket or DynamoDB table created when starting LocalStack, init hooks can be very useful. :::tip -If you have more complex states, [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods) and [how to auto-load them on startup](/aws/developer-tools/snapshots/cloud-pods#auto-loading-cloud-pods) may be a good option to look into! +If you have more complex states, [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods) and [how to auto-load them on startup](/aws/developer-tools/snapshots/cloud-pods#auto-loading-from-cloud-pods) may be a good option to look into! ::: To execute aws cli commands when LocalStack becomes ready, diff --git a/src/content/docs/aws/customization/configuration-options.md b/src/content/docs/aws/customization/configuration-options.md index 34d85acb8..ef5ac6d6a 100644 --- a/src/content/docs/aws/customization/configuration-options.md +++ b/src/content/docs/aws/customization/configuration-options.md @@ -403,7 +403,7 @@ To learn more about these configuration options, see [Persistence](/aws/develope | `SNAPSHOT_SAVE_STRATEGY` | `ON_SHUTDOWN`\|`ON_REQUEST`\|`SCHEDULED`\|`MANUAL` | Strategy that governs when LocalStack should make state snapshots | | `SNAPSHOT_LOAD_STRATEGY` | `ON_STARTUP`\|`ON_REQUEST`\|`MANUAL` | Strategy that governs when LocalStack restores state snapshots | | `SNAPSHOT_FLUSH_INTERVAL` | 15 (default) | The interval (in seconds) between persistence snapshots. It only applies to a `SCHEDULED` save strategy (see [Persistence Mechanism](/aws/developer-tools/snapshots/persistence))| -| `DISABLE_COMPATIBILITY_RULES` | `0` (default) \| `1` | Disable the [state compatibility rules](/aws/developer-tools/snapshots/persistence#state-compatibility) that prevent loading incompatible state into LocalStack. Applies to both snapshot persistence and Cloud Pods. | +| `DISABLE_COMPATIBILITY_RULES` | `0` (default) \| `1` | Disable the [snapshot compatibility rules](/aws/developer-tools/snapshots/service-coverage#state-compatibility) that prevent loading incompatible state into LocalStack. Applies to both snapshot persistence and Cloud Pods. | ## Cloud Pods @@ -415,7 +415,7 @@ To learn more about these configuration options, see [Cloud Pods](/aws/developer | `POD_LOAD_CLI_TIMEOUT` | 60 (default) | Timeout in seconds to wait before returning from load operations on the Cloud Pods CLI | | `POD_ENCRYPTION` | `0` (default) \| `1` | Whether to encrypt the Cloud Pods artifacts at rest. | | `ENABLE_POD_RESOURCES=1` | `0` (default) \| `1` | Whether to save a detailed Stack Overview including available resources for the Cloud Pod | -| `MERGE_STRATEGY` | `account-region-merge` (default) \| `service-merge` \| `overwrite` | The merge strategy to apply when loading a Cloud Pod into LocalStack (see [state merging](/aws/developer-tools/snapshots/cloud-pods/#state-merging)) | +| `MERGE_STRATEGY` | `account-region-merge` (default) \| `service-merge` \| `overwrite` | The merge strategy to apply when loading a Cloud Pod into LocalStack (see [snapshot merging](/aws/developer-tools/snapshots/save-snapshots-locally/#snapshot-merging)) | ## Extensions diff --git a/src/content/docs/aws/customization/other-installations/enterprise-image.md b/src/content/docs/aws/customization/other-installations/enterprise-image.md index 1ef2bdd59..77f0d0090 100644 --- a/src/content/docs/aws/customization/other-installations/enterprise-image.md +++ b/src/content/docs/aws/customization/other-installations/enterprise-image.md @@ -53,7 +53,7 @@ The main integrations are: - **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, configure your own Cloud Pods [remote storage](/aws/developer-tools/snapshots/other-snapshot-storage-options#remotes). - **Ephemeral instances**: These are managed cloud instances and therefore require connectivity to LocalStack Cloud services. ### Recommended setup for offline environments diff --git a/src/content/docs/aws/developer-tools/snapshots/cli-commands.md b/src/content/docs/aws/developer-tools/snapshots/cli-commands.md deleted file mode 100644 index 7959df783..000000000 --- a/src/content/docs/aws/developer-tools/snapshots/cli-commands.md +++ /dev/null @@ -1,416 +0,0 @@ ---- -title: CLI commands -description: Reference guide for LocalStack Cloud Pods CLI commands and how to get started on using them. -template: doc -tags: ["Ultimate"] -sidebar: - order: 6 ---- - -This reference provides descriptions and example commands for LocalStack Cloud Pods CLI (`pod`) commands. - -## Syntax - -Use the following syntax to run `localstack pod` commands from your terminal window: - -```bash -localstack pod [OPTIONS] COMMAND [ARGS]... -``` - -In the above syntax: -- `COMMAND` specifies the operation you want to perform with your Cloud Pods (`save` or `load`). -- `OPTIONS` specifies the optional flags. -- `ARGS` specifies the command arguments. - -## Commands - -The following section lists the available commands for the Cloud Pods CLI. -You can have an overview of these command by typing `localstack pod --help`: - -```bash -Usage: pod [OPTIONS] COMMAND [ARGS]... - - Manage the state of your instance via Cloud Pods. - -Options: - --help Show this message and exit. - -Commands: - delete Delete a Cloud Pod - inspect Inspect the contents of a Cloud Pod This command shows the... - list List all available Cloud Pods - load Load the state of a Cloud Pod into the application runtime/... - remote Manage cloud pod remotes - save Create a new Cloud Pod - versions List all available versions for a Cloud Pod This command lists... -``` - -### `save` - -```bash -Usage: pod save [OPTIONS] NAME [REMOTE] - - Save the current state of the LocalStack container in a Cloud Pod. - - A Cloud Pod can be registered and saved with different storage options, - called remotes. - By default, Cloud Pods are hosted in the LocalStack - platform. - However, users can decide to store their Cloud Pods in other - remotes, such as AWS S3 buckets or ORAS registries. - - An optional message can be attached to any Cloud Pod. - Furthermore, one - could decide to export only a subset of services with the optional - --service option. - - To use the LocalStack platform for storage, the desired Cloud Pod's name will suffice, e.g.: - - localstack pod save - - Please be aware that each following save invocation with the same name - will result in a new version being created. - - To save a local copy of your state, you can use the 'localstack state export' command. - -Options: - -m, --message TEXT Add a comment describing this Cloud Pod's - version - - -s, --services TEXT Comma-delimited list of services to push in - the Cloud Pod (all by default) - - --visibility [public|private] Set the visibility of the Cloud Pod [`public` - or `private`]. - Does not create a new version - - -S, --secret TEXT Secret for the Cloud Pod encryption. Encryption is an - Enterprise only feature. - - -f, --format [json] The formatting style for the save command - output. - - --help Show this message and exit. -``` - -The `save` command allows you to save a new version of a Cloud Pod targeting a specific remote. -To save and load the state locally, you can use the command in the `localstack state` group. - -```bash -localstack pod save my-pod -``` - -The above command generates a new version of `my-pod` and uploads it on the LocalStack platform. -When pushing an already existing pod, a new version is created and subsequently uploaded to the platform. - -Users also have the option to select a specific subset of AWS services they want to include in the new Cloud Pod version using the `--services` option. - -Users who want to make a Cloud Pod accessible outside their organization can mark it as **public** with the following command: - -```bash -localstack pod save --name my-pod --visibility public -``` - -The above command does not create a new version and requires a version already registered with the platform. -The CLI manual for the `save` command is as follows: - -### `load` - -```bash -Usage: pod load [OPTIONS] NAME [REMOTE] - - Load the state of a Cloud Pod into the application runtime/ Users can - import Cloud Pods from different remotes, with the LocalStack platform - being the default one. - - Loading the state of a Cloud Pod into LocalStack might cause some - conflicts with the current state of the container. - By default, LocalStack - will attempt a best-effort merging strategy between the current state and - the one from the Cloud Pod. - For a service X present in both the current - state and the Cloud Pod, we will attempt to merge states across different - accounts and regions. - If the service X has a state for the same account - and region both in the running container and the Cloud Pod, the latter - will be used. - If a service Y is present in the running container but not - in the Cloud Pod, it will be left untouched. - With `--merge overwrite`, the - state of the Cloud Pod will completely replace the state of the running - container. - - To load a local copy of a LocalStack state, you can use the 'localstack state import' command. - -Options: - --merge [overwrite|merge] The merge strategy to adopt when loading the - Cloud Pod - - -y, --yes Automatic yes to prompts. - Assume a positive - answer to all prompts and run non-interactively - - --help Show this message and exit. -``` - -The `load` command is the inverse operation of `save`. -It retrieves the content of a previously stored Cloud Pod a remote (by default, theLocalStack platform) and injects it into the LocalStack container. - -### `delete` - -```bash -Usage: pod delete [OPTIONS] NAME - - Delete a Cloud Pod registered on the remote LocalStack platform. - - This command will remove all the versions of a Cloud Pod, and the - operation is not reversible. - -Options: - --help Show this message and exit. -``` - -The `delete` command let users delete a Cloud Pod stored in the remote platform. -The CLI manual for the `delete` command is as follows: - -### `inspect` - -```bash -Usage: pod inspect [OPTIONS] NAME - - Inspect the contents of a Cloud Pod - - This command shows the content of a Cloud Pod. - By default, it starts a - curses interface which allows an interactive inspection of the contents in - the Cloud Pod. - -Options: - -f, --format [curses|rich|json] - The formatting style for the inspect command - output. - - --help Show this message and exit. -``` - -The `inspect` command simply lets the user inspect the content of a Cloud Pod. - -### `list` - -```bash -Usage: pod list [OPTIONS] [REMOTE] - - List all the Cloud Pods available for a single user, or for an entire - organization, if the user is part of one. - - With the --public flag, it lists the all the available public Cloud Pods. - A public Cloud Pod is available across the boundary of a user one/or - organization. - In other words, any public Cloud Pod can be injected by any - other user holding a LocalStack for AWS license. - -Options: - -p, --public List all the available public Cloud Pods - -f, --format [table|json] The formatting style for the list pods command - output. - - --help Show this message and exit. -``` - -The `list` command lists all of the available Cloud Pods. -It shows all the pods available for a single user and its organization by default. - -### `versions` - -```bash -Usage: pod versions [OPTIONS] NAME - - List all available versions for a Cloud Pod - - This command lists the versions available for a Cloud Pod. - Each invocation - of the save command is going to create a new version for a named Cloud - Pod, if a Pod with such name already does exist in the LocalStack - platform. - -Options: - -f, --format [table|json] The formatting style for the version command - output. - - --help Show this message and exit. -``` - -The `versions` command lists all the available versions of a Cloud Pod. -The CLI manual for the `version` command is as follows: - -### `remote` - -The `remote` command group lets you manage custom Cloud Pod remotes, to enable alternative storage backends in addition to the default LocalStack managed platform. -It offers 3 commands: `add`, `delete`, and `list`. - -For more info about remote usage, check our [documentation](/aws/developer-tools/snapshots/cloud-pods/#remotes). - -```bash -Usage: pod remote [OPTIONS] COMMAND [ARGS]... - - Manage cloud pod remotes - -Options: - --help Show this message and exit. - -Commands: - add Add a remote - delete Delete a remote - list Lists the available remotes -``` - -#### `remote add` - -```bash -Usage: pod remote add [OPTIONS] NAME URL - - Add a new remote for Cloud Pods. - - A remote is the place where your Cloud Pods are stored. - By default, Cloud - Pods are store in the LocalStack platform. - -Options: - --help Show this message and exit. -``` - -#### `remote delete` - -```bash -Usage: pod remote delete [OPTIONS] NAME - - Remove a remote for Cloud Pods. - -Options: - --help Show this message and exit. -``` - -#### `remote list` - -```bash -Usage: pod remote list [OPTIONS] - -Options: - -f, --format [table|json] The formatting style for the remotes command - output. - - --help Show this message and exit. -``` - ---- - -# Local Commands - -In addition to the commands in the `pod` group, we also offer a simple alternative to save and load the LocalStack state. -The `state` group offers two commands to export and import the state of the LocalStack container to/from a zip file from the host machine. - -## `state` syntax - -```bash -Usage: state [OPTIONS] COMMAND [ARGS]... - - (Preview) Manage and manipulate the localstack state. - - The state command group allows you to interact with LocalStack's state - backend. - - Read more: https://docs.localstack.cloud/aws/developer-tools/snapshots/persistence/ - -Options: - --help Show this message and exit. - -Commands: - export Export the state of LocalStack services - import Import the state of LocalStack services - reset Reset the state of LocalStack services -``` - -### `state export` - -```bash -Usage: state export [OPTIONS] [DESTINATION] - - Save the current state of the LocalStack container to a file on the local - disk. - This file can be restored at any point in time using the `localstack - state import` command. - Please be aware that this might not be possible - when importing the state with a different version of LocalStack. - - If you are looking for a managed solution to handle the state of your - LocalStack container, please check out the Cloud Pods feature: - https://docs.localstack.cloud/aws/developer-tools/snapshots/cloud-pods/ - - Use the DESTINATION argument to specify an absolute path for the exported - file or a filename in current working directory. - If no destination is - specified, a file named `ls-state-export` will be saved in the current - working directory. - - Examples: - localstack state export my-state - localstack state export /home/johndoe/my-state - - You can also specify a subset of services to export. - By default, the state - of all running services is exported. - -Options: - -s, --services TEXT Comma-delimited list of services to reset. -By default, - the state of all running services is exported. - - -f, --format [json] The formatting style for the save command output. - --help Show this message and exit. -``` - -### `state import` - -```bash -Usage: state import [OPTIONS] SOURCE - - Load the state of LocalStack from a file into the running container. - The - SOURCE file must have been generated from a previous `localstack state - export` command. - Please be aware that it might not be possible to import a - state generated from a different version of LocalStack. - - Examples: - localstack state import my-state - localstack state import /home/johndoe/my-state - -Options: - --help Show this message and exit. -``` - -### `state reset` - -```bash -Usage: state reset [OPTIONS] - - Reset the service states of the current LocalStack runtime. - - This command invokes a reset of services in the currently running - LocalStack container. - By default, all services are rest. - The `services` - options allows to select a subset of services which should be reset. - - This command tries to automatically discover the running LocalStack - instance. - If LocalStack has not been started with `localstack start` (and - is not automatically discoverable), please set `LOCALSTACK_HOST`. - -Options: - -s, --services TEXT Comma-delimited list of services to reset. -By default, - the state of all running services is reset. - - --help Show this message and exit. -``` \ No newline at end of file diff --git a/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx b/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx index d85aff37e..06db1e64a 100644 --- a/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx +++ b/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx @@ -1,278 +1,217 @@ --- -title: Cloud Pods -description: Get started with Cloud Pods to manage the state of your LocalStack instance state. +title: Saving to Cloud Pods +description: Using LocalStack's Cloud Pods repository to share Snapshots with your team. template: doc tags: ["Base"] sidebar: - order: 2 + order: 3 --- import { Tabs, TabItem, FileTree } from '@astrojs/starlight/components'; import { Badge } from '@astrojs/starlight/components'; -## Introduction +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. When working in a team environment, it's important to have a standard mechanism for sharing +snapshot files amongst your team, and for managing updates as new versions are published. -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: +
+ Cloud Pods workflows +
-- 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. +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. -![Cloud Pods Web UI](/images/aws/pods-ui.png) +
+ Cloud Pods Web UI +
-## Installation +Each organization has its own private Cloud Pods repository, securely managed in LocalStack's cloud. These are backed by dedicated, +isolated Amazon S3 buckets. 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's Platform APIs. -You can save and load the persistent state of Cloud Pods, you can use the [Cloud Pods command-line interface (CLI)](/aws/developer-tools/snapshots/cli-commands). -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. +## Using the `lstk` CLI -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. - -You can access the Cloud Pods CLI by running the `pod` command from your terminal. +You can save and load the snapshots to or 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. +### Saving a snapshot to Cloud Pods -### Create AWS resources - -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 Cloud 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: sqs, sns, cloudwatch, cloudcontrol, s3, sts +• Size: 127.0 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. - -You can access the list of available Cloud Pods for both you and your organization by utilizing the `list` command: - -```bash -localstack pod list -``` +You can access the list of available Cloud Pods for both you and your organization by using the `list` command: ```bash -┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓ -┃ Name ┃ Max Version ┃ Last Change ┃ -┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩ -│ s3-test │ 1 │ 2024-01-04 11:03:00 │ -└──────────────────────────────┴─────────────┴─────────────────────┘ +lstk snapshot list ``` -With the `save` command you can create multiple versions of a Cloud Pod. -For instance, let us create a SQS queue and second version of `s3-test`. - ```bash -awslocal sqs create-queue --queue-name test-queue +~ 3 snapshots -localstack pod save s3-test -``` - -```bash -Cloud Pod `s3-test` successfully created ✅ -Version: 2 -Remote: platform -Services: s3,sqs + NAME VERSION LAST CHANGED + snapshot1 1 2026-07-20 20:02 UTC + sample-application 1 2026-07-23 23:47 UTC + snapshot2 1 2026-07-20 20:04 UTC ``` -We can now use the command `versions` to list all the created version for a Cloud Pod. +With the `save` command you can create multiple versions of a Cloud Pod. +For instance, let us create a SQS queue and second version of `sample-application`. ```bash -localstack pod versions s3-test +lstk aws sqs create-queue --queue-name test-queue +lstk snapshot save pod:sample-application ``` ```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 │ │ -└─────────┴─────────────────────┴─────────────────────────┴──────────┴─────────────┘ +✔︎ Snapshot saved to pod:sample-application +• Version: 2 +• Services: sqs, sns, cloudwatch, cloudcontrol, s3, sts +• Size: 130.9 KB ``` -### Pull your Pod state +:::note +Permissions on Cloud Pods are assigned at organization level. +This means that every individual in the organization can view, load, and delete snapshots created by other team members. +Similarly, everyone can save a new version on top of a snapshot originally created by someone else. +::: -On a separate machine, start LocalStack while ensuring the Auth Token is properly configured. -Then, retrieve the previously created Cloud Pod by employing the `load` command, specifying the Cloud Pod name as the first argument: +### Loading snapshots from a Cloud Pod -```bash -localstack pod load s3-test -``` +To load a snapshot from a Cloud Pod into a running emulator, use the `lstk snapshot load` command: ```bash -Cloud Pod s3-test successfully loaded +lstk snapshot load pod:sample-application ``` -You can examine the S3 buckets within the Cloud Pod: - ```bash -awslocal s3 ls s3://test/ +✔︎ Snapshot loaded from pod:sample-application +• Services: sts, s3, sqs, cloudwatch, cloudcontrol, sns ``` -```bash -2022-10-04 22:33:54 12 hello-world -``` +You can examine the loaded resources with the `lstk status` command: -You can also load a specific version by appending a version number to the pod name after a colon. -If not specified, the latest version will be loaded. ```bash -localstack pod load s3-test:1 +lstk status ``` ```bash -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. +✔︎ LocalStack AWS Emulator is running +• Endpoint: localhost.localstack.cloud:4566 +• Container: localstack-aws-dev +• Version: 2026.7.0 +• Uptime: 25m 46s -```bash -localstack state inspect --format json -``` +~ 6 resources · 3 services -```bash -{ - "000000000000": { - "S3": { - "global": { - "listBuckets": { - "Buckets": [ - { - "Name": "test", - "CreationDate": "2023-10-03T07:19:31.000Z" - } - ], - } - } - } - } -} + SERVICE RESOURCE REGION ACCOUNT + S3 bucket1 global 000000000000 + SNS topic1 us-east-1 000000000000 + SNS topic2 ap-southeast-2 000000000000 + SQS http://sqs.ap-southeast-2.localhost.localstack.cloud:4566/000000000000/queue-2 ap-southeast-2 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-1 us-east-1 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/test-queue us-east-1 000000000000 ``` -For comprehensive instructions, navigate to our [Command-Line Interface (CLI) Guide](/aws/developer-tools/snapshots/cli-commands/). -To access your Cloud Pods through the LocalStack Web Application, navigate to the [Cloud Pods browser](https://app.localstack.cloud/pods). +Comprehensive instructions on using the `lstk snapshot` CLI command are found in the [`lstk` CLI Guide](/aws/developer-tools/running-localstack/lstk/#snapshot). :::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 : +The LocalStack Console enables you to: -- Browse your Cloud Pods and access your version history. -- Export & import Cloud Pods to and from LocalStack instances. -- View Cloud Pods metadata, resources, regions, and version history. +- Browse your Cloud Pods and access your snapshot version history. +- Save and load snapshots to and from Cloud Pods. +- View snapshot metadata, resources, regions, and version history. ### Browse Cloud Pods -[Cloud Pods Browser](https://app.localstack.cloud/pods) allows you to view, manage, and explore your Cloud Pods through the LocalStack Web Application. +The [Cloud Pods Browser](https://app.localstack.cloud/pods) allows you to view, manage, and explore your snapshots through the LocalStack Console. With Cloud Pods, you can have individual or shared ownership of a snapshot of your LocalStack instance. -![LocalStack Web Application's Cloud Pods Browser outlining various saved Clod Pods" title="Cloud Pods Browser](/images/aws/cloud-pods-browser.png) +![LocalStack Web Application's Cloud Pods Browser outlining various saved snapshots](/images/aws/cloud-pods-browser.png "Cloud Pods Browser") The Cloud Pods Browser provides the following functionalities: -- **View Cloud Pods**: View all Cloud Pods saved by you or your organization. -- **View Versions**: View the version history of a Cloud Pod and access previous versions of specific Cloud Pods by clicking on the Cloud Pod's name. -- **View Cloud Pod Details**: View the details of a specific Cloud Pod version by clicking on the version. +- **View Cloud Pods**: View all snapshots saved by you or your organization. +- **View Versions**: View the version history of a snapshot and access previous snapshots by clicking on the Cloud Pod's name. +- **View Snapshot Details**: View the details of a specific snapshot version by clicking on the version. - **View Cloud Pod storage**: View the organization storage usage and user storage usage on top of the Cloud Pods Browser. -- **Delete Cloud Pod**: Delete a Cloud Pod by selecting the Cloud Pod and navigating to the **Actions** button, followed by **Delete**. +- **Delete Snapshot**: Delete a snapshot by selecting the snapshot and navigating to the **Actions** button, followed by **Delete**. -### View Cloud Pods metadata +### View snapshot metadata -You can view Cloud Pods metadata by selecting any Cloud Pod in the [Cloud Pods Browser](https://app.localstack.cloud/pods). +You can view snapshot metadata by selecting any snapshot in the [Cloud Pods Browser](https://app.localstack.cloud/pods). The metadata includes details such as: -- The user who created the Cloud Pod +- The user who created the snapshot - The creation timestamp -- The LocalStack version used to create the Cloud Pod -- The size of the Cloud Pod -- The service resources contained in the Cloud Pod +- The LocalStack version used to create the snapshot +- The size of the snapshot +- The service resources contained in the snapshot -You can view detailed information within a Cloud Pod, including available resources, categorized services with configurations, and quick access to resource identifiers and endpoints—all without loading the Cloud Pod into your LocalStack runtime. +You can view detailed information within a snapshot, including available resources, categorized services with configurations, and quick access to resource identifiers and endpoints—all without loading the snapshot into your LocalStack runtime. -To save metadata with resource details in the Cloud Pod, ensure your LocalStack container is running and save the Cloud Pod with `ENABLE_POD_RESOURCES=1`. -Cloud Pods saved without this configuration enabled will not display granular details. +To save metadata with resource details in the Cloud Pod, ensure your LocalStack container is running and save the snapshot with `ENABLE_POD_RESOURCES=1`. +Snapshots saved without this configuration enabled will not display granular details. ![Cloud Pods details](/images/aws/cloud-pod-details.png) -### Export & Import Cloud Pods +### Save and load snapshots to or from Cloud Pods -You can export and import your LocalStack infrastructure state as a Cloud Pod using the LocalStack Web Application. -This feature is particularly useful when you need to use a user-friendly interface to manage your Cloud Pods, without the need to interact with the CLI. +You can save and load your LocalStack infrastructure state as a snapshot to or from a Cloud Pod using the LocalStack Console. +This feature is particularly useful when you need to use a user-friendly interface to manage your snapshots, without the need to interact with the CLI. -![LocalStack Export/Import State Cloud Pod Mode](/images/aws/export-import-state-cloud-pod.png) +![LocalStack Save/Load Snapshot Cloud Pod Mode](/images/aws/export-import-state-cloud-pod.png) -#### Export the State +#### Save the snapshot -To export the state, follow these steps: +To save a snapshot, follow these steps: 1. Navigate to the **Cloud Pod** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. 2. Create AWS resources locally as needed. -3. Enter the Pod name and toggle between the **New Pod** and **Existing Pod** options. +3. Enter the Cloud Pod name and toggle between the **New Pod** and **Existing Pod** options. 4. Enter the services to save resources for. By default, all available service resources are saved. 5. Click on **Create New Pod**. -A new Cloud Pod will be created and will be available for import into another LocalStack instance. -You can check out the list of available Cloud Pods in the [Cloud Pod](https://app.localstack.cloud/pods) page. +A new Cloud Pod will be created and the snapshot will be available for loading into another LocalStack instance. +You can check out the list of available Cloud Pods in the [Cloud Pods](https://app.localstack.cloud/pods) page. -#### Import the State +#### Load the snapshot -To import the state, follow these steps: +To load a snapshot, follow these steps: 1. Navigate to the **Cloud Pod** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. 2. Choose the Cloud Pod from the drop-down list. @@ -280,11 +219,11 @@ To import the state, follow these steps: To confirm the successful injection of the container state, visit the respective [Resource Browser](https://app.localstack.cloud/inst/default/resources) for the services and verify the resources. -## Auto Loading Cloud Pods +## Auto Loading from Cloud Pods -In addition to loading Cloud Pods through the Command-Line Interface (CLI) or the Web Application, you can configure the automatic loading of one or more Cloud Pods upon the startup of the LocalStack container. +In addition to loading snapshots through the Command-Line Interface (CLI) or the Console, you can configure the automatic loading of one or more Cloud Pods upon the startup of the LocalStack container. -### Environmental variables +### Environment variables To automatically load a Cloud Pod at startup, utilize the `AUTO_LOAD_POD` [configuration variable](/aws/customization/configuration-options/). @@ -333,7 +272,7 @@ docker run \ LocalStack allows for the use of configuration files to automatically load Cloud Pods during startup. -Within the container, LocalStack searches through the `/etc/localstack/init-pod.d` directory for two file types: `zip` files created using the `localstack state export` command, and `txt` files, where each line represents the name of a Cloud Pod. +Within the container, LocalStack searches through the `/etc/localstack/init-pods.d` directory for two file types: `zip` files created using the `localstack state export` command, and `txt` files, where each line represents the name of a Cloud Pod. Take the following example of a project layout: @@ -371,163 +310,9 @@ services: - "./init-pods.d:/etc/localstack/init-pods.d" ``` -## Remotes - -A remote is the location where Cloud Pods are stored. -By default, Cloud Pod artifacts are stored in the LocalStack platform. -However, if your organization's data regulations or sovereignty requirements prohibit storing Cloud Pod assets in a remote storage infrastructure, you have the option to persist Cloud Pods in an on-premises storage location under your complete control. - -LocalStack provides two types of alternative remotes: - -- S3 bucket remote storage. -- [ORAS](https://oras.land/) (OCI Registry as Storage) remote storage. - -Cloud Pods command-line interface (CLI) allows you to create, delete, and list remotes. - -```bash -localstack pod remote --help -``` - -```bash -Usage: localstack pod remote [OPTIONS] COMMAND [ARGS]... - - Manage cloud pod remotes - -Options: - -h, --help Show this message and exit. - -Commands: - add Add a remote - delete Delete a remote - list List the available remotes -``` - -### S3 bucket remote storage - -The S3 remote enables you to store Cloud Pod assets in an existing S3 bucket within an actual AWS account. -The initial step is to export the necessary AWS credentials within the terminal session. - -```bash -export AWS_ACCESS_KEY_ID=... -export AWS_SECRET_ACCESS_KEY=... -``` - -A possible option is to obtain credentials via [AWS SSO CLI](https://github.com/synfinatic/aws-sso-cli). - -Next, we establish a new remote specifically designed for an S3 bucket. -By running the following command, we create a remote named `s3-storage-aws` responsible for storing Cloud Pod artifacts in an S3 bucket called `ls-pods-bucket-test`. - -The `access_key_id` and `secret_access_key` placeholders ensure the correct transmission of AWS credentials to the container. - -```bash -localstack pod remote add s3-storage-aws 's3://ls-pods-bucket-test/?access_key_id={access_key_id}&secret_access_key={secret_access_key}' -``` - -Lastly, you can utilize the standard `pod` CLI command to generate a new Cloud Pod that points to the previously established remote. - -```bash -localstack pod save my-pod s3-storage-aws -``` - -Once the command has been executed, you can confirm the presence of Cloud Pod artifacts in the S3 bucket by simply running: - -```bash -aws s3 ls s3://ls-pods-bucket-test -2023-09-27 13:50:10 83650 localstack-pod-my-pod-state-1.zip -2023-09-27 13:50:11 85103 localstack-pod-my-pod-version-1.zip -``` - -You can use the `pod load` command to load the same pod that was previously saved in this remote: - -```bash -localstack pod load my-pod s3-storage-aws -``` - -Similarly, you can list the Cloud Pods on this specific remote with the `pod list` command: - -```bash -localstack pod list s3-storage-aws -``` - -:::note -Full S3 remotes support is available in the CLI from version 3.2.0. -If you experience any difficulties, update your [LocalStack CLI](/aws/getting-started/installation/#update-localstack-cli). -::: - -### ORAS remote storage - -The ORAS remote enables users to store Cloud Pods in OCI-compatible registries like Docker Hub, Nexus, or ECS registries. -ORAS stands for "OCI Registry as Service," and you can find additional information about this standard [on the official website](https://oras.land/). - -For example, let's illustrate how you can utilize Docker Hub to store and retrieve Cloud Pods. - -To begin, you must configure the new remote using the LocalStack CLI. -You'll need to export two essential environment variables, `ORAS_USERNAME` and `ORAS_PASSWORD`, which are necessary for authenticating with Docker Hub. - -```bash -export ORAS_USERNAME=docker_hub_id -export ORAS_PASSWORD=ILoveLocalStack1! -``` - -You can now use the CLI to create a new remote called `oras-remote`. - -```bash -localstack pod remote add oras-remote 'oras://{oras_username}:{oras_password}@registry.hub.docker.com/' -``` - -Lastly, you can store a pod using the newly configured remote, where `my-pod` represents the Cloud Pod's name, and `oras-remote` is the remote's name. - -```bash -localstack pod save my-pod oras-remote -``` - -Likewise, you can execute the reverse operation to load a Cloud Pod from `oras-remote` using the following command: - -```bash -localstack pod load my-pod oras-remote -``` - -### Auto Load with remotes - -LocalStack also supports the auto load of a Cloud Pod from registered remotes. -The configuration is similar to what we just described. -In particular you could simply add the remote name to the text files inside the `init-pods.d`, as follows: - -```text -foo-pod,bar-remote -``` - -With such a configuration, the `foo-pod` Cloud Pod will be loaded from the `bar-remote` remote. -To properly configure the remote, you need to provide the needed environment variables when starting the LocalStack container. -For instance, a S3 remote needs a `AWS_ACCESS_KEY` and a `AWS_SECRET_ACCESS_KEY`, as follows: - -```yaml showLineNumbers -services: - localstack: - container_name: "localstack-main" - image: localstack/localstack-pro - ports: - - "127.0.0.1:4566:4566" - - "127.0.0.1:4510-4559:4510-4559" - environment: - - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} - - DEBUG=1 - - AWS_ACCESS_KEY_ID:... - - AWS_SECRET_ACCESS_KEY:... - volumes: - - "./volume:/var/lib/localstack" - - "./init-pods.d:/etc/localstack/init-pods.d" -``` - -:::note -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). -::: - ## End-to-End Encryption -Cloud Pods artifacts are stored in S3 buckets when using the LocalStack platform as the storage remote. +Cloud Pods' artifacts are stored in S3 buckets when using the LocalStack platform as the storage remote. By default, Amazon S3 encrypts all objects before saving them on disks, while the opposite operation happens at download time. This ensures encryption **at rest** for Cloud Pods. @@ -535,7 +320,7 @@ When this is not enough, LocalStack also offers end-to-end encryption for enterp To activate this feature, make sure to start LocalStack with the `POD_ENCRYPTION` environment variable set to 1. The next step is to generate a passphrase used to encrypt and decrypt the Cloud Pods' artifacts. -We advise to create a strong passphrase by using the `openssl` utility, e,g.: +We advise creating a strong passphrase by using the `openssl` utility, e.g.: ```bash openssl rand --base64 32 @@ -562,7 +347,7 @@ The process is the following: - Customers would have to export both their private and public keys into two files, `private.pgp` and `public.pgp` respectively. - These files need to be mounted in a specific `pods.keys.d` folder when starting LocalStack, i.e., `localstack start -v $PWD/pods.keys.d:/etc/localstack/pods.keys.d`. -- The `secret` option passed to the `save` and `load` command corresponds to the passphrase needed to import the private key into the LocalStack runtime. +- The `secret` option passed to the `save` and `load` commands corresponds to the passphrase needed to import the private key into the LocalStack runtime. ### Limitations @@ -570,111 +355,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. - -## State Merging - -Cloud Pods offers various strategies for integrating states into your LocalStack container. -The available strategies are: - -- `overwrite`: This strategy clears the existing state and loads the new state from the Cloud Pod, completely resetting the LocalStack state. -- `account-region-merge` (**default**): This strategy merges services based on account and region pairs. - It attempts to combine states from both the current state and the Cloud Pod for the same account and region. -- `service-merge`: This strategy merges services at the account-region level, provided there's no overlap in resources. - It prioritizes the loaded resources when merging. - -The LocalStack's default merge strategy can be changed via the `MERGE_STRATEGY` [configuration variable](/aws/customization/configuration-options/). - -### LocalStack CLI - -Every `pod load` operation uses the merge strategy set in `MERGE_STRATEGY` (`account-region-merge` by default). -When loading a Cloud Pod via the LocalStack CLI, set the `--strategy ` option to override the strategy in the configuration variable. -For instance, to load a Cloud Pod named `test-pod-s3-sqs` with the `service-merge` strategy, run the following command: - -```bash -localstack pod load test-pod-s3-sqs --strategy service-merge -``` - -### LocalStack Web Application - -To activate merge strategies, navigate to the **Cloud Pods** tab on the [Export/Import State page](https://app.localstack.cloud/inst/default/state). -Enter the name of the Cloud Pod, select the version, choose the strategy from a dropdown, and click **Load State from Pod**. - -![Merge Strategy Web UI](/images/aws/merge-strategy-web-app.png) - -### Example scenario - -Let us take the image below as example. -The two non overlapping account/region pairs (`0123456789/us-east-1` for the Cloud Pod and `0123456789/us-east-2` for the runtime) will be both present in the resulting state. -For `0123456789/eu-central-1` however, we encounter a conflict, since both the Cloud Pod and the container hold a SQS state. -With the `account-region-merge` strategy, the one from the Cloud Pod will be preserved. - -![Merge Strategies](/images/aws/merge-strategies.png) - -On the other hand, in the `service-merge` strategy, the SQS resulting state will have 2 distinct queues if the queue from the Cloud Pod and the one in the container are distinct, i.e., do not have the same ARN. -In case of an ARN conflict, only one queue, the one from the Cloud Pod, will be present in the result. - -### Dry Run - -To preview the changes that would occur when loading a Cloud Pod, you can use the `--dry-run` flag. -The result will depend on the selected merge strategy. -The result will be displayed in the console, and no changes will be made to the LocalStack state. - -```bash -This load operation will modify the runtime state as follows: - -──────────────────────────── sns ──────────────────────────── -+ 2 resources added. -~ 1 resources modified. - -──────────────────────── cognito-idp ──────────────────────── -+ 1 resources added. -~ 0 resources modified. - -──────────────────────────── sqs ──────────────────────────── -+ 1 resources added. -~ 1 resources modified. -``` - -## 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 [state compatibility rules](/aws/developer-tools/snapshots/persistence#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 diff --git a/src/content/docs/aws/developer-tools/snapshots/export-import-state.md b/src/content/docs/aws/developer-tools/snapshots/export-import-state.md deleted file mode 100644 index 2b8a726c0..000000000 --- a/src/content/docs/aws/developer-tools/snapshots/export-import-state.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Export & Import State -description: Export and import the state of the current infrastructure state into a file or a LocalStack instance respectively. -template: doc -tags: ["Base"] -sidebar: - order: 4 ---- - -## Introduction - -The Export/Import State feature enables you to export the state of your LocalStack instance into a file and import it into another LocalStack instance. -This feature is useful when you want to save your LocalStack instance's state for later use. - -## LocalStack CLI - -The LocalStack CLI enables you to export your infrastructure state to a file and import it into another LocalStack instance. -You can access the state management commands by running `localstack state` in your terminal. - -```bash -localstack state --help -``` - -```bash -Usage: localstack state [OPTIONS] COMMAND [ARGS]... - - (Preview) Manage and manipulate the localstack state. - - The state command group allows you to interact with LocalStack's state - backend. - - Read more: https://docs.localstack.cloud/references/persistence- - mechanism/#snapshot-based-persistence - -Options: - -h, --help Show this message and exit. - -Commands: - export Export the state of LocalStack services - import Import the state of LocalStack services - reset Reset the state of LocalStack services -``` - -### Export the State - -To export the state, you can run the following command: - -```bash -localstack state export -``` - -You can specify a file path to export the state to. -If you do not specify a file path, the state will be exported to the current working directory into a file named `ls-state-export`. -You can specify the following flags to customize the export: - -- `--services`: Specify the services to export. - You can specify multiple services by separating them with a comma. - If you do not specify any services, all services will be exported. -- `--format`: Specify the format of the exported state. - For example, you can specify `json` to specify the save command output as JSON. - -### Import the State - -To import the state, you can run the following command: - -```bash -localstack state import -``` - -The `` argument is required and specifies the file path to import the state from. -The file should be generated from a previous export. - -## Web Application - -The LocalStack Web Application enables you to export your infrastructure state to a file and import it into another LocalStack instance. -The Local mode allows you to perform local exports and imports of your LocalStack instance's state. - -![LocalStack Export/Import State Local Mode](/images/aws/export-import-state-local.png) - -### Export the State - -To export the state, follow these steps: - -1. Navigate to the **Local** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. -2. Create AWS resources locally as needed. -3. Click on the **Export State** button. - This action will initiate the download of a ZIP file. - -The downloaded ZIP file contains your container state, which can be injected into another LocalStack instance for further use. - -### Import the State - -To import the state, follow these steps: - -1. Navigate to the **Local** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. -2. Upload the ZIP file that contains your container state. - This action will restore your previously loaded AWS resources. - -To confirm the successful injection of the container state, visit the respective [Resource Browser](https://app.localstack.cloud/inst/default/resources) for the services and verify the resources. \ No newline at end of file diff --git a/src/content/docs/aws/developer-tools/snapshots/index.md b/src/content/docs/aws/developer-tools/snapshots/index.md deleted file mode 100644 index bbcc54ec6..000000000 --- a/src/content/docs/aws/developer-tools/snapshots/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Overview -description: State Management in LocalStack allows you to save and load the state of your LocalStack instance. -template: doc -sidebar: - order: 1 ---- - -LocalStack is designed to be ephemeral by default, meaning all state is lost when the container stops. State Management gives you tools to persist, reuse, and share the state of your LocalStack instance across sessions or teams. This is useful for preloading test data, debugging workflows, or collaborating with teammates. - -LocalStack supports three ways to manage and reuse state: - -* [**Cloud Pods**](/aws/developer-tools/snapshots/cloud-pods): Shareable, versioned snapshots of your LocalStack instance that can be stored, restored, and synced via the LocalStack platform. - -* [**Export & Import State**](/aws/developer-tools/snapshots/export-import-state): Save your instance state to a local file and reload it manually as needed. - -* [**Persistence**](/aws/developer-tools/snapshots/persistence): Automatically save and reload state locally by enabling a configuration flag. - -Internally, all three approaches manage the same container state. They just differ in how the state is stored and reused (local vs remote, manual vs automated). - -The diagram below helps compare these options at a glance. - -![The difference between persistence, local state and Cloud Pods.](/images/aws/persistence-pods-remote.png) - diff --git a/src/content/docs/aws/developer-tools/snapshots/index.mdx b/src/content/docs/aws/developer-tools/snapshots/index.mdx new file mode 100644 index 000000000..994257306 --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/index.mdx @@ -0,0 +1,69 @@ +--- +title: Overview +description: Snapshots in LocalStack allow you to save and load the state of your LocalStack instance. +template: doc +sidebar: + order: 1 +--- + +import { SectionCards } from '../../../../../components/SectionCards.tsx'; + +LocalStack is designed to be ephemeral by default, meaning all state is lost when the container stops. The _Snapshot_ feature provides tools to persist, reuse, and share the state of your LocalStack instance across sessions or teams. This is useful for preloading test data, debugging workflows, or collaborating with teammates. + +
+ Overview of the LocalStack snapshot lifecycle +
+ +Snapshots enhance your development workflow in the following ways: + +* **Faster loading** - Snapshots can be loaded into your instance within a few seconds. Use this to avoid lengthy redeploys of your infrastructure as code, such as Terraform or CDK, each time the emulator is started. + +* **Team sharing** - Use a repository, such as _Cloud Pods_, to share snapshots amongst your team. Snapshots provide a curated set of resources for team members to use as a starting point for their work. + +* **Automatic durability** - Enable the _Persistence_ feature to gain the same durability semantics you expect from the AWS cloud. A snapshot is taken automatically when the instance is shut down, or at user-defined periods during operation, then reloaded when the instance is restarted. + +* **Application Preview** - During the code review process, sharing a snapshot allows reviewers to see the software in action, without deploying it for themselves. + +* **Debugging failures** - Save the state of an instance after a failure has occurred, allowing debugging at a later time or by a different team member. + +For more detail, see the following sections: + + + +:::caution +Not all LocalStack services support snapshots. If you encounter a limitation, please [contact support](/aws/help-support/get-help/). +::: \ No newline at end of file diff --git a/src/content/docs/aws/developer-tools/snapshots/launchpad.md b/src/content/docs/aws/developer-tools/snapshots/launchpad.md index 4e0177a4b..1542f5730 100644 --- a/src/content/docs/aws/developer-tools/snapshots/launchpad.md +++ b/src/content/docs/aws/developer-tools/snapshots/launchpad.md @@ -4,7 +4,7 @@ description: Get started with Cloud Pods Launchpad to share and inject Cloud Pod template: doc tags: ["Ultimate"] sidebar: - order: 5 + order: 6 --- The LocalStack Cloud Pods Launchpad enables you to easily share and inject Cloud Pods into a LocalStack instance. diff --git a/src/content/docs/aws/developer-tools/snapshots/other-snapshot-storage-options.md b/src/content/docs/aws/developer-tools/snapshots/other-snapshot-storage-options.md new file mode 100644 index 000000000..a8de34fc9 --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/other-snapshot-storage-options.md @@ -0,0 +1,173 @@ +--- +title: Saving to other storage +description: Save Snapshots directly to Amazon S3, or to a OCI-compatible repository. +template: doc +tags: ["Base"] +sidebar: + order: 4 +--- + +LocalStack supports saving Snapshots directly to Amazon S3, or to an OCI-compatible repository, as an alternative to Cloud Pods or local storage. + +## Remotes + +A remote is the location where Cloud Pods are stored. +By default, Cloud Pod artifacts are stored in the LocalStack platform. +However, if your organization's data regulations or sovereignty requirements prohibit storing Cloud Pod assets in a remote storage infrastructure, you have the option to persist Cloud Pods in an on-premises storage location under your complete control. + +LocalStack provides two types of alternative remotes: + +- S3 bucket remote storage. +- [ORAS](https://oras.land/) (OCI Registry as Storage) remote storage. + +Cloud Pods command-line interface (CLI) allows you to create, delete, and list remotes. + +```bash +localstack pod remote --help +``` + +```bash +Usage: localstack pod remote [OPTIONS] COMMAND [ARGS]... + + Manage cloud pod remotes + +Options: + -h, --help Show this message and exit. + +Commands: + add Add a remote + delete Delete a remote + list List the available remotes +``` + +### S3 bucket remote storage + +The S3 remote enables you to store Cloud Pod assets in an existing S3 bucket within an actual AWS account. +The initial step is to export the necessary AWS credentials within the terminal session. + +```bash +export AWS_ACCESS_KEY_ID=... +export AWS_SECRET_ACCESS_KEY=... +``` + +A possible option is to obtain credentials via [AWS SSO CLI](https://github.com/synfinatic/aws-sso-cli). + +Next, we establish a new remote specifically designed for an S3 bucket. +By running the following command, we create a remote named `s3-storage-aws` responsible for storing Cloud Pod artifacts in an S3 bucket called `ls-pods-bucket-test`. + +The `access_key_id` and `secret_access_key` placeholders ensure the correct transmission of AWS credentials to the container. + +```bash +localstack pod remote add s3-storage-aws 's3://ls-pods-bucket-test/?access_key_id={access_key_id}&secret_access_key={secret_access_key}' +``` + +Lastly, you can utilize the standard `pod` CLI command to generate a new Cloud Pod that points to the previously established remote. + +```bash +localstack pod save my-pod s3-storage-aws +``` + +Once the command has been executed, you can confirm the presence of Cloud Pod artifacts in the S3 bucket by simply running: + +```bash +aws s3 ls s3://ls-pods-bucket-test +2023-09-27 13:50:10 83650 localstack-pod-my-pod-state-1.zip +2023-09-27 13:50:11 85103 localstack-pod-my-pod-version-1.zip +``` + +You can use the `pod load` command to load the same pod that was previously saved in this remote: + +```bash +localstack pod load my-pod s3-storage-aws +``` + +Similarly, you can list the Cloud Pods on this specific remote with the `pod list` command: + +```bash +localstack pod list s3-storage-aws +``` + +:::note +Full S3 remotes support is available in the CLI from version 3.2.0. +If you experience any difficulties, update your [LocalStack CLI](/aws/getting-started/installation/#update-localstack-cli). +::: + +### ORAS remote storage + +The ORAS remote enables users to store Cloud Pods in OCI-compatible registries like Docker Hub, Nexus, or ECS registries. +ORAS stands for "OCI Registry as Service," and you can find additional information about this standard [on the official website](https://oras.land/). + +For example, let's illustrate how you can utilize Docker Hub to store and retrieve Cloud Pods. + +To begin, you must configure the new remote using the LocalStack CLI. +You'll need to export two essential environment variables, `ORAS_USERNAME` and `ORAS_PASSWORD`, which are necessary for authenticating with Docker Hub. + +```bash +export ORAS_USERNAME=docker_hub_id +export ORAS_PASSWORD=ILoveLocalStack1! +``` + +You can now use the CLI to create a new remote called `oras-remote`. + +```bash +localstack pod remote add oras-remote 'oras://{oras_username}:{oras_password}@registry.hub.docker.com/' +``` + +Lastly, you can store a pod using the newly configured remote, where `my-pod` represents the Cloud Pod's name, and `oras-remote` is the remote's name. + +```bash +localstack pod save my-pod oras-remote +``` + +Likewise, you can execute the reverse operation to load a Cloud Pod from `oras-remote` using the following command: + +```bash +localstack pod load my-pod oras-remote +``` + +### Auto Load with remotes + +LocalStack also supports the auto load of a Cloud Pod from registered remotes. +The configuration is similar to what we just described. +In particular you could simply add the remote name to the text files inside the `init-pods.d`, as follows: + +```text +foo-pod,bar-remote +``` + +With such a configuration, the `foo-pod` Cloud Pod will be loaded from the `bar-remote` remote. +To properly configure the remote, you need to provide the needed environment variables when starting the LocalStack container. +For instance, a S3 remote needs a `AWS_ACCESS_KEY` and a `AWS_SECRET_ACCESS_KEY`, as follows: + +```yaml showLineNumbers +services: + localstack: + container_name: "localstack-main" + image: localstack/localstack-pro + ports: + - "127.0.0.1:4566:4566" + - "127.0.0.1:4510-4559:4510-4559" + environment: + - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} + - DEBUG=1 + - AWS_ACCESS_KEY_ID:... + - AWS_SECRET_ACCESS_KEY:... + volumes: + - "./volume:/var/lib/localstack" + - "./init-pods.d:/etc/localstack/init-pods.d" +``` + +:::note +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. diff --git a/src/content/docs/aws/developer-tools/snapshots/persistence.mdx b/src/content/docs/aws/developer-tools/snapshots/persistence.mdx index f68558d4d..100620335 100644 --- a/src/content/docs/aws/developer-tools/snapshots/persistence.mdx +++ b/src/content/docs/aws/developer-tools/snapshots/persistence.mdx @@ -1,31 +1,30 @@ --- title: Persistence -description: Internals of LocalStack persistence mechanism. +description: Enabling automatic persistence of data, providing enhanced durability. template: doc sidebar: - order: 3 + order: 5 tags: ["Base"] --- import { Tabs, TabItem, FileTree } from '@astrojs/starlight/components'; -## Introduction - -LocalStack's Persistence mechanism enables the saving and restoration of the entire LocalStack state, including all AWS resources and data, on your local machine. -It functions as a "pause and resume" feature, allowing you to take a snapshot of your LocalStack instance and save this data to disk. -This mechanism ensures a quick and efficient way to preserve and continue your work with AWS resources locally. +LocalStack's _Persistence_ mechanism uses snapshots to provide an enhanced level of durability, bringing it closer to the behavior you'd expect from a cloud-based service. +By default, LocalStack's internal state is emphemeral, reseting when the emulator is shutdown or exits unexpectedly. By enabling the Persistence feature, +LocalStack takes periodic snapshots of your emulator, then restores it upon restart. This reduces the likelihood of unexpected data loss. ## Configuration -To start snapshot-based persistence, launch LocalStack with the configuration option `PERSISTENCE=1`. -This setting instructs LocalStack to save all AWS resources and their respective application states into the LocalStack Volume Directory. -Upon restarting LocalStack, you'll be able to resume your activities exactly where you left off. +To start snapshot-based persistence, launch LocalStack with the `--persist` command line option, or the configuration option `PERSISTENCE=1`. +This instructs LocalStack to periodically generate a snapshot, storing it within LocalStack's internal volume directory. There is no visible +snapshot file (or Cloud Pod) created, as the snapshot is managed internally to LocalStack. + +Upon restarting LocalStack, the last successful snapshot is automatically reloaded, so you can resume your activities exactly where you left off. ```bash -LOCALSTACK_AUTH_TOKEN=... -PERSISTENCE=1 localstack start +lstk start --persist ``` @@ -38,7 +37,7 @@ volumes: - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" ``` - + ```bash docker run \ -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ @@ -51,24 +50,23 @@ docker run \ :::note -Snapshots may not be compatible across different versions of LocalStack. -LocalStack applies [state compatibility rules](#state-compatibility) that block loading state files known to be incompatible with the running LocalStack version. +Snapshots (stored in LocalStack's volume) may not remain compatible if you upgrade your 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. ::: ### Save strategies -LocalStack takes point-in-time snapshot of its state and dumps them to disk. -There are four strategies that you can choose from that govern when these snapshots are taken. +LocalStack generates periodic snapshots of the running emulator. There are four strategies you can choose from to govern when these snapshots are taken. You can select a particular save strategy by setting `SNAPSHOT_SAVE_STRATEGY=`. -* **`ON_REQUEST`**: On every AWS API call that potentially modifies the state of a service, LocalStack will save the state of that service. +* **`ON_REQUEST`**: On every AWS API call that potentially makes a modification, LocalStack saves the state of that service. This strategy minimizes the chance for data loss, but also has significant performance implications. - The service has to be locked during snapshotting, meaning that any requests to the particular AWS service will be blocked until the snapshot is complete. + The service must be locked during snapshotting, with any requests to the particular AWS service being blocked until the snapshot is complete. In many cases this is just a few milliseconds, but can become significant in some services. -* **`ON_SHUTDOWN`**: The state of all services are saved during the shutdown phase of LocalStack. - This strategy has zero performance impact, but is not good when you want to minimize the chance for data loss. +* **`ON_SHUTDOWN`**: The state of all services is saved during the shutdown phase of LocalStack. + This strategy has negliable performance impact, but is not good when you want to minimize the chance for data loss. Should LocalStack for some reason not shut down properly or is terminated before it can finalize the snapshot, you may be left with an incomplete state on disk. -* **`SCHEDULED`** (**default**): Saves at regular intervals the state of all the services that have been modified since the last snapshot. +* **`SCHEDULED`** (**default**): Saves the state of all services at regular intervals, as long as the state has been modified since the last snapshot. By default, the flush interval is 15 seconds. It can be configured via the `SNAPSHOT_FLUSH_INTERVAL` configuration variable. This is a compromise between `ON_REQUEST` and `ON_SHUTDOWN` in terms of performance and reliability. @@ -78,15 +76,15 @@ You can select a particular save strategy by setting `SNAPSHOT_SAVE_STRATEGY=`. -* **`ON_REQUEST`**: (**default**) The state is loaded lazily when the service is requested. +* **`ON_REQUEST`**: (**default**) The state is loaded lazily when the service is first used (that, the first API call to that service). This maintains LocalStack's lazy-loading behavior for AWS services. -* **`ON_STARTUP`**: The state of all services in the snapshot is restored when LocalStack starts up. - This means that services that have stored state are also started on LocalStack start, which will increase the startup time, but also give you immediate feedback whether the state was restored correctly. +* **`ON_STARTUP`**: The state of all services in the snapshot is restored when LocalStack starts up, before any of the services are accessed. This + reduces the cost of lazy-loading when the data is eventually accessed, but does cause an upfront delay to pre-load everything. * **`MANUAL`**: Turns off automatic loading of snapshots and gives you control through the internal state endpoints. ### Endpoints -As mentioned, with the `MANUAL` save or load strategy you can trigger snapshotting manually when it best suits your application flow. +With the `MANUAL` save or load strategy you can trigger snapshotting manually when it best suits your application flow. * `POST /_localstack/state//save` take a snapshot the given service * `POST /_localstack/state//load` load the most recent snapshot of the given service @@ -114,123 +112,3 @@ curl -X POST localhost:4566/_localstack/state/save {"service": "sqs", "status": "ok"} {"service": "s3", "status": "ok"} ``` - -## State compatibility - -The internal state format of LocalStack changes over time as services evolve. -To prevent silently loading state into an incompatible runtime, LocalStack ships a set of compatibility rules that compare the LocalStack version recorded in the saved state with the version of the running container. -The same rules apply to both [snapshot-based persistence](#configuration) and [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods). - -If a rule rejects the state, LocalStack does not load it and logs the reason. -The rules currently enforced are: - -| Rule | Behavior | -| - | - | -| Forward compatibility | Reject loading a state into a LocalStack version older than the one that produced it. | -| First CalVer release (`v2026.03`) | Reject loading state saved before `v2026.03` into LocalStack `v2026.03` or later. Persistence was rewritten for several services in the first calendar-versioned release. | - -Loading a state saved with `v2026.03` or later into a newer LocalStack version of the same series remains supported. -For example, a state saved with `v2026.03` can be loaded into `v2026.03.1` or `v2026.04`. - -### Disable compatibility checks - -If you understand the risks and want LocalStack to load state regardless of these rules, start the container with `DISABLE_COMPATIBILITY_RULES=1`. -This bypasses every compatibility rule and lets LocalStack attempt to load the state as-is. - - - -```bash -DISABLE_COMPATIBILITY_RULES=1 PERSISTENCE=1 localstack start -``` - - -```yaml showLineNumbers -image: localstack/localstack-pro -environment: - - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} - - PERSISTENCE=1 - - DISABLE_COMPATIBILITY_RULES=1 -volumes: - - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" -``` - - -```bash -docker run \ - -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ - -e PERSISTENCE=1 \ - -e DISABLE_COMPATIBILITY_RULES=1 \ - -v ./volume:/var/lib/localstack \ - -p 4566:4566 \ - localstack/localstack-pro -``` - - - -:::caution -Disabling compatibility rules can leave LocalStack in an inconsistent state. -Use this option only for debugging or when migrating data with a tested workaround in place. -::: - -## Service coverage - -Although we are working to support both snapshot-based persistence and Cloud pods for all AWS services, -there are some common issues, known limitations, and also services that are not well tested for persistence support. -An overview is available [here](#persistence-coverage-overview). - -:::note -When using LocalStack's persistence feature, ports assigned to services (like RDS or Elasticache) when the snapshot was created may not be preserved when loading a saved state. -If you start new services *before* restoring the previous state, these new instances may use ports originally used by the saved services. - -As a result, restored resources may point to invalid or unintended ports. -It is suggested to estore services in the same order as initially deployed, though this is not always reliable. -::: - -Please help us improve persistence support by reporting bugs on our [GitHub Discussion](https://github.com/orgs/localstack/discussions/new/choose). - -## Technical Details - -State persistence in LocalStack works on a per-service basis and uses a custom state serialization protocol based on [Python's pickle mechanism](https://docs.python.org/3/library/pickle.html). -Some services also store application-specific data, which we call _assets_. -For example, when you start an RDS PostgreSQL database, LocalStack not only stores the RDS resource information, but also the PostgreSQL data. -Another example is Kinesis, which persists some data in form of JSON objects per account, or DynamoDB that serializes its stat into an SQLite database per account and region. - -The current LocalStack snapshot is stored into `/var/lib/localstack/state`, and separated into `api_states` (LocalStack internal state), and assets (one directory per service). -Here is what this looks like: - - -- /var/lib/localstack/state # state directory - - api_states # serialized LocalStack stores - - dynamodb - - store.state - - ec2 - - backend.state - - iot - - store.state - - lambda - - store.state - - dynamodb # dynamodb assets - - 000000000000_eu-central-1.db - - 886002141588_us-east-1.db - - kinesis # kinesis assets - - 000000000000.json - - 886002141588.json - - -To load a snapshot, LocalStack traverses the state directory and deserializes state files to loads them into the memory. -When we restore server backends (like an RDS server or DynamoDB server), we make sure that they are configured to use the state stored in the respective asset directory. - -When LocalStack saves snapshots, it has to lock the particular service to avoid state pollution. -That means that, while a snapshot for a particular service is created, all requests to the service are blocked. -Depending on what you are building, you may find this behavior is slowing down your application. -In most cases, the `ON_SHUTDOWN` save strategy should solve this problem. - -import PersistenceCoverage from '../../../../../components/persistence-coverage/PersistenceCoverage.tsx'; - -## Persistence Coverage Overview - - - -### Terminology - -- **Persistence Test Suite**: tested by LocalStack's internal persistence test suite. To test persistence, we use an approach similar to snapshot parity testing. First, we record API responses from LocalStack, then we reset and restore the snapshotted state, and finally, we verify that the same API responses matches with the initial ones. diff --git a/src/content/docs/aws/developer-tools/snapshots/save-snapshots-locally.md b/src/content/docs/aws/developer-tools/snapshots/save-snapshots-locally.md new file mode 100644 index 000000000..045ac0e32 --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/save-snapshots-locally.md @@ -0,0 +1,159 @@ +--- +title: Saving locally +description: Saving and loading snapshots from local files. +template: doc +tags: ["Base"] +sidebar: + order: 2 +--- + +With Snapshots, you can save the state of your LocalStack instance to a local file on disk, then load it back at a later time. This concept is similar to desktop-based word processors, spreadsheets, or practically any software that allows saving and loading the program state. + +In addition, LocalStack's snapshot mechanism allows for loading multiple snapshot files into the same emulator instance, useful when multiple teams collaborate to build a running emulator image. + +## Using the `lstk` CLI + +The [`lstk` CLI](/aws/developer-tools/running-localstack/lstk/#snapshot) lets you save your instance's state to a local file and load it back into another instance at a later time. + +To save the state to a local file, run: + +```bash +lstk snapshot save my-snapshot +✔︎ Snapshot saved to ./my-snapshot.snapshot +``` + +The destination argument is optional. +If you omit it, `lstk` auto-generates a timestamped snapshot file in the current directory: + +```bash +lstk snapshot save +✔︎ Snapshot saved to ./snapshot-2026-07-19T22-20-46-31f.snapshot +``` + +Since saving is a common operation, the `lstk save` abbreviation is allowed: + +```bash +lstk save +✔︎ Snapshot saved to ./snapshot-2026-07-19T22-27-20-16e.snapshot +``` + +To load a previously saved snapshot, run: + +```bash +lstk snapshot load my-snapshot +✔︎ Snapshot loaded from ./my-snapshot.snapshot +``` + +Or alternatively, the `lstk load` command is allowed: + +```bash +lstk load my-snapshot +✔︎ Snapshot loaded from ./my-snapshot.snapshot +``` + + +## Snapshot Merging + +A common use case is when snapshots created by multiple teams must be loaded together into the same LocalStack instance. For example, a Platform team may create a snapshot containing VPCs, Subnets, S3 buckets, and SSM parameters. An Application team then produces their own snapshot (building on the first) that contains Lambda functions, S3 buckets, ECS images, and other application-level resources. It's therefore important to load multiple snapshots, one on top of the other. + +LocalStack supports several _merge strategies_ to support loading a snapshot into an existing emulator instance. You can think of this as loading two or more snapshots into the same emulator instance, one after the other. + +The chosen strategy can be passed to `lstk snapshot load` using the `--merge` option, or by setting the `LSTK_MERGE_STRATEGY` environment variable. + +```bash +lstk snapshot load --merge= +LSTK_MERGE_STRATEGY= lstk snapshot load +``` + +#### `overwrite` strategy + +This strategy completely resets the state of the instance before loading each new snapshot. This results in the instance containing the new snapshot's content, with resources from the older snapshot being completely discarded. + +![Merging snapshots using `--merge=overwrite`](/images/aws/snapshot-merge-overwrite.png) + +For this merge strategy, use the following: + +```bash +lstk snapshot load snapshot1 +lstk snapshot load --merge=overwrite snapshot2 + +lstk status + [...] + SNS topic3 us-east-1 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-3 us-east-1 000000000000 +``` + +#### `account-region-merge` strategy (**default**) + +Merge snapshots at the service level, for any given account and region. For example, if the first snapshot contains an SQS queue (`queue-1`) in the `000000000000/us-east-1` region, and the second snapshot contains a different SQS queue (`queue-3`), also in the `000000000000/us-east-1`region, the first snapshot's SQS resources are discarded. This strategy does not consider whether that the SQS queues have different names, since _all_ SQS resources in that region are discarded. + +![Merging snapshots using `--merge=account-region-merge`](/images/aws/snapshot-merge-account-region.png) + +For this merge strategy, use the following: + +```bash +lstk snapshot load snapshot1 +lstk snapshot load --merge=account-region-merge snapshot2 +``` + +```bash +lstk status + [...] + S3 bucket1 global 000000000000 + SNS topic2 ap-southeast-2 000000000000 + SNS topic3 us-east-1 000000000000 + SQS http://sqs.ap-southeast-2.localhost.localstack.cloud:4566/000000000000/queue-2 ap-southeast-2 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-3 us-east-1 000000000000 +``` + +#### `service-merge` strategy + +This strategy performs fine-grained merging, similar to the `account-region-merge` strategy, but also considers the names of resources. For example, if each snapshot contains an SQS queue, but the queues have different names (`queue-1` vs `queue-3`), the merge contains both queues. If the names are the same, the resource from the newer snapshot is kept. + +This is the same behaviour you'd expect if you applied two infrastructure-as-code stacks, one on top of the other. + +![Merging snapshots using `--merge=service-merge`](/images/aws/snapshot-merge-service.png) + +For this merge strategy, use the following: + +```bash +lstk snapshot load snapshot1 +lstk snapshot load --merge=service-merge snapshot2 + +lstk status + [...] + S3 bucket1 global 000000000000 + SNS topic1 us-east-1 000000000000 + SNS topic2 ap-southeast-2 000000000000 + SNS topic3 us-east-1 000000000000 + SQS http://sqs.ap-southeast-2.localhost.localstack.cloud:4566/000000000000/queue-2 ap-southeast-2 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-1 us-east-1 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-3 us-east-1 000000000000 +``` + +## Using the LocalStack Console + +The LocalStack Console allows saving a snapshot to a file, then loading it into another LocalStack instance. + +![LocalStack Export/Import State Local Mode](/images/aws/export-import-state-local.png) + +To save the snapshot, follow these steps: + +1. Create AWS resources locally as needed. +2. Navigate to the **Local** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. +3. Click on the **Export State** button. + This action will initiate the download of a ZIP file. + +The downloaded ZIP file contains your container state, which can be injected into another LocalStack instance for further use. + +To load an existing snapshot, follow these steps: + +1. Navigate to the **Local** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. +2. Upload the ZIP file that contains your container state. + This action will restore your previously loaded AWS resources. + +To confirm the successful injection of the container state, visit the respective [Resource Browser](https://app.localstack.cloud/inst/default/resources) for the services and verify the resources. + +:::note +Merge Strategies are not currently supported for file-based snapshots, using the LocalStack Console. +::: diff --git a/src/content/docs/aws/developer-tools/snapshots/service-coverage.mdx b/src/content/docs/aws/developer-tools/snapshots/service-coverage.mdx new file mode 100644 index 000000000..9abe72ba0 --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/service-coverage.mdx @@ -0,0 +1,88 @@ +--- +title: Service Coverage +description: Snapshot compatibility rules, and service coverage of LocalStack's snapshot mechanism. +template: doc +sidebar: + order: 7 +tags: ["Base"] +--- + +import { Tabs, TabItem, FileTree } from '@astrojs/starlight/components'; +import PersistenceCoverage from '../../../../../components/persistence-coverage/PersistenceCoverage.tsx'; + +This page covers two topics: the compatibility rules LocalStack enforces when loading a snapshot, and the current level of snapshot support across AWS services. + +## Snapshot compatibility + +The internal data structures inside a LocalStack emulator change over time as services evolve. +To prevent silently loading state into an incompatible runtime, LocalStack ships a set of compatibility rules that compare the LocalStack version recorded in the snapshot with the version of the running emulator. +These rules apply to all snapshots, whether saved locally to a file, saved to a Cloud Pod, or implicitly saved when persistence is enabled. + +If a rule rejects the snapshot, LocalStack does not load it, then logs the reason. +The rules currently enforced are: + +| Rule | Behavior | +| - | - | +| Forward compatibility | Reject loading a snapshot into a LocalStack emulator older than the one that produced it. | +| First CalVer release (`v2026.03`) | Reject loading a snapshot saved before `v2026.03` into LocalStack `v2026.03` or later. The snapshot mechanism was rewritten for several services in the first calendar-versioned release. | + +Loading a snapshot saved with `v2026.03` or later into a newer LocalStack version of the same series remains supported. +For example, a snapshot saved with `v2026.03` can be loaded into `v2026.03.1` or `v2026.04`. + +### Disable compatibility checks + +If you understand the risks and want LocalStack to load a snapshot regardless of these rules, start the container with `DISABLE_COMPATIBILITY_RULES=1`. +This bypasses every compatibility rule and lets LocalStack attempt to load the state as-is. + + + +```bash +DISABLE_COMPATIBILITY_RULES=1 lstk start --persist +``` + + +```yaml showLineNumbers +image: localstack/localstack-pro +environment: + - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} + - PERSISTENCE=1 + - DISABLE_COMPATIBILITY_RULES=1 +volumes: + - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" +``` + + +```bash +docker run \ + -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ + -e PERSISTENCE=1 \ + -e DISABLE_COMPATIBILITY_RULES=1 \ + -v ./volume:/var/lib/localstack \ + -p 4566:4566 \ + localstack/localstack-pro +``` + + + +:::caution +Disabling compatibility rules can leave LocalStack in an inconsistent state. +Use this option only for debugging or when migrating data with a tested workaround in place. +::: + +## Service coverage + +Although we are working to support snapshots for all AWS services, +there are some common issues, known limitations, and also services that are not well tested for snapshot support. +An overview is available [here](#snapshot-coverage-overview). + +For example, when using LocalStack's snapshot feature, ports assigned to certain services (such as RDS or Elasticache) may not be preserved when reloading that snapshot. +If you start new services *before* restoring the snapshot, these new instances may use ports originally used by the saved services. + +As a result, restored resources may point to invalid or unintended ports. +It is suggested to restore services in the same order as initially deployed, though this is not always reliable. + +If you encounter a limitation or bug with snapshot support, please [contact support](/aws/help-support/get-help/). + +## Snapshot Coverage Overview + + diff --git a/src/content/docs/aws/quickstart-library/application-inspection-tracing.mdx b/src/content/docs/aws/quickstart-library/application-inspection-tracing.mdx index 2366704d6..127c5c8a6 100644 --- a/src/content/docs/aws/quickstart-library/application-inspection-tracing.mdx +++ b/src/content/docs/aws/quickstart-library/application-inspection-tracing.mdx @@ -164,7 +164,7 @@ Now let's clear the instance and confirm it's actually gone and then restore it: 2. Back in the [**Stack Overview** tab](https://app.localstack.cloud/inst/default/overview), confirm the `messages-api` function and `Messages` table are no longer listed. LocalStack is ephemeral by default, so restarting the container discards everything. -3. Switch back to the [**State** tab](https://app.localstack.cloud/inst/default/state) and click the **Cloud** view. Under **Load State from Cloud Pod**, select `messages-api-demo` from the dropdown. You should see details about the pod displayed. Leave the default merge strategy (to learn more about merge strategies, see the [Cloud Pods documentation](https://docs.localstack.cloud/aws/developer-tools/snapshots/cloud-pods/#state-merging)) and click **Load State from Pod**. +3. Switch back to the [**State** tab](https://app.localstack.cloud/inst/default/state) and click the **Cloud** view. Under **Load State from Cloud Pod**, select `messages-api-demo` from the dropdown. You should see details about the pod displayed. Leave the default merge strategy (to learn more about merge strategies, see the [snapshot merging documentation](/aws/developer-tools/snapshots/save-snapshots-locally/#snapshot-merging)) and click **Load State from Pod**. ![Cloud Pods Load State from Cloud Pod dialog](/images/aws/load-state-from-pod.jpg) diff --git a/src/content/docs/aws/tutorials/cloud-pods-collaborative-debugging.mdx b/src/content/docs/aws/tutorials/cloud-pods-collaborative-debugging.mdx index dc95183cc..896b6a8e9 100644 --- a/src/content/docs/aws/tutorials/cloud-pods-collaborative-debugging.mdx +++ b/src/content/docs/aws/tutorials/cloud-pods-collaborative-debugging.mdx @@ -333,7 +333,7 @@ For organizations with specific data regulations, LocalStack offers multiple rem allowing full control with on-premises storage if needed. That way, Bob, Alice and Carol could collaborate using either an S3 bucket remote storage or an ORAS (OCI Registry as Storage) remote storage. The Cloud Pods command-line interface enables users to manage these remotes with ease, by following the instructions in the -[documentation](/aws/developer-tools/snapshots/cloud-pods#remotes). +[documentation](/aws/developer-tools/snapshots/other-snapshot-storage-options#remotes). ## Conclusion