diff --git a/src/content/docs/aws/capabilities/config/configuration.md b/src/content/docs/aws/capabilities/config/configuration.md index 83ca1f3b..6a8a6af1 100644 --- a/src/content/docs/aws/capabilities/config/configuration.md +++ b/src/content/docs/aws/capabilities/config/configuration.md @@ -401,6 +401,7 @@ To learn more about these configuration options, see [Persistence](/aws/capabili | `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/capabilities/state-management/persistence))| +| `DISABLE_COMPATIBILITY_RULES` | `0` (default) \| `1` | Disable the [state compatibility rules](/aws/capabilities/state-management/persistence#state-compatibility) that prevent loading incompatible state into LocalStack. Applies to both snapshot persistence and Cloud Pods. | ## Cloud Pods diff --git a/src/content/docs/aws/capabilities/state-management/cloud-pods.mdx b/src/content/docs/aws/capabilities/state-management/cloud-pods.mdx index 10c52cba..56e40752 100644 --- a/src/content/docs/aws/capabilities/state-management/cloud-pods.mdx +++ b/src/content/docs/aws/capabilities/state-management/cloud-pods.mdx @@ -669,6 +669,10 @@ Loading a Cloud Pod with mismatching version might lead to a corrupted state of Do you want to continue? [y/N]: ``` +In addition to this prompt, Cloud Pods are subject to the [state compatibility rules](/aws/capabilities/state-management/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. diff --git a/src/content/docs/aws/capabilities/state-management/persistence.mdx b/src/content/docs/aws/capabilities/state-management/persistence.mdx index 1bac3f95..8b179d02 100644 --- a/src/content/docs/aws/capabilities/state-management/persistence.mdx +++ b/src/content/docs/aws/capabilities/state-management/persistence.mdx @@ -52,8 +52,7 @@ docker run \ :::note Snapshots may not be compatible across different versions of LocalStack. -It is possible that snapshots from older versions can be restored, but there are no guarantees to whether LocalStack will start into a consistent state. -We are actively working on a solution for this problem. +LocalStack applies [state compatibility rules](#state-compatibility) that block loading state files known to be incompatible with the running LocalStack version. ::: ### Save strategies @@ -116,6 +115,63 @@ curl -X POST localhost:4566/_localstack/state/save {"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/capabilities/state-management/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,