Public documentation about persistence (#1259)

localstack · May 17, 2024 · ad4dfd3 · ad4dfd3
1 parent faa33e6
commit ad4dfd3
Show file tree

Hide file tree

Showing 46 changed files with 1,076 additions and 97 deletions.
diff --git a/.github/workflows/docs-persistence-updates.yml b/.github/workflows/docs-persistence-updates.yml
@@ -0,0 +1,64 @@
+name: Update Persistence Docs
+on:
+  schedule:
+    - cron: 0 5 * * MON
+  workflow_dispatch:
+    inputs:
+        targetBranch:
+          required: false
+          type: string
+          default: 'main'
+
+jobs:
+  update-persistence-docs:
+    name: Update Parity Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout docs
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          path: docs
+          ref: ${{ github.event.inputs.targetBranch || 'main' }}
+
+      - name: Set up Python 3.11
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Update Coverage Docs with Persistence Coverage
+        working-directory: docs
+        run: |
+          cd scripts/persistence
+          python3 -m venv .venv
+          source .venv/bin/activate
+          pip3 install -r requirements.txt
+          python3 create_persistence_docs.py
+        env:
+          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
+
+      - name: Check for changes
+        id: check-for-changes
+        working-directory: docs
+        run: |
+          # Check if there are changed files and store the result in resources/diff-check.log
+          # Check against the PR branch if it exists, otherwise against the main
+          # Store the result in resources/diff-check.log and store the diff count in the GitHub Action output "diff-count"
+          mkdir -p resources
+          (git diff --name-only origin/persistence-auto-updates data/persistence/ 2>/dev/null || git diff --name-only origin/${{ github.event.inputs.targetBranch || 'main' }} data/persistence/ 2>/dev/null) | tee -a resources/diff-check.log
+          echo "diff-count=$(cat resources/diff-check.log | wc -l)" >> $GITHUB_OUTPUT
+
+      - name: Create PR
+        uses: peter-evans/create-pull-request@v6
+        if: ${{ success() && steps.check-for-changes.outputs.diff-count != '0' && steps.check-for-changes.outputs.diff-count != '' }}
+        with:
+          path: docs
+          title: "Update Persistence Docs"
+          body: "Updating Persistence Coverage Documentation based on the [Persistence Catalog](https://www.notion.so/localstack/Persistence-Catalog-a9e0e5cb89df4784adb4a1ed377b3c23) on Notion."
+          branch: "persistence-auto-updates"
+          author: "LocalStack Bot <localstack-bot@users.noreply.github.com>"
+          committer: "LocalStack Bot <localstack-bot@users.noreply.github.com>"
+          commit-message: "update generated persistence docs"
+          token: ${{ secrets.PRO_ACCESS_TOKEN }}
+          reviewers: giograno
diff --git a/.gitignore b/.gitignore
@@ -24,6 +24,7 @@ resources
 **/*.orig
 .hugo_build.lock
 
-scripts/__pycache__
+**/__pycache__
+**/.venv
 target/
 scripts/target
diff --git a/config.toml b/config.toml
@@ -20,6 +20,7 @@ enableGitInfo = true
 [taxonomies]
 tag = "tags"
 category = "categories"
+persistence = "persistence"
 
 [params.taxonomy]
 # set taxonomyCloud = [] to hide taxonomy clouds
@@ -29,7 +30,7 @@ taxonomyCloud = []
 taxonomyCloudTitle = ["Tag Cloud", "Categories"] 
 
 # set taxonomyPageHeader = [] to hide taxonomies on the page headers
-taxonomyPageHeader = ["tags"]
+taxonomyPageHeader = ["tags", "persistence"]
 
 
 # Highlighting config

diff --git a/content/en/references/configuration.md b/content/en/references/configuration.md
@@ -30,7 +30,7 @@ Options that affect the core LocalStack system.
 | `GATEWAY_LISTEN`| `0.0.0.0:4566` (default in Docker mode) `127.0.0.1:4566` (default in host mode) | Configures the bind addresses of LocalStack. It has the form `<ip address>:<port>(,<ip address>:<port>)*`. LocalStack Pro adds port `443`. |
 | `LOCALSTACK_HOST`| `localhost.localstack.cloud:4566` (default) | This is interpolated into URLs and addresses that are returned by LocalStack. It has the form `<hostname>:<port>`. |
 | `USE_SSL` | `0` (default) | Whether to return URLs using HTTP (`0`) or HTTPS (`1`). Changed with 3.0.0. In earlier versions this was toggling SSL support on or off. |
-| `PERSISTENCE` | `0` (default) | Enable persistence. See [Persistence Mechanism]({{< ref "persistence" >}}) and [Filesystem Layout]({{< ref "filesystem" >}}). |
+| `PERSISTENCE` | `0` (default) | Enable persistence. See [Persistence Mechanism]({{< ref "user-guide/state-management/persistence" >}}) and [Filesystem Layout]({{< ref "filesystem" >}}). |
 | `MAIN_CONTAINER_NAME` | `localstack-main` (default) | Specify the main docker container name |
 | `LS_LOG` | `trace`, `trace-internal`, `debug`, `info`, `warn`, `error`, `warning`| Specify the log level. Currently overrides the `DEBUG` configuration. `trace` for detailed request/response, `trace-internal` for internal calls, too. |
 | `EXTERNAL_SERVICE_PORTS_START` | `4510` (default) | Start of the [External Service Port Range]({{< ref "external-ports" >}}) (inclusive). |
@@ -309,13 +309,13 @@ Please check with your SMTP email service provider for the following settings.
 
 ## Persistence
 
-To learn more about these configuration options, see [Persistence]({{< ref "persistence" >}}).
+To learn more about these configuration options, see [Persistence]({{< ref "user-guide/state-management/persistence" >}}).
 
 | Variable | Valid options | Description |
 | - | - | - |
 | `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]({{< ref "persistence" >}}))|
+| `SNAPSHOT_FLUSH_INTERVAL` | 15 (default) | The interval (in seconds) between persistence snapshots. It only applies to a `SCHEDULED` save strategy (see [Persistence Mechanism]({{< ref "user-guide/state-management/persistence" >}}))|
 | `AUTO_LOAD_POD` |  | Comma-separated list of Cloud Pods to be automatically loaded at startup time. This feature is disabled when snapshot persistence is set via the `PERSISTENCE` variable. |
 | `POD_LOAD_CLI_TIMEOUT` | 60 (default) | Timeout in seconds to wait before returning from load operations on the Cloud Pods CLI |
 

diff --git a/content/en/user-guide/aws/amplify/index.md b/content/en/user-guide/aws/amplify/index.md
@@ -1,9 +1,10 @@
 ---
 title: "Amplify"
 linkTitle: "Amplify"
-description: >
-  Get started with Amplify on LocalStack
+description: Get started with Amplify on LocalStack
 tags: ["Pro image"]
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/apigateway/index.md b/content/en/user-guide/aws/apigateway/index.md
@@ -1,9 +1,10 @@
 ---
 title: "API Gateway"
 linkTitle: "API Gateway"
-description: >
-  Get started with API Gateway on LocalStack
+description: Get started with API Gateway on LocalStack
 tags: ["Pro image"]
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/backup/index.md b/content/en/user-guide/aws/backup/index.md
@@ -3,6 +3,8 @@ title: "Backup"
 linkTitle: "Backup"
 description: Get started with Backup on LocalStack
 tags: ["Pro image"]
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/cloudfront/index.md b/content/en/user-guide/aws/cloudfront/index.md
@@ -1,9 +1,10 @@
 ---
 title: "CloudFront"
 linkTitle: "CloudFront"
-description: >
-  Get started with CloudFront on LocalStack
+description: Get started with CloudFront on LocalStack
 tags: ["Pro image"]
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/cloudtrail/index.md b/content/en/user-guide/aws/cloudtrail/index.md
@@ -1,9 +1,10 @@
 ---
 title: "CloudTrail"
 linkTitle: "CloudTrail"
-description: >
-  Get started with CloudTrail on LocalStack
+description: Get started with CloudTrail on LocalStack
 tags: ["Pro image"]
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/cloudwatch/index.md b/content/en/user-guide/aws/cloudwatch/index.md
@@ -3,7 +3,9 @@ title: "CloudWatch"
 linkTitle: "CloudWatch"
 description: Get started with AWS CloudWatch on LocalStack
 aliases:
-  - /aws/cloudwatch/
+- /aws/cloudwatch/
+persistence: supported
+
 ---
 
 CloudWatch is a comprehensive monitoring and observability service that Amazon Web Services (AWS) provides. It allows you to collect and track metrics, collect and monitor log files, and set alarms. CloudWatch provides valuable insights into your AWS resources, applications, and services, enabling you to troubleshoot issues, optimize performance, and make informed decisions.

diff --git a/content/en/user-guide/aws/codecommit/index.md b/content/en/user-guide/aws/codecommit/index.md
@@ -1,9 +1,10 @@
 ---
 title: "CodeCommit"
 linkTitle: "CodeCommit"
-description: >
-  Get started with CodeCommit on LocalStack
+description: Get started with CodeCommit on LocalStack
 tags: ["Pro image"]
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/cognito/index.md b/content/en/user-guide/aws/cognito/index.md
@@ -1,9 +1,10 @@
 ---
 title: "Cognito"
 linkTitle: "Cognito"
-description: >
-  Get started with Cognito on LocalStack
+description: Get started with Cognito on LocalStack
 tags: ["Pro image"]
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/config/index.md b/content/en/user-guide/aws/config/index.md
@@ -1,8 +1,9 @@
 ---
 title: "Config"
 linkTitle: "Config"
-description: >
-  Get started with Config on LocalStack
+description: Get started with Config on LocalStack
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/dynamodb/index.md b/content/en/user-guide/aws/dynamodb/index.md
@@ -2,6 +2,8 @@
 title: DynamoDB
 linkTitle: DynamoDB
 description: Get started with DynamoDB on LocalStack
+persistence: supported
+
 ---
 
 DynamoDB is a fully managed NoSQL database service provided by AWS.

diff --git a/content/en/user-guide/aws/ecr/index.md b/content/en/user-guide/aws/ecr/index.md
@@ -1,9 +1,10 @@
 ---
 title: "Elastic Container Registry (ECR)"
 linkTitle: "Elastic Container Registry (ECR)"
-description: >
-  Get started with Elastic Container Registry (ECR) on LocalStack
+description: Get started with Elastic Container Registry (ECR) on LocalStack
 tags: ["Pro image"]
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/elasticache/index.md b/content/en/user-guide/aws/elasticache/index.md
@@ -2,10 +2,11 @@
 title: "ElastiCache"
 linkTitle: "ElastiCache"
 categories: ["LocalStack Pro"]
-description: >
-  Get started with AWS ElastiCache on LocalStack
+description: Get started with AWS ElastiCache on LocalStack
 aliases:
-  - /aws/elasticache/
+- /aws/elasticache/
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/glacier/index.md b/content/en/user-guide/aws/glacier/index.md
@@ -3,6 +3,8 @@ title: "Glacier"
 linkTitle: "Glacier"
 description: Get started with S3 Glacier on LocalStack
 tags: ["Pro image"]
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/iam/index.md b/content/en/user-guide/aws/iam/index.md
@@ -1,8 +1,9 @@
 ---
 title: "Identity and Access Management (IAM)"
 linkTitle: "Identity and Access Management (IAM)"
-description: >
-  Get started with AWS Identity and Access Management (IAM) on LocalStack
+description: Get started with AWS Identity and Access Management (IAM) on LocalStack
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/kinesis/index.md b/content/en/user-guide/aws/kinesis/index.md
@@ -1,8 +1,9 @@
 ---
 title: "Kinesis"
 linkTitle: "Kinesis"
-description: >
-  Get started with Kinesis on LocalStack
+description: Get started with Kinesis on LocalStack
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/kms/index.md b/content/en/user-guide/aws/kms/index.md
@@ -1,8 +1,9 @@
 ---
 title: "Key Management Service (KMS)"
 linkTitle: "Key Management Service (KMS)"
-description: >
-  Get started with Key Management Service (KMS) on LocalStack
+description: Get started with Key Management Service (KMS) on LocalStack
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/lambda/index.md b/content/en/user-guide/aws/lambda/index.md
@@ -1,13 +1,14 @@
 ---
 title: "Lambda"
 linkTitle: "Lambda"
-description: >
-  Get started with Lambda on LocalStack
+description: Get started with Lambda on LocalStack
 aliases:
-  - /references/lambda-executors/
-  - /references/lambda-provider-v2/
-  - /references/lambda-asf-provider/
-  - /references/lambda-v2-provider/
+- /references/lambda-executors/
+- /references/lambda-provider-v2/
+- /references/lambda-asf-provider/
+- /references/lambda-v2-provider/
+persistence: supported with limitations
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/logs/index.md b/content/en/user-guide/aws/logs/index.md
@@ -3,7 +3,9 @@ title: "CloudWatch Logs"
 linkTitle: "CloudWatch Logs"
 description: Get started with AWS CloudWatch Logs on LocalStack
 aliases:
-  - /aws/logs/
+- /aws/logs/
+persistence: supported
+
 ---
 
 [CloudWatch Logs](https://docs.aws.amazon.com/cloudwatch/index.html) allows to store and retrieve logs. While some services automatically create and write logs (e.g. Lambda), logs can also be added manually. 

diff --git a/content/en/user-guide/aws/msk/index.md b/content/en/user-guide/aws/msk/index.md
@@ -1,9 +1,10 @@
 ---
 title: "Managed Streaming for Kafka (MSK)"
 linkTitle: "Managed Streaming for Kafka (MSK)"
-description: >
-  Get started with Managed Streaming for Kafka (MSK) on LocalStack
+description: Get started with Managed Streaming for Kafka (MSK) on LocalStack
 tags: ["Pro image"]
+persistence: supported with limitations
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/rds/index.md b/content/en/user-guide/aws/rds/index.md
@@ -1,9 +1,10 @@
 ---
 title: "Relational Database Service (RDS)"
 linkTitle: "Relational Database Service (RDS)"
-description: >
-  Get started with Relational Database Service (RDS) on LocalStack
+description: Get started with Relational Database Service (RDS) on LocalStack
 tags: ["Pro image"]
+persistence: supported with limitations
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/route53/index.md b/content/en/user-guide/aws/route53/index.md
@@ -2,6 +2,8 @@
 title: "Route 53"
 linkTitle: "Route 53"
 description: Get started with Route 53 on LocalStack
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/route53resolver/index.md b/content/en/user-guide/aws/route53resolver/index.md
@@ -2,6 +2,8 @@
 title: "Route 53 Resolver"
 linkTitle: "Route 53 Resolver"
 description: Get started with Route 53 Resolver on LocalStack
+persistence: supported
+
 ---
 
 ## Introduction

diff --git a/content/en/user-guide/aws/s3/index.md b/content/en/user-guide/aws/s3/index.md
@@ -1,8 +1,9 @@
 ---
 title: "Simple Storage Service (S3)"
 linkTitle: "Simple Storage Service (S3)"
-description: >
-  Get started with Amazon S3 on LocalStack
+description: Get started with Amazon S3 on LocalStack
+persistence: supported
+
 ---
 
 ## Introduction