diff --git a/agents.md b/agents.md new file mode 100644 index 000000000..b77ef3cf1 --- /dev/null +++ b/agents.md @@ -0,0 +1,545 @@ +# agents.md for LocalStack for AWS Docs + +This file is an MVP AI Documentation Agent tailored for the LocalStack for AWS documentation in our documentation repository. + +This agent will automate the research, verification, and drafting of service documentation, tutorials, and configuration guides while ensuring strict alignment with our internal technical standards. + +Read this file fully before making any changes. + +--- + +## How to Work on a Docs Task + +Follow this process for every task, in order. Do not skip steps. + +### Step 1: Understand the task + +Before writing anything, clarify: +- Which **product** is this for? (AWS, Snowflake, Azure) +- What **type of doc** is needed? (aws service doc, tutorial, configuration, getting-started, changelog entry, etc.) +- Is there an **existing doc** to update, or is this a **new doc**? +- Is there a **Linear ticket** with more context? + + +### Step 2: Research before writing + +Never write from memory, and never guess. Treat lack of documentation as a research puzzle, not an invitation to improvise. You must cross-reference real AWS behavior with LocalStack's actual implementation before drafting text. + +#### EXPLICIT HALT & CONSENT REQUIRED +If you encounter a conflict between what AWS docs state and what LocalStack code/coverage files support, **do not guess or gloss over it.** Stop and explicitly ask the user for clarification. State what you found, where the data thins out, and ask how they want the limitation or behavior documented. Never apply silent assumptions. + +#### Research Protocols by Doc Type + +**For AWS service docs:** +1. **Analyze LocalStack Coverage (Ground Truth):** Open and fully parse `src/data/coverage/.json`. Identify exactly which API operations are supported, supported with limitations, or completely missing. +2. **Read Existing Context:** Read the existing doc at `src/content/docs/aws/services/.mdx` entirely to understand what is currently exposed to users. +3. **Cross-Reference Live AWS Docs:** Look up the official AWS API reference documentation for that service. Verify the exact payload structures, required parameters, and intent of the API operations. +4. **Audit the Ecosystem:** + - Search the core LocalStack repo (`github.com/localstack/localstack`) for PRs, issues, or changelog entries matching the service/feature to catch undocumented quirks. + - Search `github.com/localstack-samples` to see if real, working sample applications already exist for this service. + +**For configuration or capability docs:** +1. Open and thoroughly review the existing files under `src/content/docs/aws/configuration/`. +2. Look up the specific environment variables or configuration flags in LocalStack's core source code or release notes to verify their exact type, default values, and behavioral impact. + +**For tutorials:** +1. Review 2-3 active tutorials under `src/content/docs/aws/tutorials/` to benchmark the depth and progression of instructions. +2. **Prerequisite Verification:** Mechanically verify that all required CLI tools, auth tokens, or Pro plans are listed. +3. **Live Link Audit:** Confirm that any linked sample repositories or external assets actually exist. No placeholder URLs. + +#### MANDATORY INTERNAL AUDIT TRAIL +For every new doc or major change you draft, you must generate a short **Audit Trail** in your response or PR scratchpad containing: +- **Sources Accessed:** Direct URLs to the official AWS documentation docs you referenced. +- **Coverage Files Parsed:** The exact path and key data metrics checked from `src/data/coverage/`. +- **Confidence & Gaps Assessment:** Explicitly state if data was thin or if you encountered places where LocalStack's behavior diverged from AWS. Note any features you deliberately omitted due to lack of verified local support. + +#### Anti-Hallucination Guardrails +- **Zero-Tolerance for Fictional APIs:** Never invent `awslocal` commands, CLI flags, configuration variables, or JSON output fields. If a flag or parameter is not explicitly found in active AWS documentation or LocalStack's data/source code, do not write it down. + + + +### Step 3: Check for existing patterns + +Before creating a new doc, read 2–3 similar existing docs to match their structure. For service docs, read `s3.mdx` and `lambda.mdx`. For tutorials, read any tutorial in `aws/tutorials/`. This repo has strong internal consistency, match it. + +### Step 4: Write + +Follow the writing conventions below. Draft the full doc, not just sections. + +### Step 5: Verify before finishing + +- Run `npm run build` to catch broken links and frontmatter errors. +- Check that all internal links use root-relative paths (`/aws/services/s3/`), never relative paths (`../../s3`). +- Confirm frontmatter fields match what `src/content.config.ts` allows because unknown fields cause build errors. +- If you renamed or moved a doc, add the old URL to `public/_redirects`. + +--- + +## Writing Style and Tone + +### Voice + +- **Direct and instructional.** Tell the user exactly what to do. +- **Second person.** Address the reader as "you." +- **Present tense.** "Run the following command" not "You will run the following command." +- **Active voice.** "LocalStack supports X" not "X is supported by LocalStack." +- No filler phrases like "In this section, we will explore..." Start with the content. + +### Tone markers + +- Professional but helpful. Not stiff, not casual. +- When noting limitations, be factual and specific: "LocalStack does not support X" or "X is not yet supported in LocalStack and will be available in a future release." +- Link to AWS docs when explaining AWS concepts. Do not re-explain what AWS already explains well. + +### What to always include in a service doc + +1. **Introduction**: What the AWS service does (2–4 sentences). What LocalStack lets you do with it. Link to the API coverage section. +2. **Getting started**: A short, self-contained walkthrough using `awslocal` commands. Assume the user has LocalStack running. Show real commands with real expected output. +3. **Feature sections**: Cover notable behaviors, limitations, or LocalStack-specific quirks. Use `:::note` or `:::tip` callouts for important caveats. +4. **Resource Browser**: If the service has a LocalStack Web App Resource Browser, include a section with a screenshot and a bulleted list of actions available. +5. **Examples**: Links to relevant sample apps from `github.com/localstack-samples` or tutorials on the docs site. +6. **API Coverage**: Always end with the `` component. + +### What to always include in a tutorial + +1. **Introduction**: The problem being solved and what the reader will build. +2. **Architecture diagram**: If the tutorial involves multiple services, include a diagram. +3. **Prerequisites**: Bulleted list: LocalStack, awslocal, any other tools. State if Pro plan is required. +4. **Step-by-step tutorial**: Use `###` for each step. Each step should have a clear goal, the command(s) to run, and the expected output. +5. No "Summary" section at the end: just end with the last meaningful step or a "Next steps" pointing to related content. + +--- + +## doc Structure Templates + +### Service doc (MDX) + +````mdx +--- +title: "Service Name (Abbreviation)" +description: Get started with [Service Name] on LocalStack +tags: ["Hobby"] +persistence: supported # or: "supported with limitations" or omit if not applicable +--- + +import FeatureCoverage from "../../../../components/feature-coverage/FeatureCoverage"; + +## Introduction + +[2–4 sentences: what the AWS service does. What LocalStack lets you do with it.] + +LocalStack allows you to use the [Service] APIs in your local environment to [key actions]. +The supported APIs are available on the [API coverage section](#api-coverage). + +## Getting started + +This guide is designed for users new to [Service] and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. + +Start your LocalStack container using your preferred method. + +### [First task] + +[Explanation sentence.] + +```bash +awslocal --option value +``` + +```bash title="Output" +{ + "Field": "value" +} +``` + +## [Feature or behavior section] + +[Explain a notable LocalStack-specific behavior, limitation, or configuration option.] + +:::note +[Important caveat or limitation.] +::: + +## Resource Browser + +The LocalStack Web Application provides a [Resource Browser](/aws/connecting/console/resource-browser) for managing [Service] resources. +You can access the Resource Browser by opening the LocalStack Web Application in your browser, navigating to the **Resources** section, and then clicking on **[Service]**. + +![Resource Browser](/images/aws/-resource-browser.png) + +The Resource Browser allows you to perform the following actions: + +- **Action One**: Description. +- **Action Two**: Description. + +## Examples + +The following code snippets and sample applications provide practical examples of how to use [Service] in LocalStack: + +- [Description of sample app](https://github.com/localstack-samples/sample-...) + +## API Coverage + + +```` + +### Tutorial doc (MDX) + +````mdx +--- +title: "Tutorial title — what the user will build" +description: Learn how to [goal] using [services] with LocalStack. [One more sentence of context.] +services: + - s3 + - lmb +platform: + - Python +deployment: + - terraform +pro: true # only if LocalStack Pro is required +leadimage: "tutorial-banner-filename.png" +--- + +## Introduction + +[Problem statement. What the reader will build. Why it matters.] + +## Architecture + +![Architecture Diagram](/images/aws/tutorial-diagram.png) + +[2–3 sentences describing the architecture.] + +## Prerequisites + +- [LocalStack](https://localstack.cloud/) with an [auth token](https://app.localstack.cloud/workspace/auth-tokens) (Pro plan required) +- [awslocal](https://github.com/localstack/awscli-local) +- [Other tool](link) + +## Tutorial: [Goal] + +### Step 1 — [Action] + +[Explanation.] + +```bash +command here +``` + +### Step 2 — [Action] + + +```` + +--- + +## Code Examples + +### CLI commands + +Always use `awslocal` (not `aws`). Every command block must: +- Show the command itself +- Show the expected output in a separate block with `title="Output"` + +````mdx +```bash +awslocal s3api create-bucket --bucket my-bucket +``` + +```bash title="Output" +{ + "Location": "/my-bucket" +} +``` +```` + +### Multi-line commands + +Use `\` for line continuation: + +```bash +awslocal lambda create-function \ + --function-name my-function \ + --runtime python3.11 \ + --handler handler.handler \ + --role arn:aws:iam::000000000000:role/lambda-role \ + --zip-file fileb://function.zip +``` + +### File content blocks + +Use `title` to label the filename and `showLineNumbers` for longer snippets: + +````mdx +```json title="cors-config.json" showLineNumbers +{ + "CORSRules": [...] +} +``` +```` + +### Callout types + +Use Starlight callout syntax: + +````mdx +:::note +Use this for important caveats, limitations, or things that differ from AWS behavior. +::: + +:::tip +Use this for helpful shortcuts or recommendations. +::: + +:::caution +Use this for destructive or irreversible actions. +::: +```` + +--- + +## Linking + +### Internal links + +Always use **root-relative paths**. Never use relative paths (`../../`). + +```mdx +[SDK documentation](/aws/configuration/localstack-sdks/) +[API coverage](/aws/services/s3/#api-coverage) +``` + +Relative links will fail the build (`starlightLinksValidator` treats them as errors). + +### AWS documentation links + +Link to AWS docs when explaining AWS concepts users may not know: + +```mdx +[`CreateBucket`](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-bucket.html) +``` + +### Sample app links + +Link to `github.com/localstack-samples` for examples, not inline code snippets. Use descriptive link text: + +```mdx +- [Full-Stack application with Lambda, DynamoDB & S3 for shipment validation](https://github.com/localstack-samples/sample-shipment-list-demo-lambda-dynamodb-s3) +``` + +--- + +## Tech Stack + +| Layer | Technology | +|-------|-----------| +| Framework | [Astro](https://astro.build/) 7.x with [Starlight](https://starlight.astro.build/) 0.41.x | +| Markup | MDX (primary) and Markdown | +| UI components | React 19 (Astro islands via `client:load`) | +| Styling | Tailwind CSS v4 + custom CSS | +| Code highlighting | Expressive Code (Shiki, themes: one-light / one-dark-pro) | +| Search | Algolia DocSearch | +| Deployment | Cloudflare docs (static build to `dist/`) | +| Package manager | npm | + +--- + +## Repository Structure + +``` +localstack-docs/ +├── src/ +│ ├── content/docs/ # All documentation docs (MDX/MD) +│ │ ├── aws/ # AWS product docs +│ │ ├── snowflake/ # Snowflake product docs +│ │ └── azure/ # Azure product docs +│ ├── components/ # Astro + React components +│ │ ├── ui/ # shadcn-style table component +│ │ ├── feature-coverage/ # API coverage tables +│ │ ├── cloudformation-coverage/ +│ │ ├── snowflake-coverage/ +│ │ ├── kubernetes-operator/ +│ │ ├── licensing-coverage/ +│ │ ├── persistence-coverage/ +│ │ ├── replicator-coverage/ +│ │ ├── tutorials/ +│ │ └── applications/ +│ ├── data/ # JSON source data (coverage, licensing, etc.) +│ ├── assets/images/ # SVG icons and logos +│ ├── styles/ # global.css, custom.css (Tailwind layers + icon classes) +│ ├── fonts/ # Aeonik font families (Pro, Fono, Mono) +│ ├── hooks/ # React hooks +│ ├── lib/ # Utility functions (cn() for Tailwind) +│ ├── config/ # Algolia DocSearch config +│ ├── content.config.ts # Content collection schema (Zod) +│ └── routeData.ts # Starlight route middleware +├── public/ +│ ├── _redirects # Cloudflare docs 301 redirects +│ ├── _headers # Security & CORS headers +│ ├── images/ # Static images (screenshots, favicons) +│ ├── js/ # Vanilla JS (icon-loader.js) +│ └── .well-known/ # Agent/MCP discovery endpoints +├── scripts/ # Data generation and sync scripts +├── astro.config.mjs # Main Astro + Starlight config +├── ec.config.mjs # Expressive Code config +├── markdoc.config.mjs # Markdoc processor config +├── tsconfig.json # TypeScript (strict mode) +└── package.json +``` + +--- + +## Three Products, Three Sidebars + +| Product | Content path | Sidebar | +|---------|-------------|---------| +| AWS | `src/content/docs/aws/` | AWS sidebar | +| Snowflake | `src/content/docs/snowflake/` | Snowflake sidebar | +| Azure | `src/content/docs/azure/` | Azure sidebar | + +Sidebars are auto-generated from directory structure — adding a file in the right directory is enough to make it appear. + +### AWS content layout + +``` +aws/ +├── index.mdx +├── getting-started/ # Installation, quickstart, auth token, FAQ +├── configuration/ # ← was "capabilities/" before July 2026 +│ ├── config/ # Environment vars, initialization hooks, logging +│ ├── networking/ # Port mapping, DNS, endpoint injection +│ ├── web-app/ # LocalStack Web App UI +│ ├── localstack-sdks/ # Python SDK, Java SDK +│ └── extensions/ # Developing and managing extensions +├── developer-tools/ # CLI, Lambda tools, snapshots, MCP server +├── connecting/ # AWS CLI, SDKs, Console, IDEs +├── services/ # One .mdx per AWS service (100+ files) +├── tutorials/ # Step-by-step tutorials +├── integrations/ # CI/CD, containers, frameworks +├── enterprise/ # Kubernetes, SSO +├── help-support/ # FAQ, troubleshooting +└── changelog.md +``` + +> **Important:** The directory was renamed from `aws/capabilities/` to `aws/configuration/` in mid-2026. All new content goes in `aws/configuration/`. Old URLs are covered by `public/_redirects`. + +--- + +## Frontmatter + +Every doc requires at minimum `title` and `description`. The schema is enforced by Zod in `src/content.config.ts` — **unknown fields cause a build error**. + +| Field | Type | Purpose | +|-------|------|---------| +| `title` | string | doc heading — **required** | +| `description` | string | SEO meta description — **required** | +| `template` | `"doc"` | Explicit Starlight template (usually omitted) | +| `sidebar.order` | number | Position within its sidebar group | +| `sidebar.label` | string | Custom sidebar label | +| `sidebar.collapsed` | boolean | Collapse group by default | +| `tags` | string[] | Custom tags (managed by sync script — do not bulk-edit) | +| `services` | string[] | AWS services covered (tutorials only) | +| `platform` | string[] | Programming languages/platforms (tutorials only) | +| `deployment` | string[] | Deployment tools (tutorials only) | +| `pro` | boolean | Requires Pro plan (tutorials only) | +| `leadimage` | string | Hero image filename (tutorials only) | +| `persistence` | string | Persistence support level (service docs) | +| `editUrl` | `false` | Hide "Edit on GitHub" link | +| `hideCopydoc` | boolean | Hide the "Copy doc" dropdown | + +--- + +## Components + +### Starlight built-ins + +```mdx +import { Tabs, TabItem, Code, LinkButton, Steps, Aside } from '@astrojs/starlight/components'; +``` + +### Custom React components (require `client:load`) + +```mdx +import FeatureCoverage from "../../../../components/feature-coverage/FeatureCoverage"; + + +``` + +| Component | Purpose | +|-----------|---------| +| `FeatureCoverage` | AWS API coverage table — always at the bottom of service docs | +| `AzureFeatureCoverage` | Azure API coverage table | +| `OverviewCards` | Hero and overview card grids | +| `HeroCards` | Large CTAs on landing docs | +| `SearchableAwsServices` | Searchable + filterable service list | +| `DocsFeedback` | Inline helpfulness feedback form | + +### doc-level overrides (do not edit without understanding site-wide impact) + +| Component | What it overrides | +|-----------|-------------------| +| `docTitleWithCopyButton.astro` | doc title — adds "Copy to AI" dropdown | +| `docSidebarWithBadges.astro` | Sidebar — injects pricing tier badges | +| `BannerWithPersistentAnnouncement.astro` | Site-wide announcement banner | +| `FooterWithFeedback.astro` | Footer with feedback form | +| `StarlightHead.astro` | `` — PostHog, HubSpot, Reo tracking | + +--- + +## Build and Dev Commands + +```bash +npm run dev # Dev server at http://localhost:4321 +npm run build # Production build → ./dist/ +npm run preview # Preview production build locally +npm run lint:links # Build + validate all links (same as build) +npm run sync:licensing-tags # Sync pricing tags from src/data/licensing/ +``` + +Always run `npm run build` before opening a PR. Broken links and invalid frontmatter are caught at build time. + +--- + +## Data-Driven Content + +Do not hand-edit these docs — they are auto-generated. Edit the source data and re-run the script. + +| Generated content | Source data | Script | +|-------------------|-------------|--------| +| AWS service coverage tables | `src/data/coverage/` | `scripts/create_data_coverage.py` | +| Azure coverage tables | `src/data/azure-coverage/` | `scripts/create_azure_coverage.py` | +| CloudFormation tables | `src/data/cloudformation/` | `scripts/create_cloudformation_coverage.py` | +| CLI reference docs | External | `scripts/generate_cli_docs.py` | +| Extensions docs | External | `scripts/generate_extensions_docs.py` | +| Pricing tags | `src/data/licensing/current-plans.json` | `scripts/sync-licensing-tags.mjs` | + +--- + +## Redirects + +When renaming or restructuring docs, add entries to `public/_redirects` (Cloudflare docs format): + +``` +/old/path /new/path 301 +``` + +There are 80+ existing redirects. Check for conflicts before adding new ones. + +--- + +## Key Gotchas + +1. **No relative links.** Use root-relative paths (`/aws/services/s3/`). Relative paths (`../../s3`) fail the build. + +2. **`aws/capabilities/` is now `aws/configuration/`.** Rename happened mid-2026. All new content goes in `aws/configuration/`. + +3. **Frontmatter schema is strict.** Unknown fields throw a Zod error at build time. Check `src/content.config.ts` first. + +4. **Pricing tags are synced via script.** Don't bulk-edit `tags:` frontmatter. Update the JSON source and run the sync script. + +5. **React components need `client:load`** to be interactive. Without it, they render as static HTML with no JS. + +6. **Some docs are auto-generated.** Check `scripts/` before editing service coverage, CLI docs, or extension docs — changes will be overwritten. + +7. **`editUrl: false`** on landing docs and auto-generated docs to hide the "Edit on GitHub" link. + +8. **Agent discovery endpoints** in `public/.well-known/` — do not remove or relocate. diff --git a/astro.config.mjs b/astro.config.mjs index 948833d63..285a4a642 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -389,6 +389,13 @@ export default defineConfig({ collapsed: true, items: [{ autogenerate: { directory: '/aws/getting-started' } }], }, + { + label: 'Quickstart Library', + collapsed: true, + items: [ + { autogenerate: { directory: '/aws/quickstart-library' } }, + ], + }, { label: 'Local AWS Services', slug: 'aws/services', @@ -604,7 +611,8 @@ export default defineConfig({ items: [ { autogenerate: { - directory: '/aws/customization/integrations/extensions', + directory: + '/aws/customization/integrations/extensions', }, }, { @@ -619,7 +627,8 @@ export default defineConfig({ items: [ { autogenerate: { - directory: '/aws/customization/integrations/localstack-sdks', + directory: + '/aws/customization/integrations/localstack-sdks', }, }, ], @@ -630,7 +639,8 @@ export default defineConfig({ items: [ { autogenerate: { - directory: '/aws/customization/integrations/app-frameworks', + directory: + '/aws/customization/integrations/app-frameworks', }, }, ], @@ -641,7 +651,8 @@ export default defineConfig({ items: [ { autogenerate: { - directory: '/aws/customization/integrations/testing', + directory: + '/aws/customization/integrations/testing', }, }, ], diff --git a/public/_redirects b/public/_redirects index 06a227afc..f894dd159 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 @@ -38,13 +38,13 @@ /user-guide/tools/testing-utils/ /aws/customization/integrations/localstack-sdks/testing-utils/ 301 /user-guide/aws/codedeploy/ /aws/services/codedeploy/ 301 /references/coverage/coverage_serverlessrepo/ /aws/services/serverlessrepo/ 301 -/user-guide/aws/resource_groups/ /aws/services/resource_groups/ 301 +/user-guide/aws/resource_groups/ /aws/services/resource-groups/ 301 /references/coverage/coverage_glue/ /aws/services/glue/ 301 /user-guide/aws/ssm/ /aws/services/ssm/ 301 /references/coverage/coverage_sts/ /aws/services/sts/ 301 /academy/localstack-101/course-overview/ https://www.youtube.com/watch?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0&v=VLL-BI1AWcc&feature=youtu.be 301 /user-guide/aws/iotwireless/ /aws/services/iotwireless/ 301 -/user-guide/integrations/sdks/python/ /aws/connecting/aws-sdks/net/python/ 301 +/user-guide/integrations/sdks/python/ /aws/connecting/aws-sdks/python-boto3/ 301 /user-guide/integrations/crossplane/ /aws/connecting/infrastructure-as-code/crossplane/ 301 /references/coverage/coverage_elbv2/ /aws/services/elb/ 301 /user-guide/integrations/openshift/ /aws/customization/kubernetes/openshift/ 301 @@ -75,7 +75,6 @@ /references/coverage/coverage_kms/ /aws/services/kms/ 301 /applications/step-up-authentication-using-amazon-cognito/ https://github.com/localstack-samples/sample-cdk-cognito-dynamodb-api-gateway 301 /references/coverage/coverage_athena/ /aws/services/athena/ 301 -/user-guide/aws/mediastore/ /aws/services/mediastore/ 301 /references/coverage/coverage_fis/ /aws/services/fis/ 301 /user-guide/aws/logs/ /aws/services/logs/ 301 /academy/localstack-deployment/infra-cloudformation/ https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=K0OgQ5eq588&feature=youtu.be 301 @@ -86,7 +85,6 @@ /references/credentials/ /aws/connecting/credentials/ 301 /references/coverage/coverage_elasticbeanstalk/ /aws/services/elasticbeanstalk/ 301 /user-guide/web-application/instance-management/ /aws/connecting/console/instance-management/ 301 -/references/coverage/coverage_qldb/ /aws/services/qldb/ 301 /academy/localstack-deployment/iam-policy-stream/ https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=TOBLG2Z6xAM&feature=youtu.be 301 /references/cross-account-access/ /aws/customization/advanced/cross-account-access/ 301 /tutorials/reproducible-machine-learning-cloud-pods/ /aws/tutorials/reproducible-machine-learning-cloud-pods/ 301 @@ -120,12 +118,11 @@ /user-guide/localstack-enterprise/single-sign-on/azure-ad/ /aws/organizations-admin/sso/azure-ad/ 301 /user-guide/tools/localstack-desktop/ /aws/developer-tools/running-localstack/localstack-desktop/ 301 /references/coverage/coverage_es/ /aws/services/es/ 301 -/user-guide/integrations/sdks/javascript/ /aws/connecting/aws-sdks/net/javascript/ 301 +/user-guide/integrations/sdks/javascript/ /aws/connecting/aws-sdks/javascript/ 301 /references/coverage/coverage_iam/ /aws/services/iam/ 301 /user-guide/tools/localsurf/ /aws/customization/networking/localsurf/ 301 /user-guide/extensions/extensions-library/ /aws/customization/integrations/extensions/extensions-library/ 301 /tutorials/ecs-ecr-container-app/ /aws/tutorials/ecs-ecr-container-app/ 301 -/references/coverage/coverage_elastictranscoder/ /aws/services/elastictranscoder/ 301 /user-guide/aws/feature-coverage/ /aws/services/ 301 /user-guide/aws/lambda/ /aws/services/lambda/ 301 /references/iam-coverage/ /aws/developer-tools/security-testing/iam-coverage/ 301 @@ -142,7 +139,6 @@ /user-guide/aws/kinesisanalyticsv2/ /aws/services/kinesisanalyticsv2/ 301 /user-guide/state-management/cloud-pods/ /aws/developer-tools/snapshots/cloud-pods/ 301 /references/coverage/coverage_transcribe/ /aws/services/transcribe/ 301 -/references/coverage/coverage_mediastore-data/ /aws/services/mediastore/ 301 /user-guide/aws/route53/ /aws/services/route53/ 301 /user-guide/aws/config/ /aws/services/config/ 301 /references/coverage/coverage_identitystore/ /aws/services/identitystore/ 301 @@ -158,7 +154,7 @@ /developer-hub/ /aws/sample-apps/ 301 /references/coverage/coverage_firehose/ /aws/services/firehose/ 301 /user-guide/aws/verifiedpermissions/ /aws/services/verifiedpermissions/ 301 -/references/coverage/coverage_kinesisanalytics/ /aws/services/kinesisanalytics/ 301 +/references/coverage/coverage_kinesisanalytics/ /aws/services/kinesisanalyticsv2/ 301 /user-guide/aws/sns/ /aws/services/sns/ 301 /user-guide/tools/aws-replicator/ /aws/developer-tools/aws-replicator/ 301 /user-guide/integrations/serverless-framework/ /aws/connecting/infrastructure-as-code/serverless-framework/ 301 @@ -168,7 +164,7 @@ /user-guide/ci/bitbucket/ /aws/ci-pipelines/bitbucket/ 301 /contributing/ https://github.com/localstack/localstack/blob/main/docs/CONTRIBUTING.md 301 /user-guide/aws/scheduler/ /aws/services/scheduler/ 301 -/user-guide/integrations/quarkus/ /aws/integrations/app-frameworks/quarkus/ 301 +/user-guide/integrations/quarkus/ /aws/customization/integrations/app-frameworks/quarkus/ 301 /user-guide/aws/servicediscovery/ /aws/services/servicediscovery/ 301 /academy/localstack-101/ https://www.youtube.com/playlist?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0&si=rKhzdxOJsfO_pgyk 301 /user-guide/aws/xray/ /aws/services/xray/ 301 @@ -178,18 +174,17 @@ /user-guide/aws/apigateway/ /aws/services/apigateway/ 301 /user-guide/integrations/cloud-custodian/ /aws/connecting/infrastructure-as-code/cloud-custodian/ 301 /references/coverage/coverage_lambda/ /aws/services/lambda/ 301 -/user-guide/integrations/sdks/java/ /aws/connecting/aws-sdks/net/java/ 301 +/user-guide/integrations/sdks/java/ /aws/connecting/aws-sdks/java/ 301 /references/coverage/coverage_logs/ /aws/services/logs/ 301 -/references/coverage/coverage_mediastore/ /aws/services/mediastore/ 301 /user-guide/integrations/kafka/ /aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster/ 301 -/user-guide/chaos-engineering/fault-injection-service/ /aws/developer-tools/chaos-engineering/fault-injection-service/ 301 +/user-guide/chaos-engineering/fault-injection-service/ /aws/developer-tools/chaos-engineering/aws-fault-injection/ 301 /references/logging/ /aws/customization/logging/ 301 /tutorials/java-notification-app/ /aws/tutorials/java-notification-app/ 301 /applications/serverless-transcription-application-using-transcribe-s3-lambda-sqs-and-ses/ https://github.com/localstack-samples/sample-serverless-transcribe 301 /user-guide/aws/route53resolver/ /aws/services/route53resolver/ 301 /references/coverage/coverage_wafv2/ /aws/services/waf/ 301 -/user-guide/integrations/sdks/cpp/ /aws/connecting/aws-sdks/net/cpp/ 301 -/user-guide/integrations/testcontainers/ /aws/integrations/testing/testcontainers/ 301 +/user-guide/integrations/sdks/cpp/ /aws/connecting/aws-sdks/cpp/ 301 +/user-guide/integrations/testcontainers/ /aws/customization/integrations/testing/testcontainers/ 301 /references/internal-endpoints/ /aws/customization/networking/internal-endpoints/ 301 /tutorials/lambda-ecr-container-images/ /aws/tutorials/lambda-ecr-container-images/ 301 /user-guide/aws/fis/ /aws/services/fis/ 301 @@ -199,9 +194,9 @@ /user-guide/web-application/resource-browser/ /aws/connecting/console/resource-browser/ 301 /applications/loan-broker-application-with-aws-step-functions-dynamodb-lambda-sqs-and-sns/ https://github.com/localstack-samples/sample-loan-broker-stepfunctions-lambda 301 /references/coverage/coverage_resource-groups/ /aws/services/resource-groups/ 301 -/user-guide/state-management/support/ /aws/developer-tools/snapshots/persistence-coverage/ 301 +/user-guide/state-management/support/ /aws/developer-tools/snapshots/persistence/ 301 /references/coverage/coverage_redshift/ /aws/services/redshift/ 301 -/user-guide/integrations/lambdatest-hyperexecute/ /aws/integrations/testing/lambdatest-hyperexecute/ 301 +/user-guide/integrations/lambdatest-hyperexecute/ /aws/customization/integrations/testing/lambdatest-hyperexecute/ 301 /applications/ /aws/sample-apps/ 301 /user-guide/web-application/users-and-licenses/ /aws/organizations-admin/managing-users-licenses/ 301 /user-guide/tools/localstack-sdk/ /aws/customization/integrations/localstack-sdks/ 301 @@ -247,7 +242,6 @@ /user-guide/aws/iot-data/ /aws/services/iot-data/ 301 /references/coverage/coverage_textract/ /aws/services/textract/ 301 /references/coverage/coverage_codebuild/ /aws/services/codebuild/ 301 -/user-guide/aws/elastictranscoder/ /aws/services/elastictranscoder/ 301 /references/coverage/coverage_glacier/ /aws/services/glacier/ 301 /user-guide/tools/ /aws/developer-tools/ 301 /user-guide/aws/timestream/ /aws/services/timestream-query/ 301 @@ -260,7 +254,7 @@ /user-guide/aws/kinesis/ /aws/services/kinesis/ 301 /references/coverage/coverage_bedrock-runtime/ /aws/services/bedrock/ 301 /references/coverage/coverage_iot-data/ /aws/services/iot-data/ 301 -/user-guide/cloud-sandbox/ephemeral-instance/ /aws/developer-tools/cloud-sandbox/ephemeral-instance/ 301 +/user-guide/cloud-sandbox/ephemeral-instance/ /aws/developer-tools/cloud-sandbox/ephemeral-instances/ 301 /references/coverage/coverage_timestream-write/ /aws/services/timestream-query/ 301 /user-guide/aws/pinpoint/ /aws/services/pinpoint/ 301 /tutorials/cloud-pods-collaborative-debugging/ /aws/tutorials/cloud-pods-collaborative-debugging/ 301 @@ -283,10 +277,10 @@ /references/coverage/coverage_ecr/ /aws/services/ecr/ 301 /academy/localstack-deployment/ https://www.youtube.com/playlist?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&si=R-Ed-JQKOxXP473O 301 /references/coverage/coverage_application-autoscaling/ /aws/services/application-autoscaling/ 301 -/user-guide/lambda-tools/debugging/ /aws/developer-tools/lambda-tools/debugging/ 301 +/user-guide/lambda-tools/debugging/ /aws/developer-tools/lambda-tools/remote-debugging/ 301 /references/coverage/coverage_codestar-connections/ /aws/services/codeconnections/ 301 /user-guide/integrations/rancher-desktop/ /aws/customization/other-installations/rancher-desktop/ 301 -/user-guide/integrations/sdks/ruby/ /aws/connecting/aws-sdks/net/ruby/ 301 +/user-guide/integrations/sdks/ruby/ /aws/connecting/aws-sdks/ruby/ 301 /user-guide/aws/mwaa/ /aws/services/mwaa/ 301 /academy/localstack-deployment/deploy-app-ls/ https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=qIB79b-iw2U&feature=youtu.be 301 /user-guide/aws/organizations/ /aws/services/organizations/ 301 @@ -295,19 +289,18 @@ /references/configuration/ /aws/customization/configuration-options/ 301 /user-guide/chaos-engineering/chaos-api/ /aws/developer-tools/chaos-engineering/chaos-api/ 301 /user-guide/aws/glacier/ /aws/services/glacier/ 301 -/references/coverage/coverage_qldb-session/ /aws/services/qldb/ 301 /user-guide/integrations/pulumi/ /aws/connecting/infrastructure-as-code/pulumi/ 301 /user-guide/aws/cloudtrail/ /aws/services/cloudtrail/ 301 /references/coverage/coverage_s3/ /aws/services/s3/ 301 /user-guide/aws/emr/ /aws/services/emr/ 301 /user-guide/tools/dns-server/ /aws/customization/networking/dns-server/ 301 -/user-guide/chaos-engineering/chaos-application-dashboard/ /aws/developer-tools/chaos-engineering/chaos-application-dashboard/ 301 +/user-guide/chaos-engineering/chaos-application-dashboard/ /aws/developer-tools/chaos-engineering/chaos-engineering-dashboard/ 301 /references/coverage/coverage_route53/ /aws/services/route53/ 301 /references/coverage/coverage_dynamodbstreams/ /aws/services/dynamodbstreams/ 301 /references/coverage/coverage_dynamodb/ /aws/services/dynamodb/ 301 /user-guide/aws/ec2/ /aws/services/ec2/ 301 /user-guide/cloud-sandbox/application-previews/ /aws/developer-tools/cloud-sandbox/app-preview/ 301 -/user-guide/integrations/spring-cloud-function/ /aws/integrations/app-frameworks/spring-cloud-function/ 301 +/user-guide/integrations/spring-cloud-function/ /aws/customization/integrations/app-frameworks/spring-cloud-function/ 301 /references/multi-account-setups/ /aws/customization/advanced/multi-account-setups/ 301 /user-guide/aws/elementalmediaconvert/ /aws/services/mediaconvert/ 301 /references/coverage/coverage_shield/ /aws/services/shield/ 301 @@ -322,7 +315,7 @@ /references/coverage/coverage_appconfig/ /aws/services/appconfig/ 301 /references/coverage/coverage_iot/ /aws/services/iot/ 301 /getting-started/installation/ /aws/getting-started/installation/ 301 -/user-guide/integrations/architect/ /aws/integrations/app-frameworks/architect/ 301 +/user-guide/integrations/architect/ /aws/customization/integrations/app-frameworks/architect/ 301 /user-guide/integrations/gitpod/ /aws/customization/other-installations/ 301 /user-guide/aws/managedblockchain/ /aws/services/managedblockchain/ 301 /applications/query-data-in-s3-bucket-with-amazon-athena-glue-catalog-cloudformation/ https://github.com/localstack-samples/sample-query-data-s3-athena-glue 301 @@ -337,7 +330,7 @@ /user-guide/aws/iot/ /aws/services/iot/ 301 /user-guide/aws/backup/ /aws/services/backup/ 301 /references/coverage/coverage_organizations/ /aws/services/organizations/ 301 -/user-guide/aws/kinesisanalytics/ /aws/services/kinesisanalytics/ 301 +/user-guide/aws/kinesisanalytics/ /aws/services/kinesisanalyticsv2/ 301 /user-guide/localstack-enterprise/single-sign-on/ /aws/organizations-admin/sso/ 301 /user-guide/aws/redshift/ /aws/services/redshift/ 301 /references/coverage/coverage_verifiedpermissions/ /aws/services/verifiedpermissions/ 301 @@ -345,7 +338,7 @@ /applications/full-stack-application-with-aws-lambda-dynamodb-s3-for-shipment-validation/ https://github.com/localstack-samples/sample-shipment-list-demo-lambda-dynamodb-s3 301 /user-guide/integrations/chalice/ /aws/connecting/infrastructure-as-code/aws-chalice/ 301 /user-guide/security-testing/iam-policy-stream/ /aws/developer-tools/security-testing/iam-policy-stream/ 301 -/user-guide/security-testing/iam-enforcement/ /aws/developer-tools/security-testing/iam-enforcement/ 301 +/user-guide/security-testing/iam-enforcement/ /aws/developer-tools/security-testing/iam-policy-enforcement/ 301 /references/coverage/coverage_route53resolver/ /aws/services/route53resolver/ 301 /references/coverage/coverage_config/ /aws/services/config/ 301 /references/coverage/coverage_account/ /aws/services/account/ 301 @@ -363,7 +356,7 @@ /user-guide/aws/elasticache/ /aws/services/elasticache/ 301 /tutorials/using-terraform-with-testcontainers-and-localstack/ /aws/tutorials/using-terraform-with-testcontainers-and-localstack/ 301 /references/coverage/coverage_cloudfront/ /aws/services/cloudfront/ 301 -/user-guide/tools/localstack-sdk/java/ /aws/user-guide/tools/localstack-sdk/java/ 301 +/user-guide/tools/localstack-sdk/java/ /aws/customization/integrations/localstack-sdks/java-sdk/ 301 /references/network-troubleshooting/readme/ /aws/customization/networking/ 301 /user-guide/aws/codecommit/ /aws/services/codecommit/ 301 /references/coverage/coverage_swf/ /aws/services/swf/ 301 @@ -372,32 +365,32 @@ /references/init-hooks/ /aws/customization/advanced/initialization-hooks/ 301 /references/coverage/coverage_support/ /aws/services/support/ 301 /user-guide/ /aws/ 301 -/user-guide/aws/qldb/ /aws/services/qldb/ 301 /tutorials/simulating-outages/ /aws/tutorials/simulating-outages/ 301 /user-guide/aws/acm/ /aws/services/acm/ 301 -/user-guide/integrations/sdks/php/ /aws/connecting/aws-sdks/net/php/ 301 +/user-guide/integrations/sdks/php/ /aws/connecting/aws-sdks/php/ 301 /references/coverage/coverage_sns/ /aws/services/sns/ 301 -/getting-started/help-and-support/ /aws/getting-started/help-support/ 301 +/getting-started/help-and-support/ /aws/help-support/ 301 /user-guide/aws/amplify/ /aws/services/amplify/ 301 /references/coverage/coverage_lakeformation/ /aws/services/lakeformation/ 301 -/user-guide/integrations/sdks/dotnet/ /aws/connecting/aws-sdks/net/dotnet/ 301 +/user-guide/integrations/sdks/dotnet/ /aws/connecting/aws-sdks/dotnet/ 301 /academy/ https://www.youtube.com/playlist?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0 301 /references/coverage/coverage_cloudwatch/ /aws/services/cloudwatch/ 301 /user-guide/aws/ecr/ /aws/services/ecr/ 301 /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 /references/coverage/coverage_cognito-idp/ /aws/services/cognito-idp/ 301 /user-guide/web-application/workspace/ /aws/organizations-admin/workspaces/ 301 /references/coverage/coverage_cloudcontrol/ /aws/services/cloudcontrol/ 301 -/tutorials/replicate-aws-resources-localstack-extension/ /aws/tutorials/replicate-aws-resources-localstack-extension/ 301 +/tutorials/replicate-aws-resources-localstack-extension/ /aws/developer-tools/aws-replicator/ 301 /user-guide/tools/localstack-sdk/python/ /aws/customization/integrations/localstack-sdks/python-sdk/ 301 /user-guide/lambda-tools/hot-reloading/ /aws/developer-tools/lambda-tools/hot-reloading/ 301 -/getting-started/quickstart/ /aws/getting-started/quickstart/ 301 +/getting-started/quickstart/ /aws/getting-started/local-development/ 301 +/aws/getting-started/quickstart/ /aws/getting-started/local-development/ 301 /overview/ /aws/ 301 /user-guide/aws/glue/ /aws/services/glue/ 301 /getting-started/ /aws/getting-started/ 301 @@ -437,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 @@ -445,13 +438,13 @@ /user-guide/tools/testing-utils /aws/customization/integrations/localstack-sdks/testing-utils/ 301 /user-guide/aws/codedeploy /aws/services/codedeploy/ 301 /references/coverage/coverage_serverlessrepo /aws/services/serverlessrepo/ 301 -/user-guide/aws/resource_groups /aws/services/resource_groups/ 301 +/user-guide/aws/resource_groups /aws/services/resource-groups/ 301 /references/coverage/coverage_glue /aws/services/glue/ 301 /user-guide/aws/ssm /aws/services/ssm/ 301 /references/coverage/coverage_sts /aws/services/sts/ 301 /academy/localstack-101/course-overview https://www.youtube.com/watch?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0&v=VLL-BI1AWcc&feature=youtu.be 301 /user-guide/aws/iotwireless /aws/services/iotwireless/ 301 -/user-guide/integrations/sdks/python /aws/connecting/aws-sdks/net/python/ 301 +/user-guide/integrations/sdks/python /aws/connecting/aws-sdks/python-boto3/ 301 /user-guide/integrations/crossplane /aws/connecting/infrastructure-as-code/crossplane/ 301 /references/coverage/coverage_elbv2 /aws/services/elb/ 301 /user-guide/integrations/openshift /aws/customization/kubernetes/openshift/ 301 @@ -482,7 +475,6 @@ /references/coverage/coverage_kms /aws/services/kms/ 301 /applications/step-up-authentication-using-amazon-cognito https://github.com/localstack-samples/sample-cdk-cognito-dynamodb-api-gateway 301 /references/coverage/coverage_athena /aws/services/athena/ 301 -/user-guide/aws/mediastore /aws/services/mediastore/ 301 /references/coverage/coverage_fis /aws/services/fis/ 301 /user-guide/aws/logs /aws/services/logs/ 301 /academy/localstack-deployment/infra-cloudformation https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=K0OgQ5eq588&feature=youtu.be 301 @@ -493,7 +485,6 @@ /references/credentials /aws/connecting/credentials/ 301 /references/coverage/coverage_elasticbeanstalk /aws/services/elasticbeanstalk/ 301 /user-guide/web-application/instance-management /aws/connecting/console/instance-management/ 301 -/references/coverage/coverage_qldb /aws/services/qldb/ 301 /academy/localstack-deployment/iam-policy-stream https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=TOBLG2Z6xAM&feature=youtu.be 301 /references/cross-account-access /aws/customization/advanced/cross-account-access/ 301 /tutorials/reproducible-machine-learning-cloud-pods /aws/tutorials/reproducible-machine-learning-cloud-pods/ 301 @@ -527,12 +518,11 @@ /user-guide/localstack-enterprise/single-sign-on/azure-ad /aws/organizations-admin/sso/azure-ad/ 301 /user-guide/tools/localstack-desktop /aws/developer-tools/running-localstack/localstack-desktop/ 301 /references/coverage/coverage_es /aws/services/es/ 301 -/user-guide/integrations/sdks/javascript /aws/connecting/aws-sdks/net/javascript/ 301 +/user-guide/integrations/sdks/javascript /aws/connecting/aws-sdks/javascript/ 301 /references/coverage/coverage_iam /aws/services/iam/ 301 /user-guide/tools/localsurf /aws/customization/networking/localsurf/ 301 /user-guide/extensions/extensions-library /aws/customization/integrations/extensions/extensions-library/ 301 /tutorials/ecs-ecr-container-app /aws/tutorials/ecs-ecr-container-app/ 301 -/references/coverage/coverage_elastictranscoder /aws/services/elastictranscoder/ 301 /user-guide/aws/feature-coverage /aws/services/ 301 /user-guide/aws/lambda /aws/services/lambda/ 301 /references/iam-coverage /aws/developer-tools/security-testing/iam-coverage/ 301 @@ -549,7 +539,6 @@ /user-guide/aws/kinesisanalyticsv2 /aws/services/kinesisanalyticsv2/ 301 /user-guide/state-management/cloud-pods /aws/developer-tools/snapshots/cloud-pods/ 301 /references/coverage/coverage_transcribe /aws/services/transcribe/ 301 -/references/coverage/coverage_mediastore-data /aws/services/mediastore/ 301 /user-guide/aws/route53 /aws/services/route53/ 301 /user-guide/aws/config /aws/services/config/ 301 /references/coverage/coverage_identitystore /aws/services/identitystore/ 301 @@ -565,7 +554,7 @@ /developer-hub /aws/sample-apps/ 301 /references/coverage/coverage_firehose /aws/services/firehose/ 301 /user-guide/aws/verifiedpermissions /aws/services/verifiedpermissions/ 301 -/references/coverage/coverage_kinesisanalytics /aws/services/kinesisanalytics/ 301 +/references/coverage/coverage_kinesisanalytics /aws/services/kinesisanalyticsv2/ 301 /user-guide/aws/sns /aws/services/sns/ 301 /user-guide/tools/aws-replicator /aws/developer-tools/aws-replicator/ 301 /user-guide/integrations/serverless-framework /aws/connecting/infrastructure-as-code/serverless-framework/ 301 @@ -575,7 +564,7 @@ /user-guide/ci/bitbucket /aws/ci-pipelines/bitbucket/ 301 /contributing https://github.com/localstack/localstack/blob/master/docs/CONTRIBUTING.md 301 /user-guide/aws/scheduler /aws/services/scheduler/ 301 -/user-guide/integrations/quarkus /aws/integrations/app-frameworks/quarkus/ 301 +/user-guide/integrations/quarkus /aws/customization/integrations/app-frameworks/quarkus/ 301 /user-guide/aws/servicediscovery /aws/services/servicediscovery/ 301 /academy/localstack-101 https://www.youtube.com/playlist?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0&si=rKhzdxOJsfO_pgyk 301 /user-guide/aws/xray /aws/services/xray/ 301 @@ -585,18 +574,17 @@ /user-guide/aws/apigateway /aws/services/apigateway/ 301 /user-guide/integrations/cloud-custodian /aws/connecting/infrastructure-as-code/cloud-custodian/ 301 /references/coverage/coverage_lambda /aws/services/lambda/ 301 -/user-guide/integrations/sdks/java /aws/connecting/aws-sdks/net/java/ 301 +/user-guide/integrations/sdks/java /aws/connecting/aws-sdks/java/ 301 /references/coverage/coverage_logs /aws/services/logs/ 301 -/references/coverage/coverage_mediastore /aws/services/mediastore/ 301 /user-guide/integrations/kafka /aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster/ 301 -/user-guide/chaos-engineering/fault-injection-service /aws/developer-tools/chaos-engineering/fault-injection-service/ 301 +/user-guide/chaos-engineering/fault-injection-service /aws/developer-tools/chaos-engineering/aws-fault-injection/ 301 /references/logging /aws/customization/logging/ 301 /tutorials/java-notification-app /aws/tutorials/java-notification-app/ 301 /applications/serverless-transcription-application-using-transcribe-s3-lambda-sqs-and-ses https://github.com/localstack-samples/sample-serverless-transcribe 301 /user-guide/aws/route53resolver /aws/services/route53resolver/ 301 /references/coverage/coverage_wafv2 /aws/services/waf/ 301 -/user-guide/integrations/sdks/cpp /aws/connecting/aws-sdks/net/cpp/ 301 -/user-guide/integrations/testcontainers /aws/integrations/testing/testcontainers/ 301 +/user-guide/integrations/sdks/cpp /aws/connecting/aws-sdks/cpp/ 301 +/user-guide/integrations/testcontainers /aws/customization/integrations/testing/testcontainers/ 301 /references/internal-endpoints /aws/customization/networking/internal-endpoints/ 301 /tutorials/lambda-ecr-container-images /aws/tutorials/lambda-ecr-container-images/ 301 /user-guide/aws/fis /aws/services/fis/ 301 @@ -606,9 +594,9 @@ /user-guide/web-application/resource-browser /aws/connecting/console/resource-browser/ 301 /applications/loan-broker-application-with-aws-step-functions-dynamodb-lambda-sqs-and-sns https://github.com/localstack-samples/sample-loan-broker-stepfunctions-lambda 301 /references/coverage/coverage_resource-groups /aws/services/resource-groups/ 301 -/user-guide/state-management/support /aws/developer-tools/snapshots/persistence-coverage/ 301 +/user-guide/state-management/support /aws/developer-tools/snapshots/persistence/ 301 /references/coverage/coverage_redshift /aws/services/redshift/ 301 -/user-guide/integrations/lambdatest-hyperexecute /aws/integrations/testing/lambdatest-hyperexecute/ 301 +/user-guide/integrations/lambdatest-hyperexecute /aws/customization/integrations/testing/lambdatest-hyperexecute/ 301 /applications /aws/sample-apps/ 301 /user-guide/web-application/users-and-licenses /aws/organizations-admin/managing-users-licenses/ 301 /user-guide/tools/localstack-sdk /aws/customization/integrations/localstack-sdks/ 301 @@ -654,7 +642,6 @@ /user-guide/aws/iot-data /aws/services/iot-data/ 301 /references/coverage/coverage_textract /aws/services/textract/ 301 /references/coverage/coverage_codebuild /aws/services/codebuild/ 301 -/user-guide/aws/elastictranscoder /aws/services/elastictranscoder/ 301 /references/coverage/coverage_glacier /aws/services/glacier/ 301 /user-guide/tools /aws/developer-tools/ 301 /user-guide/aws/timestream /aws/services/timestream-query/ 301 @@ -667,7 +654,7 @@ /user-guide/aws/kinesis /aws/services/kinesis/ 301 /references/coverage/coverage_bedrock-runtime /aws/services/bedrock/ 301 /references/coverage/coverage_iot-data /aws/services/iot-data/ 301 -/user-guide/cloud-sandbox/ephemeral-instance /aws/developer-tools/cloud-sandbox/ephemeral-instance/ 301 +/user-guide/cloud-sandbox/ephemeral-instance /aws/developer-tools/cloud-sandbox/ephemeral-instances/ 301 /references/coverage/coverage_timestream-write /aws/services/timestream-query/ 301 /user-guide/aws/pinpoint /aws/services/pinpoint/ 301 /tutorials/cloud-pods-collaborative-debugging /aws/tutorials/cloud-pods-collaborative-debugging/ 301 @@ -690,10 +677,10 @@ /references/coverage/coverage_ecr /aws/services/ecr/ 301 /academy/localstack-deployment https://www.youtube.com/playlist?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&si=R-Ed-JQKOxXP473O 301 /references/coverage/coverage_application-autoscaling /aws/services/application-autoscaling/ 301 -/user-guide/lambda-tools/debugging /aws/developer-tools/lambda-tools/debugging/ 301 +/user-guide/lambda-tools/debugging /aws/developer-tools/lambda-tools/remote-debugging/ 301 /references/coverage/coverage_codestar-connections /aws/services/codeconnections/ 301 /user-guide/integrations/rancher-desktop /aws/customization/other-installations/rancher-desktop/ 301 -/user-guide/integrations/sdks/ruby /aws/connecting/aws-sdks/net/ruby/ 301 +/user-guide/integrations/sdks/ruby /aws/connecting/aws-sdks/ruby/ 301 /user-guide/aws/mwaa /aws/services/mwaa/ 301 /academy/localstack-deployment/deploy-app-ls https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=qIB79b-iw2U&feature=youtu.be 301 /user-guide/aws/organizations /aws/services/organizations/ 301 @@ -702,19 +689,18 @@ /references/configuration /aws/customization/configuration-options/ 301 /user-guide/chaos-engineering/chaos-api /aws/developer-tools/chaos-engineering/chaos-api/ 301 /user-guide/aws/glacier /aws/services/glacier/ 301 -/references/coverage/coverage_qldb-session /aws/services/qldb/ 301 /user-guide/integrations/pulumi /aws/connecting/infrastructure-as-code/pulumi/ 301 /user-guide/aws/cloudtrail /aws/services/cloudtrail/ 301 /references/coverage/coverage_s3 /aws/services/s3/ 301 /user-guide/aws/emr /aws/services/emr/ 301 /user-guide/tools/dns-server /aws/customization/networking/dns-server/ 301 -/user-guide/chaos-engineering/chaos-application-dashboard /aws/developer-tools/chaos-engineering/chaos-application-dashboard/ 301 +/user-guide/chaos-engineering/chaos-application-dashboard /aws/developer-tools/chaos-engineering/chaos-engineering-dashboard/ 301 /references/coverage/coverage_route53 /aws/services/route53/ 301 /references/coverage/coverage_dynamodbstreams /aws/services/dynamodbstreams/ 301 /references/coverage/coverage_dynamodb /aws/services/dynamodb/ 301 /user-guide/aws/ec2 /aws/services/ec2/ 301 /user-guide/cloud-sandbox/application-previews /aws/developer-tools/cloud-sandbox/app-preview/ 301 -/user-guide/integrations/spring-cloud-function /aws/integrations/app-frameworks/spring-cloud-function/ 301 +/user-guide/integrations/spring-cloud-function /aws/customization/integrations/app-frameworks/spring-cloud-function/ 301 /references/multi-account-setups /aws/customization/advanced/multi-account-setups/ 301 /user-guide/aws/elementalmediaconvert /aws/services/mediaconvert/ 301 /references/coverage/coverage_shield /aws/services/shield/ 301 @@ -729,7 +715,7 @@ /references/coverage/coverage_appconfig /aws/services/appconfig/ 301 /references/coverage/coverage_iot /aws/services/iot/ 301 /getting-started/installation /aws/getting-started/installation/ 301 -/user-guide/integrations/architect /aws/integrations/app-frameworks/architect/ 301 +/user-guide/integrations/architect /aws/customization/integrations/app-frameworks/architect/ 301 /user-guide/integrations/gitpod /aws/customization/other-installations/ 301 /user-guide/aws/managedblockchain /aws/services/managedblockchain/ 301 /applications/query-data-in-s3-bucket-with-amazon-athena-glue-catalog-cloudformation https://github.com/localstack-samples/sample-query-data-s3-athena-glue 301 @@ -744,7 +730,7 @@ /user-guide/aws/iot /aws/services/iot/ 301 /user-guide/aws/backup /aws/services/backup/ 301 /references/coverage/coverage_organizations /aws/services/organizations/ 301 -/user-guide/aws/kinesisanalytics /aws/services/kinesisanalytics/ 301 +/user-guide/aws/kinesisanalytics /aws/services/kinesisanalyticsv2/ 301 /user-guide/localstack-enterprise/single-sign-on /aws/organizations-admin/sso/ 301 /user-guide/aws/redshift /aws/services/redshift/ 301 /references/coverage/coverage_verifiedpermissions /aws/services/verifiedpermissions/ 301 @@ -752,7 +738,7 @@ /applications/full-stack-application-with-aws-lambda-dynamodb-s3-for-shipment-validation https://github.com/localstack-samples/sample-shipment-list-demo-lambda-dynamodb-s3 301 /user-guide/integrations/chalice /aws/connecting/infrastructure-as-code/aws-chalice/ 301 /user-guide/security-testing/iam-policy-stream /aws/developer-tools/security-testing/iam-policy-stream/ 301 -/user-guide/security-testing/iam-enforcement /aws/developer-tools/security-testing/iam-enforcement/ 301 +/user-guide/security-testing/iam-enforcement /aws/developer-tools/security-testing/iam-policy-enforcement/ 301 /references/coverage/coverage_route53resolver /aws/services/route53resolver/ 301 /references/coverage/coverage_config /aws/services/config/ 301 /references/coverage/coverage_account /aws/services/account/ 301 @@ -770,7 +756,7 @@ /user-guide/aws/elasticache /aws/services/elasticache/ 301 /tutorials/using-terraform-with-testcontainers-and-localstack /aws/tutorials/using-terraform-with-testcontainers-and-localstack/ 301 /references/coverage/coverage_cloudfront /aws/services/cloudfront/ 301 -/user-guide/tools/localstack-sdk/java /aws/user-guide/tools/localstack-sdk/java/ 301 +/user-guide/tools/localstack-sdk/java /aws/customization/integrations/localstack-sdks/java-sdk/ 301 /references/network-troubleshooting/readme /aws/customization/networking/ 301 /user-guide/aws/codecommit /aws/services/codecommit/ 301 /references/coverage/coverage_swf /aws/services/swf/ 301 @@ -779,32 +765,32 @@ /references/init-hooks /aws/customization/advanced/initialization-hooks/ 301 /references/coverage/coverage_support /aws/services/support/ 301 /user-guide /aws/ 301 -/user-guide/aws/qldb /aws/services/qldb/ 301 /tutorials/simulating-outages /aws/tutorials/simulating-outages/ 301 /user-guide/aws/acm /aws/services/acm/ 301 -/user-guide/integrations/sdks/php /aws/connecting/aws-sdks/net/php/ 301 +/user-guide/integrations/sdks/php /aws/connecting/aws-sdks/php/ 301 /references/coverage/coverage_sns /aws/services/sns/ 301 -/getting-started/help-and-support /aws/getting-started/help-support/ 301 +/getting-started/help-and-support /aws/help-support/ 301 /user-guide/aws/amplify /aws/services/amplify/ 301 /references/coverage/coverage_lakeformation /aws/services/lakeformation/ 301 -/user-guide/integrations/sdks/dotnet /aws/connecting/aws-sdks/net/dotnet/ 301 +/user-guide/integrations/sdks/dotnet /aws/connecting/aws-sdks/dotnet/ 301 /academy https://www.youtube.com/playlist?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0 301 /references/coverage/coverage_cloudwatch /aws/services/cloudwatch/ 301 /user-guide/aws/ecr /aws/services/ecr/ 301 /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 /references/coverage/coverage_cognito-idp /aws/services/cognito-idp/ 301 /user-guide/web-application/workspace /aws/organizations-admin/workspaces/ 301 /references/coverage/coverage_cloudcontrol /aws/services/cloudcontrol/ 301 -/tutorials/replicate-aws-resources-localstack-extension /aws/tutorials/replicate-aws-resources-localstack-extension/ 301 +/tutorials/replicate-aws-resources-localstack-extension /aws/developer-tools/aws-replicator/ 301 /user-guide/tools/localstack-sdk/python /aws/customization/integrations/localstack-sdks/python-sdk/ 301 /user-guide/lambda-tools/hot-reloading /aws/developer-tools/lambda-tools/hot-reloading/ 301 -/getting-started/quickstart /aws/getting-started/quickstart/ 301 +/getting-started/quickstart /aws/getting-started/local-development/ 301 +/aws/getting-started/quickstart /aws/getting-started/local-development/ 301 /overview /aws/ 301 /user-guide/aws/glue /aws/services/glue/ 301 /getting-started /aws/getting-started/ 301 @@ -839,8 +825,8 @@ /aws/integrations/aws-sdks/java /aws/connecting/aws-sdks/java/ 301 /aws/integrations/aws-sdks/javascript/ /aws/connecting/aws-sdks/javascript/ 301 /aws/integrations/aws-sdks/javascript /aws/connecting/aws-sdks/javascript/ 301 -/aws/integrations/aws-sdks/net/ /aws/connecting/aws-sdks/net/ 301 -/aws/integrations/aws-sdks/net /aws/connecting/aws-sdks/net/ 301 +/aws/integrations/aws-sdks/net/ /aws/connecting/aws-sdks/ 301 +/aws/integrations/aws-sdks/net /aws/connecting/aws-sdks/ 301 /aws/integrations/aws-sdks/php/ /aws/connecting/aws-sdks/php/ 301 /aws/integrations/aws-sdks/php /aws/connecting/aws-sdks/php/ 301 /aws/integrations/aws-sdks/python-boto3/ /aws/connecting/aws-sdks/python-boto3/ 301 @@ -875,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 @@ -1008,7 +998,6 @@ /aws/capabilities/web-app/workspaces /aws/organizations-admin/workspaces/ 301 /aws/capabilities/web-app/workspaces/ /aws/organizations-admin/workspaces/ 301 -/aws/configuration/networking/* /aws/customization/networking/:splat 301 /aws/configuration/networking /aws/customization/networking/ 301 /aws/configuration/config/configuration /aws/customization/configuration-options/ 301 /aws/configuration/config/logging /aws/customization/logging/ 301 @@ -1028,9 +1017,7 @@ /aws/configuration/localsurf /aws/customization/networking/localsurf/ 301 /aws/configuration/testing-utils /aws/customization/integrations/localstack-sdks/testing-utils/ 301 /aws/configuration/localstack-docker-extension /aws/customization/other-installations/localstack-docker-extension/ 301 -/aws/configuration/localstack-sdks/* /aws/customization/integrations/localstack-sdks/:splat 301 /aws/configuration/localstack-sdks /aws/customization/integrations/localstack-sdks/ 301 -/aws/configuration/extensions/* /aws/customization/integrations/extensions/:splat 301 /aws/configuration/extensions /aws/customization/integrations/extensions/ 301 /aws/configuration/web-app/accounts /aws/organizations-admin/accounts/ 301 /aws/configuration/web-app/workspaces /aws/organizations-admin/workspaces/ 301 @@ -1087,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 @@ -1130,8 +1117,8 @@ /aws/integrations/containers/openshift/ /aws/customization/kubernetes/openshift/ 301 /aws/integrations/containers/rancher-desktop /aws/customization/other-installations/rancher-desktop/ 301 /aws/integrations/containers/rancher-desktop/ /aws/customization/other-installations/rancher-desktop/ 301 -/aws/integrations/messaging/docker-compose /aws/customization/integrations/app-frameworks/docker-compose/ 301 -/aws/integrations/messaging/docker-compose/ /aws/customization/integrations/app-frameworks/docker-compose/ 301 +/aws/integrations/messaging/docker-compose /aws/customization/other-installations/docker-images/ 301 +/aws/integrations/messaging/docker-compose/ /aws/customization/other-installations/docker-images/ 301 /aws/integrations/messaging /aws/customization/integrations/app-frameworks/ 301 /aws/integrations/messaging/ /aws/customization/integrations/app-frameworks/ 301 /aws/integrations/messaging/selfmanaged-kafka-cluster /aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster/ 301 @@ -1139,6 +1126,9 @@ /aws/integrations/continuous-integration /aws/ci-pipelines/ 301 /aws/integrations/continuous-integration/ /aws/ci-pipelines/ 301 +/aws/configuration/networking/* /aws/customization/networking/:splat 301 +/aws/configuration/localstack-sdks/* /aws/customization/integrations/localstack-sdks/:splat 301 +/aws/configuration/extensions/* /aws/customization/integrations/extensions/:splat 301 /aws/capabilities/networking/* /aws/customization/networking/:splat 301 /aws/capabilities/extensions/* /aws/customization/integrations/extensions/:splat 301 /aws/capabilities/localstack-sdks/* /aws/customization/integrations/localstack-sdks/:splat 301 diff --git a/public/images/aws/app-inspector-operations.jpg b/public/images/aws/app-inspector-operations.jpg new file mode 100644 index 000000000..d2820d1e8 Binary files /dev/null and b/public/images/aws/app-inspector-operations.jpg differ diff --git a/public/images/aws/dynamodb-resource-browser.jpg b/public/images/aws/dynamodb-resource-browser.jpg new file mode 100644 index 000000000..a52bd6a9e Binary files /dev/null and b/public/images/aws/dynamodb-resource-browser.jpg differ diff --git a/public/images/aws/export-cloud-pod-web-app.jpg b/public/images/aws/export-cloud-pod-web-app.jpg new file mode 100644 index 000000000..daaa8277c Binary files /dev/null and b/public/images/aws/export-cloud-pod-web-app.jpg differ diff --git a/public/images/aws/lambda-resource-browser.jpg b/public/images/aws/lambda-resource-browser.jpg new file mode 100644 index 000000000..58784dd07 Binary files /dev/null and b/public/images/aws/lambda-resource-browser.jpg differ diff --git a/public/images/aws/load-state-from-pod.jpg b/public/images/aws/load-state-from-pod.jpg new file mode 100644 index 000000000..4453bf53c Binary files /dev/null and b/public/images/aws/load-state-from-pod.jpg differ diff --git a/public/images/aws/localstack-resource-browser.png b/public/images/aws/localstack-resource-browser.png new file mode 100644 index 000000000..a228b2b7e Binary files /dev/null and b/public/images/aws/localstack-resource-browser.png differ 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/running-instance-sidebar.jpg b/public/images/aws/running-instance-sidebar.jpg new file mode 100644 index 000000000..852130704 Binary files /dev/null and b/public/images/aws/running-instance-sidebar.jpg 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/public/images/aws/stack-overview.jpg b/public/images/aws/stack-overview.jpg new file mode 100644 index 000000000..9ff1e52e2 Binary files /dev/null and b/public/images/aws/stack-overview.jpg differ diff --git a/public/images/aws/verify-cloud-pod-save.jpg b/public/images/aws/verify-cloud-pod-save.jpg new file mode 100644 index 000000000..053318c1e Binary files /dev/null and b/public/images/aws/verify-cloud-pod-save.jpg differ diff --git a/public/js/icon-loader.js b/public/js/icon-loader.js index e2d20a348..fdfd26fb4 100644 --- a/public/js/icon-loader.js +++ b/public/js/icon-loader.js @@ -5,6 +5,7 @@ const iconMappings = { Welcome: 'cube-icon', 'Getting Started': 'rocket-icon', + 'Quickstart Library': 'lightning-icon', 'Local AWS Services': 'cube-icon', 'Local Azure Services': 'cube-icon', Features: 'cube-icon', diff --git a/scripts/redirects/redirects_config.json b/scripts/redirects/redirects_config.json index 6f3580563..6ed8fdf08 100644 --- a/scripts/redirects/redirects_config.json +++ b/scripts/redirects/redirects_config.json @@ -1975,7 +1975,12 @@ }, { "old_link": "/getting-started/quickstart/", - "new_link": "/aws/getting-started/quickstart", + "new_link": "/aws/getting-started/local-development/", + "status_code": 301 + }, + { + "old_link": "/aws/getting-started/quickstart/", + "new_link": "/aws/getting-started/local-development/", "status_code": 301 }, { diff --git a/src/assets/images/lightning.svg b/src/assets/images/lightning.svg new file mode 100644 index 000000000..eadf570ec --- /dev/null +++ b/src/assets/images/lightning.svg @@ -0,0 +1,3 @@ + + + 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/configuration-options.md b/src/content/docs/aws/customization/configuration-options.md index 7b915a7c8..ea336a122 100644 --- a/src/content/docs/aws/customization/configuration-options.md +++ b/src/content/docs/aws/customization/configuration-options.md @@ -29,7 +29,7 @@ Options that affect the core LocalStack system. | `DEBUG` | `0` (default) \|`1`| Flag to increase log level and print more verbose logs (useful for troubleshooting issues)| | `IMAGE_NAME`| `localstack/localstack` (default), `localstack/localstack:0.11.0` | Specific name and tag of LocalStack Docker image to use.| | `LOCALSTACK_HOST`| `localhost.localstack.cloud:4566` (default) | This is interpolated into URLs and addresses that are returned by LocalStack. It has the form `:`. | -| `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 `:(,:)*`. LocalStack for AWS adds port `443`. | +| `GATEWAY_LISTEN` | `0.0.0.0:4566,0.0.0.0:443` (default in Docker mode), `127.0.0.1:4566,127.0.0.1:443` (default in host mode) | Configures the bind addresses of LocalStack. It has the form `:(,:)*`. When unset, LocalStack listens on both the HTTP edge port (`4566`) and HTTPS (`443`). | | `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](/aws/developer-tools/snapshots/persistence) and [Filesystem Layout](/aws/customization/advanced/filesystem). | | `MAIN_CONTAINER_NAME` | `localstack-main` (default) | Specify the main docker container name | @@ -397,7 +397,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 @@ -409,7 +409,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 @@ -462,7 +462,6 @@ To learn more about these configuration options, see [DNS Server](/aws/customiza | Variable | Example Values | Description | |----------------------|----------------|-------------| -| `ACTIVATE_PRO` | `0` \| `1` (default) | Whether Pro should be activated or not. This is set to true by default if using the `localstack/localstack-pro` container image. If set to `1`, LocalStack will fail to start if the license key activation did not work. If set to `0`, an attempt is made to start LocalStack without Pro features. | | `LOCALSTACK_AUTH_TOKEN` | | [Auth token](/aws/getting-started/auth-token) to activate LocalStack for AWS. | | `LOCALSTACK_API_KEY` | | **Deprecated since 3.0.0** API key to activate LocalStack for AWS.
**Use the `LOCALSTACK_AUTH_TOKEN` instead (except for [CI environments](/aws/ci-pipelines/)).** | | `LOG_LICENSE_ISSUES` | `0` \| `1` (default) | Whether to log issues with the license activation to the console. | @@ -476,6 +475,7 @@ These configurations have already been removed and **won't have any effect** on | Variable | Removed in | Example Values | Description | | - | - | - | - | +| `ACTIVATE_PRO` | 2026.7.0 | `0` \| `1` (default) | Whether Pro should be activated or not. Previously allowed starting LocalStack without Pro features when set to `0`. The flag had no remaining effect and was removed; use the community image (`localstack/localstack`) if you do not need Pro features. | | `EVENT_RULE_ENGINE` | 4.1.0 | `python` (default) \| `java` (deprecated) | Engine for [event pattern matching](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns-content-based-filtering.html) used in EventBridge, EventBridge Pipes, and Lambda Event Source Mapping. Our new `python` implementation introduced with version `4.0.3` makes the `java` engine (previously in preview) using AWS [event-ruler](https://github.com/aws/event-ruler) obsolete. | | `LAMBDA_EVENT_SOURCE_MAPPING` | 4.0.0 | `v2` (default since [3.8.0](https://blog.localstack.cloud/localstack-release-v-3-8-0/#new-default-lambda-event-source-mapping-implementation)) \| `v1` | Feature flag to switch Lambda Event Source Mapping (ESM) implementations. | | `PROVIDER_OVERRIDE_STEPFUNCTIONS` | 4.0.0 | `v2` (default) \| `legacy` | The new LocalStack-native StepFunctions provider (v2) is active by default since LocalStack 3.0. | diff --git a/src/content/docs/aws/customization/other-installations/devcontainers.mdx b/src/content/docs/aws/customization/other-installations/devcontainers.mdx index bbe67b4a2..2aba6f90b 100644 --- a/src/content/docs/aws/customization/other-installations/devcontainers.mdx +++ b/src/content/docs/aws/customization/other-installations/devcontainers.mdx @@ -157,7 +157,6 @@ The `devcontainer.json` will look similar to the following: "LOCALSTACK_AUTH_TOKEN": "${localEnv:LOCALSTACK_AUTH_TOKEN}", // required for Pro, not processed via template due to security reasons "LOCALSTACK_API_KEY": "${localEnv:LOCALSTACK_API_KEY}", // LocalStack configuration: https://docs.localstack.cloud/references/configuration/ - "ACTIVATE_PRO": false, "DEBUG": true, "LS_LOG": "debug", "PERSISTENCE": false, @@ -414,7 +413,6 @@ FROM mcr.microsoft.com/devcontainers/base:bookworm LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:-} # required for Pro, not processed via template due to security reasons LOCALSTACK_API_KEY=${LOCALSTACK_API_KEY:-} # LocalStack configuration: https://docs.localstack.cloud/references/configuration/ -ACTIVATE_PRO=false DEBUG=true LS_LOG=debug PERSISTENCE=false 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/aws-replicator/index.mdx b/src/content/docs/aws/developer-tools/aws-replicator/index.mdx index f05ff9a3a..ea880b3db 100644 --- a/src/content/docs/aws/developer-tools/aws-replicator/index.mdx +++ b/src/content/docs/aws/developer-tools/aws-replicator/index.mdx @@ -29,7 +29,7 @@ A valid `LOCALSTACK_AUTH_TOKEN` must be configured to start the LocalStack for A :::note The Replicator is in limited preview and is available from LocalStack CLI version 4.2.0. -If you encounter issues, update your [LocalStack CLI](/aws/getting-started/installation/#updating-localstack-cli). +If you encounter issues, update your [LocalStack CLI](/aws/getting-started/installation/#update-localstack-cli). ::: ### Retrieve credentials to access AWS @@ -85,7 +85,7 @@ The replication type and explore strategy are independent: `replication_type` se The Replicator CLI is part of the LocalStack CLI. -Follow the [installation instructions](/aws/getting-started/installation/#installing-localstack-cli) to set it up. +Follow the [installation instructions](/aws/getting-started/installation/#install-localstack-cli) to set it up. To start a replication job, get the ARN of the resource to replicate. Then, trigger the job using the command: diff --git a/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md b/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md index 1c00d0113..0dcfaf16e 100644 --- a/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md +++ b/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md @@ -87,7 +87,7 @@ If you have created a Cloud Pod from an older version of LocalStack, you need to ## Ephemeral Instances CLI -The Ephemeral Instances CLI is included in the [LocalStack CLI installation](/aws/getting-started/installation/#installing-localstack-cli), so no additional installations are needed to start using it. +The Ephemeral Instances CLI is included in the [LocalStack CLI installation](/aws/getting-started/installation/#install-localstack-cli), so no additional installations are needed to start using it. If you're a licensed user, setting the `LOCALSTACK_AUTH_TOKEN` as an environment variable is recommended to access all features of the Ephemeral Instances CLI. Access the Ephemeral Instances CLI by running the `localstack ephemeral` command from your terminal. diff --git a/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md b/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md index 184fac030..732606560 100644 --- a/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md +++ b/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md @@ -3,18 +3,254 @@ title: LocalStack CLI description: Reference guide for LocalStack CLI commands, options, and usage. template: doc sidebar: - order: 10 -tags: ["Hobby"] + order: 10 +tags: ['Hobby'] --- +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import { LinkButton, Code } from '@astrojs/starlight/components'; +import { LOCALSTACK_AWS_VERSION } from 'astro:env/server'; + ## Introduction The LocalStack Command Line Interface (CLI) is a tool for starting, managing, and configuring your LocalStack container. It provides convenience features to interact with LocalStack features like Cloud Pods, Extensions, State Management, and more. -To install the LocalStack CLI, follow the [installation guide](/aws/getting-started/installation/#installing-localstack-cli). +:::caution +The LocalStack CLI is deprecated and will be removed in a future version. +Please use [lstk](/aws/developer-tools/running-localstack/lstk/) instead. +::: + +## Installation + + + + + +You can download the pre-built binary for your architecture using the link below: + + + {' '} + x86-64 + + + ARM64 + + +or use the curl commands below: + +For x86-64: + + + +For ARM64: + + + +Then extract the LocalStack CLI from the terminal: + + + +
+Alternative: Homebrew on Linux + +If you are using [Homebrew for Linux](https://docs.brew.sh/Homebrew-on-Linux), you can install the LocalStack CLI directly from our official LocalStack tap: + +```bash +brew install localstack/tap/localstack-cli +``` + +
+ + + + + +You can install the LocalStack CLI using Brew directly from our official LocalStack tap: + +```bash +brew install localstack/tap/localstack-cli +``` + +
+Alternative: Binary Download + +You may download the binary for your architecture using the link below: + + + {' '} + Intel (AMD64) + + +or use the following curl command: + + + +Then extract the LocalStack CLI from the terminal: + + + +
+ + + + +You can download the pre-built binary for your architecture using the link below: + + + {' '} + Intel (AMD64) + + +Then extract the archive and execute the binary in Powershell. + + + + + +If you cannot use the binary releases of LocalStack, you can install the Python distribution. + +Please make sure to install the following before moving ahead: + +- [Python](https://docs.python.org/3/using/index.html) +- [pip](https://pip.pypa.io/en/stable/installation/) + +Next install the LocalStack CLI in your Python environment by running: + +```bash +python3 -m pip install --upgrade localstack +``` + +:::note +To download a specific version of LocalStack, replace `` with the required version from [changelog page](/aws/changelog). + +```bash +python3 -m pip install localstack== +``` + +::: + +:::tip[MacOS Sierra?] +If you have problems with permissions in MacOS X Sierra, install with: + +```bash +python3 -m pip install --user localstack +``` + +::: + +:::danger +Do not use `sudo` or the `root` user when starting LocalStack. +It should be installed and started entirely under a local non-root user. +::: + + + + +### Starting LocalStack + +To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal: + + + +You are all set! + +:::note +To start LocalStack, you must first [set up your auth token](/aws/getting-started/auth-token). +::: + +Once you've set up your auth token, you can start LocalStack with the following command: + +```bash +localstack start # start localstack in background with -d flag +``` + +{/_ prettier-ignore _/} + + + +### Updating LocalStack CLI + +The LocalStack CLI allows you to easily update the different components of LocalStack. +To check the various options available for updating, run: + +```bash +localstack update --help +``` + +```bash +Usage: localstack update [OPTIONS] COMMAND [ARGS]... + + Update different LocalStack components. + +Options: + -h, --help Show this message and exit. + +Commands: + all Update all LocalStack components + docker-images Update docker images LocalStack depends on + localstack-cli Update LocalStack CLI +``` :::note +Updating the LocalStack CLI using `localstack update localstack-cli` and `localstack update all` will work only if it was installed from the Python distribution. +If it was installed using the pre-built binary or via Brew, please run the installation steps again to update to the latest version. +::: + +:::note +This documentation below was auto-generated from LocalStack CLI version `LocalStack CLI 2026.4.0`. + [`lstk`](/aws/developer-tools/running-localstack/lstk/) is our new Go-based CLI with an interactive terminal UI for lifecycle (`start`, `stop`), monitoring (`status`, `logs`), storage (`snapshot`), and more. ::: @@ -22,12 +258,12 @@ To install the LocalStack CLI, follow the [installation guide](/aws/getting-star The following global options are available for the `localstack` CLI: -| Option | Description | -|--------|-------------| -| `-v`, `--version` | Show the version and exit | -| `-d`, `--debug` | Enable CLI debugging mode | +| Option | Description | +| ---------------------- | ----------------------------- | +| `-v`, `--version` | Show the version and exit | +| `-d`, `--debug` | Enable CLI debugging mode | | `-p`, `--profile TEXT` | Set the configuration profile | -| `-h`, `--help` | Show help message and exit | +| `-h`, `--help` | Show help message and exit | ## Commands @@ -791,8 +1027,6 @@ Commands: #### `license activate` - - ```bash Usage: localstack license activate [OPTIONS] @@ -802,8 +1036,6 @@ Options: #### `license info` - - ```bash Usage: localstack license info [OPTIONS] diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk.mdx b/src/content/docs/aws/developer-tools/running-localstack/lstk.mdx index 1287d737c..9eef67b13 100644 --- a/src/content/docs/aws/developer-tools/running-localstack/lstk.mdx +++ b/src/content/docs/aws/developer-tools/running-localstack/lstk.mdx @@ -15,12 +15,10 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; It provides a built-in terminal UI (TUI) for interactive use and plain text output for CI/CD pipelines and scripting. `lstk` handles the full emulator lifecycle: authentication, pulling the Docker image, starting, stopping, and restarting the container, streaming logs, and checking status. -It can also save and load emulator state — as local snapshots or Cloud Pods — reset running state, run AWS CLI commands against the emulator, and manage the on-disk volume. +It can also save and load emulator state (as local snapshots or Cloud Pods) reset running state, run AWS CLI commands against the emulator, and manage the on-disk volume. Running `lstk` with no arguments takes you through the entire startup flow automatically. -:::note -`lstk` supports core lifecycle commands (`start`, `stop`, `restart`, `logs`, `status`) along with state management via snapshots (`snapshot save`/`snapshot load`, `reset`) and an AWS CLI proxy (`lstk aws`). -::: +`lstk` also proxies developer tools so they run directly against LocalStack: the AWS CLI (`lstk aws`), the Azure CLI (`lstk az`), Terraform (`lstk terraform`), the AWS CDK (`lstk cdk`), and the AWS SAM CLI (`lstk sam`). ## Prerequisites @@ -172,22 +170,28 @@ The default `config.toml` created on first run: ```toml [[containers]] -type = "aws" # Emulator type. Supported: "aws", "snowflake", "azure" -tag = "latest" # Docker image tag, e.g. "latest", "2026.4" -port = "4566" # Host port the emulator will be accessible on -# volume = "" # Host directory for persistent state (default: OS cache dir) -# env = [] # Named environment profiles to apply (see [env.*] sections below) +type = "aws" # Emulator type. Supported: "aws", "snowflake", "azure" +tag = "latest" # Docker image tag, e.g. "latest", "2026.4" +port = "4566" # Host port the emulator will be accessible on +# image = "" # Full image override (e.g. an internal mirror or offline image) +# volume = "" # Host directory for persistent state (default: OS cache dir) +# volumes = [] # Docker-style "host:container[:ro]" bind mounts (see Volumes) +# env = [] # Named environment profiles to apply (see [env.*] sections below) +# snapshot = "" # Snapshot REF to auto-load after start (AWS only) ``` ### Config field reference -| Field | Type | Default | Description | -|:---------|:---------|:-----------|:-----------------------------------------------------------------------------------------------------| -| `type` | string | `"aws"` | Emulator type. One of `"aws"`, `"snowflake"`, `"azure"`. Run a single `[[containers]]` block at a time. See [Emulator types](#emulator-types). | -| `tag` | string | `"latest"` | Docker image tag (`"latest"`, `"2026.4"`, etc.). Useful for pinning a specific version. Zero-padded months (`"2026.04"`) are normalized to `"2026.4"`. | -| `port` | string | `"4566"` | Host port the emulator listens on (1–65535). The in-container port is always `4566`. | -| `volume` | string | (OS cache) | Host directory for persistent emulator state. Defaults to `/lstk/volume/`. | -| `env` | string[] | `[]` | List of named environment profiles to inject into the container (see below). | +| Field | Type | Default | Description | +|:-----------|:---------|:-----------|:-----------------------------------------------------------------------------------------------------| +| `type` | string | `"aws"` | Emulator type. One of `"aws"`, `"snowflake"`, `"azure"`. Run a single `[[containers]]` block at a time. See [Emulator types](#emulator-types). | +| `tag` | string | `"latest"` | Docker image tag (`"latest"`, `"2026.4"`, etc.). Useful for pinning a specific version. Zero-padded months (`"2026.04"`) are normalized to `"2026.4"`. | +| `port` | string | `"4566"` | Host port the emulator listens on (1–65535). The in-container port is always `4566`. | +| `image` | string | (default) | Full image reference that overrides the default Docker Hub image, e.g. an internal-registry mirror or a locally loaded offline image. If it already carries a tag, `tag` is ignored; otherwise `tag` (or `latest`) is appended. | +| `volume` | string | (OS cache) | Host directory for persistent emulator state. Defaults to `/lstk/volume/`. See also `volumes`. | +| `volumes` | string[] | `[]` | Docker-style `"host:container[:ro]"` bind mounts (e.g. init hooks). May also carry the persistence mount (target `/var/lib/localstack`). See [Volume mounts](#volume-mounts). | +| `env` | string[] | `[]` | List of named environment profiles to inject into the container (see below). | +| `snapshot` | string | `""` | Snapshot REF (e.g. `pod:my-baseline` or a local path) to auto-load after the emulator starts. AWS emulator only. See [Auto-loading a snapshot on start](#auto-loading-a-snapshot-on-start). | :::note There is no `update_prompt` config key. @@ -208,10 +212,10 @@ The `type` field in your `config.toml` selects which one: | `azure` | `localstack/localstack-azure` | LocalStack Azure emulator. | On the first interactive run, `lstk` prompts you to pick an emulator (`a` for AWS, `s` for Snowflake, `z` for Azure) and writes your choice to `config.toml`. -In non-interactive mode the default `aws` emulator is used. +In non-interactive mode the default `aws` emulator is used if no config file is found. Lifecycle commands operate on the emulators defined in your `config.toml`. -Run a single `[[containers]]` block at a time; the AWS-specific commands (`status` resources, `aws`, `snapshot`, `reset`, `setup aws`) require an `aws` emulator to be configured. +Run a single `[[containers]]` block at a time; the AWS-specific commands (`status` resources, `aws`, `reset`, `setup aws`) require an `aws` emulator to be configured. :::note The AWS emulator's license is validated by `lstk` before the container starts. @@ -250,6 +254,42 @@ If you reference an `env` profile name that doesn't exist in your config, `lstk` In addition to your custom profiles, `lstk` always injects several variables into the container. See [Container-injected variables](#container-injected-variables) for the full list. +### Custom container image + +By default the emulator image is pulled from Docker Hub (`localstack/localstack-pro`, `localstack/snowflake`, or `localstack/localstack-azure` depending on `type`). +Set `image` on a container block to override it — for example, to pull from an internal-registry mirror or to run a locally loaded image in an air-gapped environment: + +```toml +[[containers]] +type = "aws" +image = "registry.internal.example.com/localstack/localstack-pro" +tag = "2026.4" +``` + +If `image` already carries a tag (e.g. `...:2026.4`), the separate `tag` field is ignored; otherwise `tag` (or `latest`) is appended. +See [Offline and enterprise environments](#offline-and-enterprise-environments) for how `lstk` falls back to a locally present image when a pull fails. + +### Volume mounts + +Beyond the single persistence directory set by `volume`, a container block can declare arbitrary Docker-style bind mounts with `volumes`. +Each entry is a `"host:container[:ro]"` spec — useful, for example, for mounting Snowflake init hooks into `/etc/localstack/init/{boot,start,ready,shutdown}.d`: + +```toml +[[containers]] +type = "snowflake" +port = "4566" +volumes = [ + "./init:/etc/localstack/init/ready.d:ro", + "./data:/var/lib/localstack", +] +``` + +- A `volumes` entry whose container target is `/var/lib/localstack` sets the persistence directory (the same mount `volume` configures); this is what [`lstk volume path`](#volume) and [`lstk volume clear`](#volume) resolve. +- Relative host sources and a leading `~/` are resolved against the config file's directory. This differs from the legacy `volume` field, whose value is passed to Docker verbatim. +- Setting the persistence directory through both `volume` and a `volumes` entry with a different source is a validation error. + +`volume` and `volumes` overlap only for the persistence mount: `volume` can *only* set the persistence directory, while `volumes` is a superset that can also express init hooks and other mounts. + ### Using a project-local config Place a `.lstk/config.toml` in your project directory. @@ -300,8 +340,12 @@ lstk start --non-interactive | Option | Description | |:--------------------|:-----------------------------------------------------------------------------| | `--persist` | Persist emulator state across restarts (sets `LOCALSTACK_PERSISTENCE=1` in the container) | +| `--snapshot ` | Auto-load this snapshot after the emulator starts, overriding the configured `snapshot` for one run (AWS only) | +| `--no-snapshot` | Skip auto-loading the configured `snapshot` for this run | | `--non-interactive` | Disable the interactive TUI and use plain output | +`lstk start` forwards host environment variables prefixed with `LOCALSTACK_` to the emulator (the host `LOCALSTACK_AUTH_TOKEN` is dropped so it cannot override the token `lstk` resolved). See [Container-injected variables](#container-injected-variables). + By default the emulator starts with a fresh state on every run. Pass `--persist` to keep data across restarts: `lstk` injects `LOCALSTACK_PERSISTENCE=1` into the container so state is written to the mounted [`volume`](#config-field-reference) and reloaded on the next start. When persistence is active, the AWS emulator's startup summary includes a `• Persistence: Enabled` line. @@ -316,6 +360,31 @@ lstk start --persist For finer-grained control, you can also set `PERSISTENCE = "1"` in an environment profile (see [Passing environment variables to the container](#passing-environment-variables-to-the-container)). ::: +#### Auto-loading a snapshot on start + +For the **AWS emulator**, you can have `lstk` load a snapshot automatically every time it starts the emulator. +Set the `snapshot` field on the container block to any load REF (a `pod:` Cloud Pod or a local path): + +```toml +[[containers]] +type = "aws" +port = "4566" +snapshot = "pod:my-baseline" +``` + +The snapshot is loaded only when the emulator is **freshly started** this run; if it is already running, the auto-load is skipped. +Override it for a single run with `--snapshot REF`, or skip it entirely with `--no-snapshot`: + +```bash +# Start and load a different snapshot for this run only +lstk start --snapshot pod:other-baseline + +# Start without loading the configured snapshot +lstk start --no-snapshot +``` + +The `snapshot` field is only read on start; [`snapshot save`](#snapshot-save) never writes it back into your config. + ### `stop` Stop the running LocalStack emulator. @@ -470,15 +539,113 @@ By default, `lstk` probes whether `localhost.localstack.cloud` resolves to `127. Set [`LOCALSTACK_HOST`](#environment-variables) to override the host:port used to reach LocalStack and skip the DNS probe. The port comes from the AWS container's `port` in `config.toml` (default `4566`). +### `az` + +Run Azure CLI commands against the running LocalStack Azure emulator. +`lstk az` runs `az` with an isolated `AZURE_CONFIG_DIR` in which a custom Azure cloud is registered against LocalStack's endpoints, so your global `~/.azure` configuration is left untouched and plain `az` keeps talking to real Azure. + +Run [`lstk setup azure`](#setup-azure) once before using this mode. +Everything after `lstk az` is forwarded verbatim to the host `az` binary, and its exit code and output are passed through unchanged. + +```bash +lstk az group list +lstk az storage account list +``` + +The Azure CLI has no `--endpoint-url`/`--profile` equivalent, so the isolation relies entirely on the dedicated config directory prepared by `setup azure`. + +#### Global interception (optional) + +If a script must invoke plain `az` (not `lstk az`), you can redirect your **global** `~/.azure` to LocalStack instead: + +```bash +# Point global 'az' at the LocalStack Azure emulator +lstk az start-interception + +# Switch back to real Azure +lstk az stop-interception +``` + +`start-interception` registers and activates the `LocalStack` cloud in your global Azure configuration so every `az` invocation targets LocalStack until you stop it. +`stop-interception` switches the active cloud back to `AzureCloud` (override with `--cloud `) and re-enables instance discovery, but only when `LocalStack` is still the active cloud, to avoid clobbering an unrelated selection. + +:::caution +Interception changes global state that affects every `az` command in any terminal. +Use the isolated `lstk az ` mode unless you specifically need plain `az` to target LocalStack. +::: + +### `terraform` + +Run Terraform against LocalStack, using LocalStack endpoints as AWS provider overrides. +`lstk terraform` (alias `lstk tf`) generates a provider-override file and forwards your arguments to the real `terraform` binary. + +:::note +`lstk terraform` currently targets the AWS emulator only. +To use Terraform with the other emulators, see the relevant emulator docs. +::: + +```bash +lstk terraform init +lstk terraform --region us-west-2 plan +lstk tf apply +``` + +lstk-specific flags must appear **before** the Terraform action: + +| Option | Default | Description | +|:------------------|:---------------------|:---------------------------------------| +| `--region ` | `us-east-1` | Deployment region. | +| `--account ` | `test` | Target AWS account id (12 digits). | + +Relevant environment variables: `AWS_ENDPOINT_URL` (override the auto-resolved endpoint), `LSTK_TF_CMD` (binary to invoke, e.g. `tofu`; default `terraform`), `LSTK_TF_OVERRIDE_FILE_NAME` (override file name; default `localstack_providers_override.tf`), `LSTK_TF_DRY_RUN` (generate the override file but do not run Terraform), `AWS_REGION` (fallback for `--region`), and `AWS_ACCESS_KEY_ID` (fallback for `--account`). + +### `cdk` + +Run the AWS CDK against LocalStack. +Requires the AWS CDK CLI version `2.177.0` or newer on your `PATH`. + +```bash +lstk cdk bootstrap +lstk cdk --region us-west-2 deploy +lstk cdk synth +``` + +The only lstk-specific flag (before the CDK action) is `--region ` (default `us-east-1`); CDK always targets the default LocalStack account `000000000000`, so there is no `--account` flag. +Relevant environment variables: `AWS_ENDPOINT_URL`, `AWS_ENDPOINT_URL_S3`, `LSTK_CDK_CMD` (default `cdk`), and `AWS_REGION`. + +### `sam` + +Run the AWS SAM CLI against LocalStack. +Requires the AWS SAM CLI version `1.95.0` or newer on your `PATH` (older versions ignore `AWS_ENDPOINT_URL` and would target real AWS). + +```bash +lstk sam build +lstk sam --region us-west-2 deploy +lstk sam validate +``` + +lstk-specific flags (before the SAM action): `--region ` (default `us-east-1`) and `--account ` (12 digits, default `000000000000`). +Relevant environment variables: `AWS_ENDPOINT_URL`, `AWS_ENDPOINT_URL_S3`, `LSTK_SAM_CMD` (default `sam`), `AWS_REGION` (fallback for `--region`), and `AWS_ACCESS_KEY_ID` (fallback for `--account`). + +:::note +Compared with `samlocal`, image/container-based Lambda (ECR) deploys and nested CloudFormation stacks are not supported; use `samlocal` for those workflows. +::: + +:::note +Like `lstk aws`, the `az`, `terraform`, `cdk`, and `sam` proxies do not start the emulator — start it first with `lstk start`. +Each requires the corresponding third-party CLI to be installed and on your `PATH`. +::: + ### `snapshot` Manage emulator snapshots. -A snapshot captures the running AWS emulator's state, either as a local file on disk or as a Cloud Pod on the LocalStack platform. -The `snapshot` command groups four subcommands — `save`, `load`, `list`, and `remove`. The first two are also exposed as the top-level aliases `lstk save` and `lstk load`. +A snapshot captures the running emulator's state, either as a local file on disk, as a Cloud Pod on the LocalStack platform, or in your own S3 bucket. +The `snapshot` command groups five subcommands — `save`, `load`, `list`, `remove`, and `show`. The first two are also exposed as the top-level aliases `lstk save` and `lstk load`. :::note -`snapshot`, `save`, `load`, and [`reset`](#reset) operate on the **AWS emulator** only. -If no AWS emulator is configured or running, they error out (`snapshot is only supported for the AWS emulator`). +Snapshots are best supported on the **AWS emulator**. +`snapshot save`/`load` (and the `save`/`load` aliases) also work for the Snowflake and Azure emulators, but their snapshot support is experimental and not fully tested — `lstk` prints a warning such as `Snapshot support for the snowflake emulator is experimental and not fully tested.` +[`reset`](#reset) remains **AWS-only** and errors out with `reset is only supported for the AWS emulator` otherwise. ::: #### `snapshot save` @@ -495,18 +662,26 @@ lstk snapshot save ./my-snapshot # Save to a Cloud Pod on the LocalStack platform (requires auth) lstk snapshot save pod:my-baseline + +# Save to your own S3 bucket (pod name is auto-generated if omitted) +lstk snapshot save my-pod s3://my-bucket/prefix ``` -The optional `[destination]` argument takes one of three forms: +The optional `[destination]` argument takes one of these forms: -| Destination | Description | -|:-------------------|:------------------------------------------------------------------------------------------------| -| (omitted) | Auto-generates a timestamped snapshot file in the current directory. | -| local path | Writes a snapshot archive to that path. | -| `pod:` | Saves a Cloud Pod to the LocalStack platform. Requires authentication. | +| Destination | Description | +|:--------------------------------|:------------------------------------------------------------------------------------------------| +| (omitted) | Auto-generates a timestamped snapshot file in the current directory (`./snapshot--.snapshot`). | +| local path | Writes a snapshot archive to that path. The `.snapshot` extension is forced. | +| `pod:` | Saves a Cloud Pod to the LocalStack platform. Requires authentication. | +| ` s3://bucket/prefix` | Saves to your own S3 bucket. The pod name is a separate positional (auto-generated when omitted). See [S3 remotes](#s3-remotes). | Pod operations require an auth token (`LOCALSTACK_AUTH_TOKEN` or a prior `lstk login`); local-file snapshots do not. +| Option | Description | +|:--------------------|:----------------------------------------------------------------------------------------------| +| `--profile ` | AWS profile to read S3 credentials from (used only for `s3://` destinations). Defaults to `AWS_*` env vars, then `AWS_PROFILE`. | + #### `snapshot load` Load a snapshot into the emulator, **auto-starting it first** if it is not already running. @@ -519,15 +694,20 @@ lstk snapshot load ./checkpoint # Load from a Cloud Pod (requires auth) lstk snapshot load pod:my-baseline +# Load from your own S3 bucket (pod name is required) +lstk snapshot load my-pod s3://my-bucket/prefix + # Control how the snapshot merges with running state lstk snapshot load pod:my-baseline --merge=overwrite ``` The `REF` argument is required and identifies a local path/name or a `pod:` Cloud Pod. +To load from S3, pass the pod name followed by an `s3://bucket/prefix` location (see [S3 remotes](#s3-remotes)). | Option | Description | |:---------------------|:--------------------------------------------------------------------------------------------------------| | `--merge ` | How the loaded state combines with running state. One of `account-region-merge` (default), `overwrite`, `service-merge`. | +| `--profile ` | AWS profile to read S3 credentials from (used only for `s3://` sources). Defaults to `AWS_*` env vars, then `AWS_PROFILE`. | - `account-region-merge` (default): the snapshot wins on any `(service, account, region)` overlap. - `overwrite`: running state is reset first, then the snapshot is imported onto a clean state. @@ -552,11 +732,17 @@ lstk snapshot list # Every snapshot in your organization lstk snapshot list --all + +# List snapshots in your own S3 bucket (requires a running emulator) +lstk snapshot list s3://my-bucket/prefix ``` -| Option | Description | -|:--------|:------------------------------------------------------------| -| `--all` | List all snapshots in your organization, not just your own. | +Passing an `s3://bucket/prefix` location lists snapshots stored in your own S3 bucket instead of the platform (see [S3 remotes](#s3-remotes)). Unlike the platform listing, this queries the emulator, so it requires a running emulator. + +| Option | Description | +|:-------------------|:-------------------------------------------------------------| +| `--all` | List all snapshots in your organization, not just your own. | +| `--profile ` | AWS profile to read S3 credentials from (used only with an `s3://` location). Defaults to `AWS_*` env vars, then `AWS_PROFILE`. | #### `snapshot remove` @@ -577,6 +763,38 @@ The required `REF` argument must be a `pod:` Cloud Pod reference. |:----------|:----------------------------------------------------------------------| | `--force` | Skip the confirmation prompt. Required when running non-interactively. | +#### `snapshot show` + +Show metadata for a single Cloud Pod snapshot on the LocalStack platform: its name, created date, size, LocalStack version, message, the services it contains, and per-service resource counts (resource counts render only when the platform has them for that snapshot). +This subcommand is cloud-only and requires authentication. + +```bash +lstk snapshot show pod:my-baseline +``` + +The required `REF` argument must be a `pod:` Cloud Pod reference. + +#### S3 remotes + +`snapshot save`, `load`, and `list` can target a snapshot stored in your **own S3 bucket** by passing an `s3://bucket/prefix` location. +The pod name (the snapshot's identity within the bucket) is a positional separate from the `s3://` location — required for `load`, auto-generated for `save` when omitted, and unused for `list`. + +```bash +lstk snapshot save my-pod s3://my-bucket/prefix +lstk snapshot load my-pod s3://my-bucket/prefix +lstk snapshot list s3://my-bucket/prefix +``` + +Credentials follow AWS CLI precedence: `--profile ` wins, otherwise the static `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` (plus optional `AWS_SESSION_TOKEN`) environment variables, otherwise the profile named by `AWS_PROFILE`. +Only static credentials are supported (no SSO, assume-role, or `credential_process`), and credentials must never be embedded in the URL. + +`lstk` runs a pre-flight check that the target bucket exists and errors out rather than letting the emulator auto-create a bucket on a typo. +Because the transfer is performed by the emulator (not the CLI), S3 remotes require a **running emulator**, and `list s3://…` in particular queries the emulator rather than the platform API. + +:::note +`remove` and `show` do not support S3; they operate on Cloud Pods only. +::: + ### `reset` Discard the running AWS emulator's in-memory state (all created resources such as S3 buckets and Lambda functions are dropped). @@ -731,22 +949,30 @@ If a LocalStack emulator is still running after logout, `lstk` prints a note rem ### `setup` Set up CLI integration for an emulator type. -`lstk setup` is a grouping command with no action of its own; the work is done by its subcommand. -Currently only AWS is supported. +`lstk setup` is a grouping command with no action of its own; the work is done by its subcommands, `setup aws` and `setup azure`. ```bash lstk setup aws +lstk setup azure ``` #### `setup aws` Create or update a `localstack` profile in `~/.aws/config` and `~/.aws/credentials` so the AWS CLI and SDKs can target LocalStack. -This command requires an interactive terminal and prompts before making any changes. ```bash lstk setup aws +lstk setup aws --force ``` +| Option | Description | +|:----------|:-----------------------------------------------------------------------------------------| +| `--force` | Overwrite an existing `localstack` profile whose values differ, and skip the confirmation prompt. | + +On an interactive terminal it prompts (Y/n) before making changes. +In non-interactive mode (piped output, CI, or `--non-interactive`) it writes the profile with defaults without prompting and exits `0`; a failed write or check returns a non-zero exit code so automation notices. +Overwriting an existing `localstack` profile whose values differ requires `--force` (which also skips the interactive prompt); creating a fresh profile, completing a partial one, or leaving an already-correct profile in place never needs it. + It writes the following profile (existing unrelated profiles are preserved): ```ini @@ -776,15 +1002,24 @@ The port comes from your AWS emulator's configured `port` (default `4566`); if n If the `localstack` profile is already configured correctly, `lstk` reports `LocalStack AWS profile is already configured.` and makes no changes. :::note -`setup aws` requires an interactive terminal. -In non-interactive mode (piped output, CI, or `--non-interactive`) it fails with `setup aws requires an interactive terminal`. -There is no flag to auto-confirm. +The former `lstk config profile` command has been removed; use `lstk setup aws`. ::: -:::caution -`lstk config profile` is the deprecated form of this command. -It still works and behaves identically, but you should use `lstk setup aws` instead. -::: +#### `setup azure` + +Prepare an isolated Azure CLI configuration directory that routes [`lstk az`](#az) commands to the LocalStack Azure emulator. +Your global `~/.azure` configuration is left untouched. + +```bash +lstk setup azure +# alias: +lstk setup az +``` + +`setup azure` registers a custom Azure cloud (`LocalStack`) whose endpoints point at the LocalStack Azure emulator, activates it, disables Azure CLI instance discovery and telemetry, and performs a one-time dummy service-principal login — all inside a dedicated config directory under the `lstk` config dir (via `AZURE_CONFIG_DIR`). +It requires the `az` CLI to be installed and a running LocalStack Azure emulator. + +To instead redirect your **global** `az` (so existing scripts run unmodified against LocalStack), see [`lstk az start-interception`](#az). ### `config` @@ -803,26 +1038,6 @@ This subcommand is read-only: it never creates or initializes a config file. If `--config ` is set, it prints that path verbatim. Otherwise it prints the already-loaded config path, the first existing config in the search order, or the path where a config would be created on first run. -#### `config profile` - -:::caution[Deprecated] -`config profile` is deprecated. Use [`setup aws`](#setup) instead. -::: - -Write a LocalStack AWS CLI profile into `~/.aws/config` and `~/.aws/credentials`, pointing at your configured emulator. - -```bash -lstk config profile # prefer: lstk setup aws -``` - -Requires an interactive terminal. In non-interactive mode it fails with: - -```text -config profile requires an interactive terminal -``` - -The generated profile uses the host from the `LOCALSTACK_HOST` environment variable (when set) and your configured containers, identical to [`setup aws`](#setup). - ### `update` Check for and apply updates to the `lstk` CLI itself. @@ -911,7 +1126,10 @@ These options are available for all commands: |:--------------------|:---------------------------------------------------------------------------| | `--config ` | Path to a specific TOML config file | | `--non-interactive` | Disable the interactive TUI, use plain output | +| `--json` | Output in JSON format (only supported by some commands, e.g. the tool proxies) | | `--persist` | Persist emulator state across restarts (on `start`/bare `lstk` and `restart`) | +| `--snapshot ` | Snapshot REF to auto-load after start (on `start`/bare `lstk`; overrides config for one run) | +| `--no-snapshot` | Skip auto-loading the configured snapshot (on `start`/bare `lstk`) | | `-v`, `--version` | Print the version and exit | | `-h`, `--help` | Print help and exit | @@ -930,9 +1148,9 @@ lstk --non-interactive start ``` :::note -`lstk login` and `lstk setup aws` require an interactive terminal. -If you need to authenticate in CI, set `LOCALSTACK_AUTH_TOKEN` instead. +`lstk login` requires an interactive terminal; if you need to authenticate in CI, set `LOCALSTACK_AUTH_TOKEN` instead. Commands that mutate state without prompting in CI (`reset`, `volume clear`) require `--force`. +`lstk setup aws` works non-interactively — it writes the profile with defaults and needs `--force` only to overwrite a conflicting `localstack` profile. ::: ## Environment variables @@ -959,19 +1177,26 @@ When `LSTK_OTEL` is enabled, the standard `OTEL_EXPORTER_OTLP_*` environment var `lstk` injects several environment variables into the LocalStack container on every start, in addition to any profiles you configure: -| Variable | Default value | Description | -|:------------------------|:---------------------------------------------|:---------------------------------------------| -| `LOCALSTACK_AUTH_TOKEN` | (your resolved token) | Passed from the CLI to activate the license. | -| `GATEWAY_LISTEN` | `:4566,:443` | Ports the emulator binds inside the container. | -| `MAIN_CONTAINER_NAME` | `localstack-aws` | Container name for internal references. | -| `LOCALSTACK_HOST` | `localhost.localstack.cloud:` | Hostname/port the emulator advertises. | -| `LOCALSTACK_PERSISTENCE`| `1` (only with `--persist`) | Enables state persistence across restarts. | +| Variable | Default value | Description | +|:---------------------------|:---------------------------------------------|:---------------------------------------------| +| `LOCALSTACK_AUTH_TOKEN` | (your resolved token) | Passed from the CLI to activate the license. | +| `GATEWAY_LISTEN` | `:4566,:443` | Ports the emulator binds inside the container. | +| `MAIN_CONTAINER_NAME` | `localstack-aws` | Container name for internal references. | +| `LOCALSTACK_HOST` | `localhost.localstack.cloud:` | Hostname/port the emulator advertises. | +| `LOCALSTACK_PERSISTENCE` | `1` (only with `--persist`) | Enables state persistence across restarts. | +| `LOCALSTACK_CLIENT_NAME` | `lstk` | Identifies the client that started the emulator. | +| `LOCALSTACK_CLIENT_VERSION`| (the `lstk` version) | Version of the client that started the emulator. | When a Docker socket is detected it is bind-mounted into the container and `DOCKER_HOST=unix:///var/run/docker.sock` is injected so the emulator can spawn its own containers. `lstk` also forwards host environment variables matching `CI` and `LOCALSTACK_*` (the host `LOCALSTACK_AUTH_TOKEN` is dropped so it cannot override the token resolved by `lstk`). The container also gets port mappings for `4566`, `443`, and the service port range `4510-4559`. +:::note +`GATEWAY_LISTEN` is read from the container's resolved environment (set it via an `[env.*]` profile), not hardcoded. +Beyond controlling which ports the emulator binds, its host part sets the host publish IP for all published ports: a value like `GATEWAY_LISTEN = "0.0.0.0:4566,0.0.0.0:443"` exposes the emulator beyond loopback (e.g. on a remote host), whereas the default binds to `127.0.0.1` only. +::: + ## OpenTelemetry tracing `lstk` can export traces of its own command execution over OTLP/HTTP. @@ -995,6 +1220,16 @@ This is separate from the LocalStack container logs (which you view with `lstk l - When the file exceeds **1 MB**, it is cleared on the next run. - Use `lstk config path` to find the config directory; `lstk.log` sits alongside `config.toml`. +## Offline and enterprise environments + +There is no `--offline` flag. Instead, `lstk` degrades gracefully when common enterprise blockers (Docker Hub unreachable, a proxy/TLS interceptor, or an unreachable license server) prevent an internet request: + +- **Image pull**: if the image pull fails but the image is already present locally, `lstk` warns and uses the local image instead of failing. In interactive mode you can also press Esc to abort an in-progress pull and fall back to the local image. +- **License pre-flight**: when the pinned image is already present locally, `lstk` skips its pre-flight license check so a fully offline start is not blocked; the container validates its own bundled license at startup. When a check does run, a definitive server rejection (e.g. HTTP 403/400) is still fatal, but a transport-level failure (offline, proxy, or certificate error) is treated as non-fatal and the container validates its own license instead. +- **Telemetry and update checks** are best-effort and fail silently when offline. + +Pair this behavior with a custom [`image`](#custom-container-image) that points at an internal-registry mirror or a locally loaded image to run `lstk` in an air-gapped environment. + ## Shell completions `lstk` includes completion scripts for bash, zsh, fish, and powershell. diff --git a/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx b/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx index 87feb6797..32b6d479a 100644 --- a/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx +++ b/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx @@ -33,7 +33,15 @@ You must include it in the `env` block of your configuration. You can get your Auth Token from the [LocalStack Web App](https://app.localstack.cloud). ::: -Choose your MCP client below for setup instructions. +The quickest way to get started with the MCP server is to use the interactive setup wizard: + +```bash +npx -y @localstack/localstack-mcp-server init +``` + +The wizard detects your installed clients, asks how you want to run the server, and writes the configuration for you. You need a valid [Auth Token](/aws/getting-started/auth-token/) to configure the server. + +For manual setup of the MCP server, choose your MCP client below for setup instructions. @@ -171,10 +179,10 @@ Refer to your client's documentation for the exact location of its MCP configura By default the MCP server connects to `http://localhost:4566`. If your LocalStack instance runs on a different host or port, set the following environment variables in the `env` block: -| Variable | Default | Description | -|---|---|---| +| Variable | Default | Description | +| --------------------- | ----------- | ----------------------------------- | | `LOCALSTACK_HOSTNAME` | `localhost` | Hostname of the LocalStack instance | -| `LOCALSTACK_PORT` | `4566` | Port of the LocalStack instance | +| `LOCALSTACK_PORT` | `4566` | Port of the LocalStack instance | You can also pass any [LocalStack configuration variable](/aws/customization/configuration-options/) through the `env` block. These are forwarded to the container when the `localstack-management` tool starts it. @@ -204,11 +212,11 @@ Each tool runs pre-flight checks (verifying the CLI is available, the container Manage the LocalStack runtime lifecycle for both the AWS emulator and the Snowflake emulator. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `start` \| `stop` \| `restart` \| `status` | Yes | The operation to perform | -| `service` | `aws` \| `snowflake` | No | The stack to manage (default: `aws`) | -| `envVars` | `Record` | No | Extra environment variables passed on `start` | +| Parameter | Type | Required | Description | +| --------- | ------------------------------------------ | -------- | --------------------------------------------- | +| `action` | `start` \| `stop` \| `restart` \| `status` | Yes | The operation to perform | +| `service` | `aws` \| `snowflake` | No | The stack to manage (default: `aws`) | +| `envVars` | `Record` | No | Extra environment variables passed on `start` | **Example prompts:** @@ -220,17 +228,17 @@ Manage the LocalStack runtime lifecycle for both the AWS emulator and the Snowfl Deploy or destroy infrastructure on LocalStack using CDK, Terraform, SAM, or CloudFormation. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `deploy` \| `destroy` \| `create-stack` \| `delete-stack` | Yes | The deployment operation | -| `projectType` | `cdk` \| `terraform` \| `sam` \| `auto` | No | Framework to use (default: `auto`, detected from project files) | -| `directory` | `string` | Yes (for `deploy`/`destroy`) | Path to the project directory | -| `variables` | `Record` | No | Variables passed as Terraform `-var` flags, CDK `--context` values, or SAM `--parameter-overrides` | -| `stackName` | `string` | Yes (for `create-stack`/`delete-stack`) | CloudFormation/SAM stack name | -| `templatePath` | `string` | No | Path to a CloudFormation/SAM template | -| `s3Bucket` | `string` | No | S3 bucket for SAM deployments (if omitted, SAM uses `--resolve-s3`) | -| `resolveS3` | `boolean` | No | For SAM deployments, whether to use `--resolve-s3` when no `s3Bucket` is provided | -| `saveParams` | `boolean` | No | For SAM deployments, whether to persist resolved parameters to `samconfig.toml` | +| Parameter | Type | Required | Description | +| -------------- | --------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `action` | `deploy` \| `destroy` \| `create-stack` \| `delete-stack` | Yes | The deployment operation | +| `projectType` | `cdk` \| `terraform` \| `sam` \| `auto` | No | Framework to use (default: `auto`, detected from project files) | +| `directory` | `string` | Yes (for `deploy`/`destroy`) | Path to the project directory | +| `variables` | `Record` | No | Variables passed as Terraform `-var` flags, CDK `--context` values, or SAM `--parameter-overrides` | +| `stackName` | `string` | Yes (for `create-stack`/`delete-stack`) | CloudFormation/SAM stack name | +| `templatePath` | `string` | No | Path to a CloudFormation/SAM template | +| `s3Bucket` | `string` | No | S3 bucket for SAM deployments (if omitted, SAM uses `--resolve-s3`) | +| `resolveS3` | `boolean` | No | For SAM deployments, whether to use `--resolve-s3` when no `s3Bucket` is provided | +| `saveParams` | `boolean` | No | For SAM deployments, whether to persist resolved parameters to `samconfig.toml` | **Example prompts:** @@ -248,13 +256,13 @@ The `create-stack` and `delete-stack` actions run `awslocal` inside the LocalSta Analyze LocalStack logs to find errors, summarize API activity, or inspect raw output. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `analysisType` | `summary` \| `errors` \| `requests` \| `logs` | No | Type of analysis (default: `summary`) | -| `lines` | `number` | No | Number of log lines to fetch (default: `2000`) | -| `service` | `string` | No | Filter by AWS service name | -| `operation` | `string` | No | Filter by API operation (used with `service` in `requests` mode) | -| `filter` | `string` | No | Keyword filter (used with `logs` mode only) | +| Parameter | Type | Required | Description | +| -------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------- | +| `analysisType` | `summary` \| `errors` \| `requests` \| `logs` | No | Type of analysis (default: `summary`) | +| `lines` | `number` | No | Number of log lines to fetch (default: `2000`) | +| `service` | `string` | No | Filter by AWS service name | +| `operation` | `string` | No | Filter by API operation (used with `service` in `requests` mode) | +| `filter` | `string` | No | Keyword filter (used with `logs` mode only) | **Example prompts:** @@ -266,10 +274,10 @@ Analyze LocalStack logs to find errors, summarize API activity, or inspect raw o Configure IAM enforcement and generate IAM policies from access denials in the logs. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `set-mode` \| `analyze-policies` \| `get-status` | Yes | The operation to perform | -| `mode` | `ENFORCED` \| `SOFT_MODE` \| `DISABLED` | Yes (for `set-mode`) | IAM enforcement level | +| Parameter | Type | Required | Description | +| --------- | ------------------------------------------------ | -------------------- | ------------------------ | +| `action` | `set-mode` \| `analyze-policies` \| `get-status` | Yes | The operation to perform | +| `mode` | `ENFORCED` \| `SOFT_MODE` \| `DISABLED` | Yes (for `set-mode`) | IAM enforcement level | **Example prompts:** @@ -281,21 +289,21 @@ Configure IAM enforcement and generate IAM policies from access denials in the l Inject faults and network latency into LocalStack services to test application resilience. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `inject-faults` \| `add-fault-rule` \| `remove-fault-rule` \| `get-faults` \| `clear-all-faults` \| `inject-latency` \| `get-latency` \| `clear-latency` | Yes | The chaos operation | -| `rules` | `Array` | Yes (for `inject-faults`, `add-fault-rule`, `remove-fault-rule`) | Fault rules to inject/modify | -| `latency_ms` | `number` | Yes (for `inject-latency`) | Latency in milliseconds to add to all requests | +| Parameter | Type | Required | Description | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- | +| `action` | `inject-faults` \| `add-fault-rule` \| `remove-fault-rule` \| `get-faults` \| `clear-all-faults` \| `inject-latency` \| `get-latency` \| `clear-latency` | Yes | The chaos operation | +| `rules` | `Array` | Yes (for `inject-faults`, `add-fault-rule`, `remove-fault-rule`) | Fault rules to inject/modify | +| `latency_ms` | `number` | Yes (for `inject-latency`) | Latency in milliseconds to add to all requests | Each **fault rule** can include: -| Field | Type | Description | -|---|---|---| -| `service` | `string` | Target AWS service (e.g., `s3`, `lambda`) | -| `region` | `string` | Target region (e.g., `us-east-1`) | -| `operation` | `string` | Target API operation (e.g., `PutObject`) | -| `probability` | `number` (0-1) | Probability of the fault triggering | -| `error` | `{ statusCode?: number, code?: string }` | Error response to return | +| Field | Type | Description | +| ------------- | ---------------------------------------- | ----------------------------------------- | +| `service` | `string` | Target AWS service (e.g., `s3`, `lambda`) | +| `region` | `string` | Target region (e.g., `us-east-1`) | +| `operation` | `string` | Target API operation (e.g., `PutObject`) | +| `probability` | `number` (0-1) | Probability of the fault triggering | +| `error` | `{ statusCode?: number, code?: string }` | Error response to return | **Example prompts:** @@ -307,10 +315,10 @@ Each **fault rule** can include: Save, load, and manage LocalStack state snapshots using [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods/). -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `save` \| `load` \| `delete` \| `reset` | Yes | The state management operation | -| `pod_name` | `string` | Yes (for `save`/`load`/`delete`) | Name of the Cloud Pod (alphanumeric, dots, hyphens, underscores; max 128 characters) | +| Parameter | Type | Required | Description | +| ---------- | --------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------ | +| `action` | `save` \| `load` \| `delete` \| `reset` | Yes | The state management operation | +| `pod_name` | `string` | Yes (for `save`/`load`/`delete`) | Name of the Cloud Pod (alphanumeric, dots, hyphens, underscores; max 128 characters) | **Example prompts:** @@ -322,9 +330,9 @@ Save, load, and manage LocalStack state snapshots using [Cloud Pods](/aws/develo Execute AWS CLI commands inside the running LocalStack container via `awslocal`. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `command` | `string` | Yes | The AWS CLI command to run (without the `aws` or `awslocal` prefix) | +| Parameter | Type | Required | Description | +| --------- | -------- | -------- | ------------------------------------------------------------------- | +| `command` | `string` | Yes | The AWS CLI command to run (without the `aws` or `awslocal` prefix) | **Example prompts:** @@ -339,11 +347,11 @@ If a command fails due to a service not being emulated, the tool returns a link Install, uninstall, list, and discover [LocalStack Extensions](/aws/customization/integrations/extensions/) from the marketplace. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `list` \| `install` \| `uninstall` \| `available` | Yes | The extensions operation | -| `name` | `string` | Yes (for `install`/`uninstall`) | Extension package name (e.g., `localstack-extension-typedb`) | -| `source` | `string` | No | Git URL to install from (alternative to `name`) | +| Parameter | Type | Required | Description | +| --------- | ------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ | +| `action` | `list` \| `install` \| `uninstall` \| `available` | Yes | The extensions operation | +| `name` | `string` | Yes (for `install`/`uninstall`) | Extension package name (e.g., `localstack-extension-typedb`) | +| `source` | `string` | No | Git URL to install from (alternative to `name`) | **Example prompts:** @@ -360,14 +368,14 @@ After installing or uninstalling an extension, the tool automatically restarts L Manage cloud-hosted [Ephemeral Instances](/aws/developer-tools/cloud-sandbox/ephemeral-instances/) for remote LocalStack testing workflows. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `create` \| `list` \| `logs` \| `delete` | Yes | The ephemeral instance operation | -| `name` | `string` | Yes (for `create`/`logs`/`delete`) | Instance name | -| `lifetime` | `number` | No | Lifetime in minutes for the instance (only for `create`) | -| `extension` | `string` | No | Extension package to preload on the instance (only for `create`) | -| `cloudPod` | `string` | No | Cloud Pod name to initialize state from (only for `create`) | -| `envVars` | `Record` | No | Extra environment variables for the instance (only for `create`) | +| Parameter | Type | Required | Description | +| ----------- | ---------------------------------------- | ---------------------------------- | ---------------------------------------------------------------- | +| `action` | `create` \| `list` \| `logs` \| `delete` | Yes | The ephemeral instance operation | +| `name` | `string` | Yes (for `create`/`logs`/`delete`) | Instance name | +| `lifetime` | `number` | No | Lifetime in minutes for the instance (only for `create`) | +| `extension` | `string` | No | Extension package to preload on the instance (only for `create`) | +| `cloudPod` | `string` | No | Cloud Pod name to initialize state from (only for `create`) | +| `envVars` | `Record` | No | Extra environment variables for the instance (only for `create`) | **Example prompts:** @@ -380,10 +388,10 @@ Manage cloud-hosted [Ephemeral Instances](/aws/developer-tools/cloud-sandbox/eph Search the LocalStack documentation to find guides, API references, and configuration details. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `query` | `string` | Yes | The search query | -| `limit` | `number` | No | Maximum number of results to return (default: `5`, max: `10`) | +| Parameter | Type | Required | Description | +| --------- | -------- | -------- | ------------------------------------------------------------- | +| `query` | `string` | Yes | The search query | +| `limit` | `number` | No | Maximum number of results to return (default: `5`, max: `10`) | **Example prompts:** @@ -394,15 +402,15 @@ Search the LocalStack documentation to find guides, API references, and configur Execute SQL queries and commands against the [LocalStack Snowflake emulator](/snowflake/) using the Snowflake CLI (`snow`). -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `execute` \| `check-connection` | Yes | The operation to perform | -| `query` | `string` | Yes (for `execute`, if `file_path` not provided) | SQL query to execute | -| `file_path` | `string` | Yes (for `execute`, if `query` not provided) | Absolute path to a `.sql` file to execute | -| `database` | `string` | No | Snowflake database context | -| `schema` | `string` | No | Snowflake schema context | -| `warehouse` | `string` | No | Snowflake warehouse to use | -| `role` | `string` | No | Snowflake role to use | +| Parameter | Type | Required | Description | +| ----------- | ------------------------------- | ------------------------------------------------ | ----------------------------------------- | +| `action` | `execute` \| `check-connection` | Yes | The operation to perform | +| `query` | `string` | Yes (for `execute`, if `file_path` not provided) | SQL query to execute | +| `file_path` | `string` | Yes (for `execute`, if `query` not provided) | Absolute path to a `.sql` file to execute | +| `database` | `string` | No | Snowflake database context | +| `schema` | `string` | No | Snowflake schema context | +| `warehouse` | `string` | No | Snowflake warehouse to use | +| `role` | `string` | No | Snowflake role to use | **Example prompts:** @@ -421,31 +429,31 @@ Once your MCP client is configured, verify the setup by opening a conversation w **1. Start LocalStack** -> *"Start my LocalStack container."* +> _"Start my LocalStack container."_ The agent uses the `localstack-management` tool to start the container and confirms the status. **2. Deploy infrastructure** -> *"Deploy my CDK project in the `./my-app` directory."* +> _"Deploy my CDK project in the `./my-app` directory."_ The agent detects the framework, runs `cdklocal bootstrap` and `cdklocal deploy`, and returns the stack outputs. **3. Verify resources** -> *"List the Lambda functions and DynamoDB tables that were created."* +> _"List the Lambda functions and DynamoDB tables that were created."_ The agent runs `awslocal` commands inside the container and returns the results. **4. Analyze logs** -> *"Check the LocalStack logs for any errors."* +> _"Check the LocalStack logs for any errors."_ The agent fetches recent logs and highlights any errors or warnings. **5. Save state** -> *"Save a Cloud Pod named `my-checkpoint`."* +> _"Save a Cloud Pod named `my-checkpoint`."_ The agent persists the current LocalStack state so you can restore it later. @@ -453,13 +461,13 @@ The agent persists the current LocalStack state so you can restore it later. The following environment variables can be set in the `env` block of your MCP configuration: -| Variable | Default | Description | -|---|---|---| -| `LOCALSTACK_AUTH_TOKEN` (**required**) | None | Your LocalStack Auth Token. Required for all MCP server tools. | -| `LOCALSTACK_HOSTNAME` | `localhost` | Hostname of the LocalStack instance | -| `LOCALSTACK_PORT` | `4566` | Port of the LocalStack instance | -| `MAIN_CONTAINER_NAME` | `localstack-main` | Name of the LocalStack Docker container | -| `MCP_ANALYTICS_DISABLED` | `0` | Set to `1` to disable MCP analytics | +| Variable | Default | Description | +| -------------------------------------- | ----------------- | -------------------------------------------------------------- | +| `LOCALSTACK_AUTH_TOKEN` (**required**) | None | Your LocalStack Auth Token. Required for all MCP server tools. | +| `LOCALSTACK_HOSTNAME` | `localhost` | Hostname of the LocalStack instance | +| `LOCALSTACK_PORT` | `4566` | Port of the LocalStack instance | +| `MAIN_CONTAINER_NAME` | `localstack-main` | Name of the LocalStack Docker container | +| `MCP_ANALYTICS_DISABLED` | `0` | Set to `1` to disable MCP analytics | Any [LocalStack configuration variable](/aws/customization/configuration-options/) can also be passed through the `env` block. These are forwarded to the container when the `localstack-management` tool starts it. diff --git a/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx b/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx index c4813cdc6..c6b460cf9 100644 --- a/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx +++ b/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx @@ -30,7 +30,7 @@ They all can be summarised as: ## Creating a custom docker image -If you run LocalStack in a docker container (which includes using [the CLI](/aws/getting-started/installation/#installing-localstack-cli), [docker](/aws/getting-started/installation/#docker), [docker-compose](/aws/getting-started/installation/#docker-compose), or [helm](/aws/customization/kubernetes/deploy-helm-chart)), to include a custom TLS root certificate a new docker image should be created. +If you run LocalStack in a docker container (which includes using [the CLI](/aws/getting-started/installation/#install-localstack-cli), [docker](/aws/getting-started/installation/#docker-compose), [docker-compose](/aws/getting-started/installation/#docker-compose), or [helm](/aws/customization/kubernetes/deploy-helm-chart)), to include a custom TLS root certificate a new docker image should be created. Create a `Dockerfile` containing the following commands: 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 14b43118e..9c135cff4 100644 --- a/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx +++ b/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx @@ -1,17 +1,15 @@ --- -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 - 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: @@ -24,11 +22,11 @@ Cloud Pods can be used for various purposes, such as: ## Installation -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). +You can save and load the persistent state of Cloud Pods, you can use the [`lstk snapshot` command](/aws/developer-tools/running-localstack/lstk/#snapshot). LocalStack provides a remote storage backend that can be used to store the state of your running application and share it with your team members. You can interact with the Cloud Pods over the storage backend via the LocalStack Web Application. -Cloud Pods CLI is included in the [LocalStack CLI installation](/aws/getting-started/installation/#installing-localstack-cli), so there's no need for additional installations to begin using it. +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. @@ -199,7 +197,7 @@ localstack state inspect --format json } ``` -For comprehensive instructions, navigate to our [Command-Line Interface (CLI) Guide](/aws/developer-tools/snapshots/cli-commands/). +For comprehensive instructions, navigate to our [`lstk` CLI Guide](/aws/developer-tools/running-localstack/lstk/#snapshot). To access your Cloud Pods through the LocalStack Web Application, navigate to the [Cloud Pods browser](https://app.localstack.cloud/pods). :::note @@ -371,160 +369,6 @@ 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/#updating-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. @@ -579,70 +423,6 @@ Custom remote configurations are stored within the [LocalStack volume directory] 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. @@ -669,7 +449,7 @@ 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/developer-tools/snapshots/persistence#state-compatibility) shared with snapshot-based persistence. +In addition to this prompt, Cloud Pods are subject to the [snapshot compatibility rules](/aws/developer-tools/snapshots/service-coverage#state-compatibility) shared with snapshot-based persistence. Pods that were saved before `v2026.03` cannot be loaded into LocalStack `v2026.03` or later, because persistence was rewritten for several services in that release. Set `DISABLE_COMPATIBILITY_RULES=1` to bypass the checks at your own risk. 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..51ac8f2f1 --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/other-snapshot-storage-options.md @@ -0,0 +1,164 @@ +--- +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). +::: 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..fc4c05d1b --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/save-snapshots-locally.md @@ -0,0 +1,145 @@ +--- +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. + +#### `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.snapshot +lstk snapshot load --merge=overwrite snapshot2.snapshot + +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.snapshot +lstk snapshot load --merge=account-region-merge snapshot2.snapshot +``` + +TBD: THE OUTPUT FROM ACCOUNT_REGION_MERGE IS NOT CORRECT YET. + + +#### `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.snapshot +lstk snapshot load --merge=service-merge snapshot2.snapshot + +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 in 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/getting-started/ai-workflows.mdx b/src/content/docs/aws/getting-started/ai-workflows.mdx new file mode 100644 index 000000000..091267b3c --- /dev/null +++ b/src/content/docs/aws/getting-started/ai-workflows.mdx @@ -0,0 +1,108 @@ +--- +title: AI & Agent Workflows +description: Use LocalStack with AI coding assistants, MCP clients, and agent-driven infrastructure workflows. +template: doc +sidebar: + order: 5 +--- + +## Introduction + +LocalStack gives AI coding assistants a local AWS-compatible environment to work against. Instead of letting an agent experiment in a real AWS account, you can ask it to create infrastructure, deploy code, inspect logs, and test resources in LocalStack first. + +This is useful when you want to: + +- Prototype AWS applications & infrastructure code from natural language prompts. +- Validate AI-generated Terraform, CDK, or AWS CLI commands before using a cloud account. +- Give an AI assistant a safe place to inspect resources, debug logs, and iterate on deployments. +- Use reusable agent instructions for LocalStack-aware infrastructure workflows. + +## Common workflows + +There are three common ways to use LocalStack in AI-assisted development: + +- Use the [LocalStack MCP Server](/aws/tooling/mcp-server/) when your AI assistant supports MCP clients such as Cursor, Claude, Codex, or OpenCode. +- Use [LocalStack Skills](https://github.com/localstack/skills) when you want reusable agent instructions for deploying and testing AWS architectures against LocalStack. +- Use LocalStack with `tflocal`, `cdklocal`, or `awslocal` when you want the agent to generate infrastructure code or commands that you review and run locally. + +You do not need all three approaches to get started. If your editor supports MCP, start with the LocalStack MCP Server. Or, you can use Skills if you want reusable agent instructions. If not, ask your assistant to generate Terraform, CDK, or AWS CLI steps and run them with LocalStack's local wrappers. + +## Quick Setup + +LocalStack has provided an [`agents.md`](https://blog.localstack.cloud/ai/agents.md) file that provides the full instructions for your AI agent to get started with LocalStack, including how to configure the MCP server and LocalStack Skills. Details can be found at our [agents landing page](https://blog.localstack.cloud/ai/) or you can copy and paste the instructions below into your AI agent's prompt. + +```text +Fetch https://blog.localstack.cloud/ai/agents.md and follow the instructions to set up LocalStack on my machine. +``` + +For manual setup of the MCP server and skills, you can follow the steps below. + +## Connect an MCP client + +The LocalStack MCP Server connects MCP-compatible clients to your LocalStack environment. Once configured, your AI assistant can use LocalStack tools to start the container, deploy infrastructure, run AWS CLI commands, inspect logs, manage state, and query resources. + +Start the MCP server with an interactive setup wizard: + +```bash +npx -y @localstack/localstack-mcp-server init +``` + +:::note +The MCP server runs locally and talks to a LocalStack instance. Your AI assistant is the MCP client. For full installation instructions, detailed setup, and the full tool reference, see the [LocalStack MCP Server guide](/aws/tooling/mcp-server/). + +You need a valid [Auth Token](/aws/getting-started/auth-token/) to configure the server. +::: + +## Use agent skills + +[LocalStack Skills](https://github.com/localstack/skills) provide reusable instructions for AI agents working with LocalStack. They help agents follow LocalStack-specific conventions when creating infrastructure, deploying resources, running tests, and inspecting local cloud state. + +Skills are most useful when you want the assistant to follow a repeatable workflow, for example: + +- Scaffold a local AWS application and deploy it to LocalStack. +- Convert an AWS architecture idea into Terraform or CDK that targets LocalStack first. +- Debug a failing local deployment by checking resources, logs, and configuration. +- Save or restore LocalStack state as part of an iterative development loop. + +Refer to the [LocalStack Skills repository](https://github.com/localstack/skills) for available skills and setup instructions. + +## Example prompt sequence + +After LocalStack and your preferred AI tooling are configured, you can use a sequence like this: + +```text +Create a Terraform application with an S3 bucket, a Lambda function, and a DynamoDB table. +Make it deployable to LocalStack with tflocal. +``` + +```text +Deploy the application to LocalStack and fix any errors from the deployment. +``` + +```text +Invoke the Lambda function locally, inspect the DynamoDB table, and summarize what resources were created. +``` + +```text +Add an integration test that verifies the Lambda writes an item to DynamoDB. +Run the test against LocalStack. +``` + +This keeps the feedback loop local while still giving the assistant a realistic AWS-compatible target. + +## Review before applying to AWS + +AI-generated infrastructure still needs review. Treat LocalStack as the first validation step, not as a replacement for code review, tests, or production deployment controls. + +Before applying changes to AWS, check that: + +- The generated infrastructure matches your intended architecture. +- Resource names, IAM policies, and environment variables are appropriate for your project. +- Tests pass against LocalStack. +- You understand any changes the assistant made to application code or deployment configuration. + +## Next steps + +- Configure the [LocalStack MCP Server](/aws/tooling/mcp-server/) if your AI assistant supports MCP. +- Review [LocalStack Skills](https://github.com/localstack/skills) for reusable agent workflows. +- Browse the [LocalStack for AWS services](/aws/services/) reference, or check the [Getting Started FAQ](/aws/getting-started/faq/) for common setup questions. diff --git a/src/content/docs/aws/getting-started/auth-token.mdx b/src/content/docs/aws/getting-started/auth-token.mdx index 8a14e258c..0c1ec7fd7 100644 --- a/src/content/docs/aws/getting-started/auth-token.mdx +++ b/src/content/docs/aws/getting-started/auth-token.mdx @@ -1,167 +1,81 @@ --- title: Auth Token -description: Configure your Auth Token to access and activate LocalStack. +description: Configure and manage your LocalStack Auth Token to activate LocalStack and access licensed features. template: doc sidebar: - order: 3 + order: 6 --- -import { Code, Tabs, TabItem } from '@astrojs/starlight/components'; +import { Tabs, TabItem } from '@astrojs/starlight/components'; -## Introduction +## What is an Auth Token? -The Auth Token is required to activate the LocalStack for AWS core cloud emulator. It identifies and authenticates users outside the LocalStack Web Application. -It primarily accesses your workspace and advanced services & features. +An Auth Token is a mandatory credential required to start the LocalStack container and activate licensed features. It links your running LocalStack instance to your workspace license and unlocks the services and capabilities available to your account. -Auth tokens come in two types: a **Developer Auth Token** and a **CI Auth Token**: +You can manage Auth Tokens from the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application. -- The **Developer Auth Token** is linked to a specific user within a specific workspace. - Every user has their own Auth Token. - It cannot be deleted but can be rotated for security reasons if needed. -- The **CI Auth Token** is not associated with any specific user and is designed for use in CI environments and other non-developer contexts. - These tokens are stored in the workspace and can be managed by members with appropriate permissions. - -Both the **Developer Auth Token** and **CI Auth Token** can be managed on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens). - -:::danger - -- It's crucial to keep your Auth Token confidential. - Do not include it in source code management systems, such as Git repositories. -- Be aware that if an Auth Token is committed to a public repository, it is at risk of exposure, and could remain in the repository's history, even if attempts are made to rewrite it. -- In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens). - ::: - -## Managing your License - -To use LocalStack, a license is required. -You can get a license by [signing up for a free LocalStack account](https://www.localstack.cloud/pricing). -Choose between a 14-day trial or explore additional features with our paid offering. -During the trial period, you are welcome to use all the features of LocalStack. - -After initiating your trial or acquiring a license, proceed to assign it to a user by following the steps outlined below: - -- Visit the [Users & Licenses page](https://app.localstack.cloud/workspace/members). -- Select a user in the **Workspace Members** section for license assignment. -- Define user's role via the **Member Role** dropdown. - Single users automatically receive the **Admin** role. -- Toggle **Advanced Permissions** to set specific permissions. - Single users automatically receive full permissions. -- Click **Save** to complete the assignment. - Single users assign licenses to themselves. - -![Assigning a license](/images/aws/assigning-a-license.png) - -If you have joined a workspace, you need to be assigned a license by the workspace administrator. -In case of switching workspaces or licenses, you need to make sure that you are assigned to the correct license. - -:::note -If you do not assign a license, you will not be able to use LocalStack even if you have a valid Auth token. +:::danger[Credential security] +Auth Tokens provide access to your license and workspace. Do not commit tokens to version control. If a token is exposed, rotate it immediately in the LocalStack Web Application. ::: -To view your own assigned license, visit the [My License page](https://app.localstack.cloud/workspace/my-license). -You can further navigate to the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) to view your **Developer Auth Token** and **CI Auth Token**. - -## Configuring your Auth Token +## Token types -LocalStack requires the `LOCALSTACK_AUTH_TOKEN` environment variable to contain your Auth Token. -You can configure your Auth Token in several ways, depending on your use case. -The following sections describe the various methods of setting your Auth Token. +| Token Type | Scope | Use Case | +| :--- | :--- | :--- | +| **Developer Token** | Individual | Local development workstations. Managed per user. | +| **CI Auth Token** | Workspace | Automated pipelines and shared runners. Managed by workspace admins. | -:::danger +## Configure your token -- It's crucial to keep your Auth Token confidential. - Do not include it in source code management systems, such as Git repositories. -- Be aware that if an Auth Token is committed to a public repository, it's at risk of exposure, and could remain in the repository's history, even if attempts are made to rewrite it. -- In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens). - ::: +Authentication requirements vary based on your chosen execution method. -### LocalStack CLI +### lstk -You should set the `LOCALSTACK_AUTH_TOKEN` environment variable either before or during the startup of LocalStack using the `localstack` command-line interface (CLI). +The `lstk` CLI automates the authentication lifecycle. On initial execution, it triggers a browser-based OAuth flow and stores the resulting token in your system keyring. No manual environment variable configuration is required. - - - \nlocalstack start`} - lang="shell" - /> - - - \nlocalstack start`} - lang="powershell" - /> - - - -:::note +```bash +lstk start +``` -1. You can alternatively set the `LOCALSTACK_AUTH_TOKEN` environment variable in your shell session. - This ensures the Auth Token is transmitted to your LocalStack container, enabling key activation. -2. The `localstack auth set-token` command is only available for `localstack` CLI and cannot be used with a Docker/Docker Compose setup. - ::: +### LocalStack CLI -You have the option to run your LocalStack container in the background by appending the `-d` flag to the `localstack start` command. +If you use the LocalStack CLI, set your token with the `auth` command. This stores the token in your local configuration. -The `localstack` CLI automatically detects the Auth Token and appropriately conveys it to the LocalStack container. +```bash +localstack auth set-token +localstack start +``` :::note -If you are using LocalStack with an Auth Token, it's necessary to download the [LocalStack for AWS image](/aws/customization/other-installations/docker-images#localstack-for-aws-image), which includes Pro services and several advanced features. +You can alternatively set the `LOCALSTACK_AUTH_TOKEN` environment variable in your shell session. +The `localstack auth set-token` command is only available for the `localstack` CLI and cannot be used with a Docker or Docker Compose setup. ::: -### Docker +### Docker and Docker Compose -To start LocalStack via Docker, you need to provide the Auth Token using the `-e` flag, which is used for setting environment variables. - -```bash {5} -docker run \ - --rm -it \ - -p 4566:4566 \ - -p 4510-4559:4510-4559 \ - -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:- } \ - localstack/localstack-pro -``` +For direct container execution, inject the token as an environment variable. For complete startup examples, see the [Docker Compose](/aws/getting-started/installation/#docker-compose) and [Docker CLI](/aws/getting-started/installation/#docker-cli) installation options. -For more information about starting LocalStack with Docker, take a look at our [Docker installation](/aws/getting-started/installation/#docker) guide. +**Docker CLI:** -### Docker Compose +```bash +-e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} +``` -To start LocalStack using `docker compose`, you have to include the `LOCALSTACK_AUTH_TOKEN` environment variable in your `docker-compose.yml` file: +**Docker Compose:** ```yaml environment: - - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN- } + - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} ``` -You can manually set the Auth Token, or use the `export` command to establish the Auth Token in your current shell session. -This ensures the Auth Token is transmitted to your LocalStack container, enabling key activation. - -### CI Environments - -CI environments require a CI Auth Token. -Developer Auth Tokens cannot be used in CI. -CI Auth Tokens are available on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) and are configured similarly to Developer Auth Tokens. - -To set the CI Auth Token, add the Auth Token value in the `LOCALSTACK_AUTH_TOKEN` environment variable of your CI provider, and refer to it when starting LocalStack in your CI workflow. -You can find detailed examples in our [LocalStack in CI documentation](/aws/ci-pipelines/). - -## Rotating the Auth Token - -Your personal Auth Token provides full access to your workspace and LocalStack license. -It's important to treat auth tokens as confidential, avoiding sharing or storing them in source control management systems (SCMs) like Git. - -If you believe your Auth Token has been compromised or becomes known to someone else, reset it without delay. -When you reset a token, the old one is immediately deactivated, losing its ability to access your license or workspace. -It is not possible to restore previous tokens. - -To rotate your Auth Token, go to the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and select the **Reset Auth Token** option. +### CI environments -## Licensing configuration & activation checkup +CI environments should use a dedicated CI Auth Token stored in your CI provider's secret manager. +For complete examples, see the [CI/CD guide](/aws/getting-started/ci-cd/). -To avoid logging any licensing-related error messages, set `LOG_LICENSE_ISSUES=0` in your environment. -Refer to our [configuration guide](/aws/customization/configuration-options/#localstack-for-aws) for more information. +## Verify activation -The simplest method to verify if LocalStack is active is by querying the health endpoint for a list of running services: +Verify the activation status by querying the LocalStack info endpoint: @@ -173,61 +87,44 @@ The simplest method to verify if LocalStack is active is by querying the health - ```bash + ```powershell Invoke-WebRequest -Uri http://localhost:4566/_localstack/info | ConvertFrom-Json ``` -The following output would be retrieved: - -```bash +```json title="Output" { - "version": "3.0.0:6dd3f3d", "edition": "pro", - "is_license_activated": true, - "session_id": "7132da5f-a380-44ca-8897-6f0fdfd7b1c9", - "machine_id": "0c49752c", - "system": "linux", - "is_docker": true, - "server_time_utc": "2023-11-21T05:41:33", - "uptime": 161 + "is_license_activated": true } ``` -The `edition` field is always `pro` and the `is_license_activated` field is set to `true`. -Another way to confirm this is by checking the logs of the LocalStack container for a message indicating successful license activation: - -```bash -[...] Successfully activated license -``` - -Otherwise, check our [troubleshooting](#troubleshooting) section. - -## FAQ +The `edition` field should be `pro`, and `is_license_activated` should be `true`. -### How do I activate older versions of LocalStack (Before v3.0)? +## License assignment -Prior to the introduction of Auth Tokens, LocalStack used **API keys** managed through the `LOCALSTACK_API_KEY` environment variable for activation. +An Auth Token can only activate licensed features if a license is assigned to the associated user or workspace. -For backwards compatibility, we've updated our back-end to accept new Auth Tokens within the `LOCALSTACK_API_KEY` variable. -You can use the new Auth Token in the same way you previously used the API key. +1. Navigate to the [Users & Licenses page](https://app.localstack.cloud/workspace/members). +2. Identify the target user in **Workspace Members**. +3. Select the appropriate **Member Role**. +4. Save the configuration to activate the license for that identity. -### When will the legacy API keys be phased out? +:::note +LocalStack cannot activate licensed features unless the token belongs to a user or workspace with an assigned license. +::: -In early 2025, we will begin phasing out legacy API keys entirely. -After the sunsetting period, legacy API and legacy CI keys will no longer activate or work with LocalStack. +## Rotate a token -During the sunsetting period, the legacy service will experience scheduled downtimes. -These are planned to encourage users to transition to new Auth Tokens while minimizing impact for those who have not yet updated. +Rotate an Auth Token if it has been exposed, shared accidentally, or stored in a place where it should not be. Go to the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) and select the reset option for the affected token. -The downtime schedule will be communicated well in advance, allowing users ample time to switch to the new Auth Tokens. +After rotation, update every local shell, container configuration, or CI secret that used the old token. ## Troubleshooting -While using Auth Tokens, LocalStack demands a successful license activation for startup. -If the activation of the license is unsuccessful, LocalStack will exit and display error messages. +LocalStack requires successful license activation during startup. If activation fails, LocalStack exits and displays an error message: ```bash =============================================== @@ -235,18 +132,17 @@ License activation failed! 🔑❌ Reason: The credentials defined in your environment are invalid. Please make sure to either set the LOCALSTACK_AUTH_TOKEN variable to a valid auth token, or the LOCALSTACK_API_KEY variable to a valid LocalStack API key. You can find your Auth Token or API key in the LocalStack web app https://app.localstack.cloud. -Due to this error, Localstack has quit. LocalStack for AWS features can only be used with a valid license. +Due to this error, Localstack has quit. LocalStack pro features can only be used with a valid license. - Please check that your credentials are set up correctly and that you have an active license. You can find your credentials in our webapp at https://app.localstack.cloud. -- If you want to continue using LocalStack without pro features you can set `ACTIVATE_PRO=0`. ``` -The key activation in LocalStack may fail for several reasons, and the most common ones are listed below in this section. +Activation may fail for several reasons, and the most common ones are listed below. -### Missing Credentials +### Missing credentials -You need to provide either an Auth Token to start the LocalStack for AWS image successfully. +You need to provide an Auth Token to start the LocalStack for AWS image successfully. You can find your Auth Token on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application. If you are using the `localstack` CLI, you can set the `LOCALSTACK_AUTH_TOKEN` environment variable to your Auth Token or use the following command to set it up: @@ -255,12 +151,12 @@ If you are using the `localstack` CLI, you can set the `LOCALSTACK_AUTH_TOKEN` e localstack auth set-token ``` -### Invalid License +### Invalid license The issue may occur if there is no valid license linked to your account due to expiration or if the license has not been assigned. You can check your license status in the LocalStack Web Application on the [My License page](https://app.localstack.cloud/workspace/my-license). -### License Server Unreachable +### License server unreachable LocalStack initiates offline activation when the license server is unreachable, requiring re-activation every 24 hours. Log output may indicate issues with your machine resolving the LocalStack API domain, which can be verified using a tool like `dig`: @@ -273,4 +169,8 @@ If the result shows a status other than `status: NOERROR`, your machine is unabl Certain corporate DNS servers may filter requests to specific domains. Kindly reach out to your network administrator to safelist `localstack.cloud` domain. -If you have any further problems concerning your license activation, or if the steps do not help, do not hesitate to [contact us](https://localstack.cloud/contact/). +If you have any further problems concerning your license activation, or if the steps do not help, don't hesitate to [contact us](https://localstack.cloud/contact/). + +## Next steps + +After configuring your Auth Token, continue to the [Local Development guide](/aws/getting-started/local-development/) to start LocalStack and deploy a local serverless API. diff --git a/src/content/docs/aws/getting-started/ci-cd.mdx b/src/content/docs/aws/getting-started/ci-cd.mdx new file mode 100644 index 000000000..b3dacb0ef --- /dev/null +++ b/src/content/docs/aws/getting-started/ci-cd.mdx @@ -0,0 +1,211 @@ +--- +title: CI Integration +description: Use LocalStack in CI pipelines to run integration tests against local AWS infrastructure. +template: doc +sidebar: + order: 4 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +## Introduction + +LocalStack helps you run integration tests in CI against emulated AWS infrastructure. Your pipeline starts LocalStack inside the CI job, deploys or prepares the resources your application needs, runs tests against the local endpoint, and then discards the environment when the job ends. + +## How LocalStack works in CI + +A typical CI job with LocalStack follows this flow: + +1. Check out your application code. +2. Start LocalStack in the CI runner. +3. Configure a CI Auth Token through the CI provider's secret manager. +4. Deploy test infrastructure with tools such as `awslocal`, `tflocal`, `cdklocal`, or your application's test harness. +5. Run integration tests against the LocalStack endpoint. +6. Collect logs, test reports, and artifacts from the job. + +This gives every pipeline run a fresh AWS-compatible environment without creating cloud resources in an AWS account. + +## What changes from local development + +CI runs are usually more constrained than local development: + +- Use a dedicated **CI Auth Token** instead of a personal Developer Token. +- Store `LOCALSTACK_AUTH_TOKEN` as a protected CI secret. +- Start LocalStack non-interactively as part of the job. +- Treat the LocalStack container as ephemeral unless your workflow explicitly saves state. +- Export logs and test reports before the runner shuts down. + +Docker and Docker Compose are still common ways to run containers inside CI runners, but they are not CI tools by themselves. For container startup details, see the [Installation guide](/aws/getting-started/installation/#container-and-orchestration-tools). For provider-specific CI setup, use the integration guides below. + +## Choose your CI provider + +Start with the CI system you use. These snippets show the basic LocalStack startup shape for each provider; the linked guides include authentication, configuration, logs, state management, and provider-specific caveats. + +:::note +For brevity, these snippets show only the LocalStack startup shape. Apart from the GitHub Actions example, they assume your CI Auth Token is already exposed to the job as the `LOCALSTACK_AUTH_TOKEN` environment variable. Store it as a secret in your CI provider before running them, and see [Authentication in CI](#authentication-in-ci) below. +::: + + + + + ```yaml + - name: Start LocalStack + uses: LocalStack/setup-localstack@main + with: + image-tag: 'latest' + install-awslocal: 'true' + env: + LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} + ``` + + See the [GitHub Actions guide](/aws/integrations/continuous-integration/github-actions/) for the full setup. + + + + + ```yaml + version: '2.1' + orbs: + python: circleci/python@4.0.0 + jobs: + localstack-test: + machine: + image: ubuntu-2204:current + steps: + - checkout + - run: + name: Install lstk and awslocal + command: | + python3 -m pip install --user --upgrade pip + python3 -m pip install --user localstack awscli-local[ver1] + echo 'export PATH=$HOME/.local/bin:$PATH' >> "$BASH_ENV" + - run: + name: Start LocalStack + command: | + source "$BASH_ENV" + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 + ``` + + See the [CircleCI guide](/aws/integrations/continuous-integration/circleci/) for the full setup. + + + + + ```yaml + image: python:3.9 + + definitions: + services: + docker: + memory: 2048 + + pipelines: + default: + - step: + name: Test LocalStack + services: + - docker + script: + - export DOCKER_SOCK=$DOCKER_HOST + - export AWS_ENDPOINT_URL="http://localhost.localstack.cloud:4566" + - echo "${BITBUCKET_DOCKER_HOST_INTERNAL} localhost.localstack.cloud " >> /etc/hosts + - pip install localstack awscli-local + - docker run -d --rm -p 4566:4566 -p 4510-4559:4510-4559 -e DOCKER_SOCK=tcp://${BITBUCKET_DOCKER_HOST_INTERNAL}:2375 -e DOCKER_HOST=tcp://${BITBUCKET_DOCKER_HOST_INTERNAL}:2375 --name localstack-main localstack/localstack + - localstack wait -t 60 + ``` + + See the [Bitbucket Pipelines guide](/aws/integrations/continuous-integration/bitbucket/) for the full setup. + + + + + ```yaml + version: 0.2 + + phases: + pre_build: + commands: + - pip3 install localstack awscli + - docker pull public.ecr.aws/localstack/localstack:latest + - localstack start -d + - localstack wait -t 30 + ``` + + See the [CodeBuild guide](/aws/integrations/continuous-integration/codebuild/) for the full setup. + + + + + ```yaml + stages: + - test + + variables: + DOCKER_HOST: tcp://docker:2375 + DOCKER_TLS_CERTDIR: "" + LOCALSTACK_HOST: "localstack:4566" + + services: + - name: localstack/localstack:latest + alias: localstack + - name: docker:dind + alias: docker + command: ["--tls=false"] + + localstack-test: + stage: test + image: python:3.11 + script: + - pip install awscli-local + - awslocal s3 mb s3://test-bucket + ``` + + See the [GitLab CI guide](/aws/integrations/continuous-integration/gitlab-ci/) for the full setup. + + + + + ```yaml + language: python + + services: + - docker + + python: + - "3.8" + + before_install: + - python -m pip install localstack awscli-local[ver1] + - docker pull localstack/localstack + - localstack start -d + - localstack wait -t 30 + ``` + + See the [Travis CI guide](/aws/integrations/continuous-integration/travis-ci/) for the full setup. + + + + +You can also start from the [CI integrations overview](/aws/integrations/continuous-integration/) if you want a broader explanation of the CI workflow. + +## Authentication in CI + +CI environments should use a CI Auth Token. Create one from the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens), then store it as `LOCALSTACK_AUTH_TOKEN` in your CI provider's secret manager. + +Do not commit tokens to your repository or write them directly into workflow files. For more details on token types and rotation, see the [Auth Token guide](/aws/getting-started/auth-token/). + +## State in CI + +Most CI jobs should start with a clean LocalStack instance. A fresh instance makes test runs reproducible and avoids hidden dependencies between jobs. + +If your pipeline needs state across jobs or workflow stages, use one of the state management options documented outside this getting started page: + +- [Cloud Pods](/aws/capabilities/state-management/cloud-pods/) to save and restore named LocalStack state snapshots. +- [State export and import](/aws/capabilities/state-management/export-import-state/) to move state through artifacts or caches. +- [Persistence](/aws/capabilities/state-management/persistence/) when the same runner keeps a mounted LocalStack volume. + +## Next steps + +After choosing your CI provider, continue to [AI & Agent Workflows](/aws/getting-started/ai-workflows/) to learn how AI coding assistants can help generate, deploy, and test LocalStack-backed AWS applications. diff --git a/src/content/docs/aws/getting-started/faq.mdx b/src/content/docs/aws/getting-started/faq.mdx index 62106f672..a47a1e9bd 100644 --- a/src/content/docs/aws/getting-started/faq.mdx +++ b/src/content/docs/aws/getting-started/faq.mdx @@ -3,7 +3,7 @@ title: FAQ description: Frequently asked questions about LocalStack for AWS. template: doc sidebar: - order: 5 + order: 7 --- import { Tabs, TabItem } from '@astrojs/starlight/components'; @@ -35,20 +35,6 @@ To resolve the issue follow the steps: For other SSL-related issues encountered during startup — such as Python `CERTIFICATE_VERIFY_FAILED` tracebacks or corporate TLS interception — see [How do I diagnose if my SSL traffic is being intercepted by a corporate proxy?](#how-do-i-diagnose-if-my-ssl-traffic-is-being-intercepted-by-a-corporate-proxy). -### How to update my LocalStack CLI? - -If the LocalStack CLI version is heavily outdated, it might lead to issues with container startup and debug commands. -If you are using an older version of LocalStack, you can update it by running the following command: - -```bash -pip install --upgrade localstack localstack-ext -``` - -If you are running a newer version of LocalStack, you can check the version by running the following command: - -```bash -localstack update localstack-cli -``` ### Is using `localhost.localstack.cloud:4566` to set as the endpoint for AWS services recommended? @@ -122,23 +108,6 @@ aws ssm put-parameter --name "//test/parameter/new" --type String --value "test" For additional known issues related to Git Bash, you can refer to the following link: [Git Bash Known Issues](https://github.com/git-for-windows/build-extra/blob/main/ReleaseNotes.md#known-issues) -### How to fix LocalStack CLI (Python) UTF-8 encoding issue under Windows? - -If you are using LocalStack CLI under Windows, you might run into encoding issues. -To fix this, set the following environment variables: -Set the system locale (language for non-Unicode programs) to UTF-8 to avoid Unicode errors. - -Follow these steps: - -- Open the Control Panel. -- Go to "Clock and Region" or "Region and Language." -- Click on the "Administrative" tab. -- Click on the "Change system locale" button. -- Select "Beta: Use Unicode UTF-8 for worldwide language support" and click "OK." -- Restart your computer to apply the changes. - -If you would like to keep the system locale as it is, you can mitigate the issue by using the command `localstack --no-banner`. - ### How do I resolve connection issues with proxy blocking access to LocalStack's BigData image? A company proxy can lead to connection issues. @@ -626,14 +595,6 @@ If that happens, see [How do I trust my corporate TLS interceptor certificate in Offline images for airgapped environments are available on our enterprise tier, please reach out to our sales team. -### Why does LocalStack startup fail with "Docker not available"? - -The LocalStack CLI cannot reach the Docker daemon. Common fixes: - -- Start Docker Desktop and confirm it's running. -- Verify `docker ps` works as your current user (no `sudo`). -- On macOS, check that `/var/run/docker.sock` is reachable from Docker Desktop. -- If you use Colima, Rancher, or Podman, make sure the `DOCKER_HOST` environment variable points at the correct socket. ### Why does LocalStack fail with "ports are not available: exposing port TCP 127.0.0.1:443"? @@ -699,7 +660,6 @@ Open a ticket by emailing `support@localstack.cloud`. | `LOCALSTACK_REQUESTS_CA_BUNDLE` | Prefixed form of `REQUESTS_CA_BUNDLE` that avoids the CLI auto-forward warning | | `SKIP_SSL_CERT_DOWNLOAD` | `1` to skip the per-org TLS cert download on startup | | `SSL_NO_VERIFY` | `1` to disable outbound TLS verification (debug only) | -| `ACTIVATE_PRO` | `0` to start LocalStack without Pro features (lets the container boot even if license activation fails) | For the full configuration reference, see the [Configuration reference](/aws/customization/configuration-options/) and the broader [Networking documentation](/aws/customization/networking/). diff --git a/src/content/docs/aws/getting-started/index.md b/src/content/docs/aws/getting-started/index.md deleted file mode 100644 index e6bb33555..000000000 --- a/src/content/docs/aws/getting-started/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Overview -description: This section describes how to get started with LocalStack using a variety of options, and provides details on how LocalStack can be configured to fit the needs of a local cloud sandbox for development, testing, and experimentation. -template: doc -editUrl: false -sidebar: - order: 1 ---- - -[LocalStack](https://localstack.cloud) is a cloud service emulator that runs in a single container on your laptop or in your CI environment. -With LocalStack, you can run your AWS applications or Lambdas entirely on your local machine without connecting to a remote cloud provider! - -Whether you are testing complex CDK applications or Terraform configurations, or just beginning to learn about AWS services, LocalStack helps speed up and simplify your testing and development workflow. - -LocalStack supports a growing number of [AWS services](/aws/services/) -, like [Lambda](/aws/services/lambda), [S3](/aws/services/s3), [DynamoDB](/aws/services/dynamodb), [Kinesis](/aws/services/kinesis), [SQS](/aws/services/sqs), [SNS](/aws/services/sns), and more! -[LocalStack for AWS](https://localstack.cloud/pricing) also supports APIs and advanced features to make your cloud development experience a breeze. - -You can find a comprehensive list of supported APIs on each AWS service page. - -LocalStack also provides additional features to make your life as a cloud developer easier! - -Check out LocalStack's [Cloud Developer Tools](/aws/developer-tools/). diff --git a/src/content/docs/aws/getting-started/index.mdx b/src/content/docs/aws/getting-started/index.mdx new file mode 100644 index 000000000..24414b24f --- /dev/null +++ b/src/content/docs/aws/getting-started/index.mdx @@ -0,0 +1,68 @@ +--- +title: Overview +description: Introduction to LocalStack for AWS, covering core use cases, local cloud capabilities, and deployment options for development and testing. +template: doc +editUrl: false +sidebar: + order: 1 +--- + +import { SectionCards } from '../../../../components/SectionCards.tsx'; + +LocalStack provides a cloud service emulator that runs within a single container on your local machine or CI environment. It delivers a functional AWS environment including Lambda, DynamoDB, S3, SQS, and [80+ supported services](/aws/services/), enabling development and testing without an AWS account or cloud-related costs. + +### Core Use Cases + +- **Accelerate development loops**: Test changes against local AWS services instantly to bypass deployment wait times. +- **Automate integration testing**: Execute integration tests against local AWS infrastructure within pull requests to identify regressions before production. +- **Validate IaC**: Deploy Terraform, CDK, or CloudFormation templates to LocalStack to verify infrastructure logic before applying changes to a cloud environment. +- **Experimental sandbox**: Explore new AWS services and architectures in a risk-free environment. + +LocalStack also provides advanced features for team collaboration and security, including [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods/) for state management, [IAM policy enforcement](/aws/developer-tools/security-testing/iam-policy-enforcement/), and [Chaos Engineering](/aws/developer-tools/chaos-engineering/). + +## Start with the basics + + + +:::note +**Enterprise Kubernetes Deployment:** LocalStack also supports execution within Kubernetes clusters via the Operator or Helm charts. This model enables dynamic scaling, environment isolation, and native orchestration. See our [Kubernetes Deployment guide](/aws/customization/kubernetes/) for more information. +::: diff --git a/src/content/docs/aws/getting-started/installation.mdx b/src/content/docs/aws/getting-started/installation.mdx index c5e333e0f..3aceb90be 100644 --- a/src/content/docs/aws/getting-started/installation.mdx +++ b/src/content/docs/aws/getting-started/installation.mdx @@ -1,6 +1,6 @@ --- title: Installation -description: Basic installation guide to get started with LocalStack on your local machine. +description: Install LocalStack with lstk, Docker, Docker Compose, or Helm. template: doc sidebar: order: 2 @@ -9,296 +9,74 @@ sidebar: import { Code, LinkButton, Tabs, TabItem } from '@astrojs/starlight/components'; import { LOCALSTACK_AWS_VERSION } from 'astro:env/server'; -## LocalStack CLI +## Introduction -The quickest way get started with LocalStack is by using the LocalStack CLI. -It allows you to start LocalStack from your command line. -Please make sure that you have a working [Docker installation](https://docs.docker.com/get-docker/) on your machine before moving on. +LocalStack provides multiple installation paths depending on your development environment and requirements. We recommend a CLI-based installation for the most consistent local startup experience. -### Installing LocalStack CLI +Use [`lstk`](#lstk) to install, authenticate, and start LocalStack with minimal setup. -The CLI starts and manages the LocalStack Docker container. -For alternative methods of managing the LocalStack container, see our [alternative installation instructions](#alternatives). +LocalStack for AWS features require an [Auth Token](/aws/getting-started/auth-token/) to activate your running instance. `lstk` handles authentication through a browser-based login flow, while Docker and CI workflows can use `LOCALSTACK_AUTH_TOKEN`. - - - - -You can download the pre-built binary for your architecture using the link below: - - - x86-64 - - - ARM64 - - -or use the curl commands below: - -For x86-64: - - - -For ARM64: - - - -Then extract the LocalStack CLI from the terminal: - - - -
-Alternative: Homebrew on Linux - -If you are using [Homebrew for Linux](https://docs.brew.sh/Homebrew-on-Linux), you can install the LocalStack CLI directly from our official LocalStack tap: - -```bash -brew install localstack/tap/localstack-cli -``` - -
- - - - - -You can install the LocalStack CLI using Brew directly from our official LocalStack tap: - -```bash -brew install localstack/tap/localstack-cli -``` - -
-Alternative: Binary Download - -You may download the binary for your architecture using the link below: - - - Intel (AMD64) - - -or use the following curl command: - - - -Then extract the LocalStack CLI from the terminal: - - +## lstk -
- - - - -You can download the pre-built binary for your architecture using the link below: - - - Intel (AMD64) - - -Then extract the archive and execute the binary in Powershell. - - - - +`lstk` is a lightweight CLI for LocalStack that manages the authentication and container lifecycle in a single workflow. -If you cannot use the binary releases of LocalStack, you can install the Python distribution. +**Requirement:** You must have a working [Docker installation](https://docs.docker.com/get-docker/) before proceeding. -Please make sure to install the following before moving ahead: -- [Python](https://docs.python.org/3/using/index.html) -- [pip](https://pip.pypa.io/en/stable/installation/) +### Install lstk -Next install the LocalStack CLI in your Python environment by running: - -```bash -python3 -m pip install --upgrade localstack -``` - -:::note -To download a specific version of LocalStack, replace `` with the required version from [changelog page](/aws/changelog). - -```bash -python3 -m pip install localstack== -``` - -::: - -:::tip[MacOS Sierra?] -If you have problems with permissions in MacOS X Sierra, install with: - -```bash -python3 -m pip install --user localstack -``` - -::: - -:::danger -Do not use `sudo` or the `root` user when starting LocalStack. -It should be installed and started entirely under a local non-root user. -::: - - + + + ```bash + brew install localstack/tap/lstk + ``` + + + ```bash + npm install -g @localstack/lstk + ``` + + + Download the binary for your platform from the [GitHub Releases](https://github.com/localstack/lstk/releases) and add it to your `PATH`. + -### Starting LocalStack - -To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal: - - - -You are all set! - -:::note -To start LocalStack, you must first [set up your auth token](/aws/getting-started/auth-token). -::: - -Once you've set up your auth token, you can start LocalStack with the following command: +### Start lstk ```bash -localstack start # start localstack in background with -d flag +lstk start ``` -{/* prettier-ignore */} - - -### Updating LocalStack CLI - -The LocalStack CLI allows you to easily update the different components of LocalStack. -To check the various options available for updating, run: +The first execution initiates a browser-based login flow. Subsequent starts use credentials stored in your system keyring. -```bash -localstack update --help -``` +### Update lstk ```bash -Usage: localstack update [OPTIONS] COMMAND [ARGS]... - - Update different LocalStack components. - -Options: - -h, --help Show this message and exit. - -Commands: - all Update all LocalStack components - docker-images Update docker images LocalStack depends on - localstack-cli Update LocalStack CLI +lstk update ``` -:::note -Updating the LocalStack CLI using `localstack update localstack-cli` and `localstack update all` will work only if it was installed from the Python distribution. -If it was installed using the pre-built binary or via Brew, please run the installation steps again to update to the latest version. -::: - -## Alternatives - -Besides using the CLI, there are other ways of starting and managing your LocalStack instance: - -- [LocalStack Desktop](#localstack-desktop)\ - Get a desktop experience and work with your local LocalStack instance via the UI. - -- [LocalStack Docker Extension](#localstack-docker-extension)\ - Use the LocalStack extension for Docker Desktop to work with your LocalStack instance. +For more details, see the [lstk documentation](/aws/developer-tools/running-localstack/lstk/). -- [Docker-Compose](#docker-compose)\ - Use Docker Compose to configure and start your LocalStack Docker container. +## Container and orchestration tools -- [Docker](#docker)\ - Use the Docker CLI to manually start the LocalStack Docker container. +Use these methods when you need explicit container configuration, want to run LocalStack alongside other services, or deploy LocalStack in CI and Kubernetes environments. +For everyday local development, `lstk` is usually simpler. -- [LocalStack Operator](#localstack-operator)\ - Use the LocalStack Operator to deploy and manage LocalStack instances inside a Kubernetes cluster. +### Docker Compose -LocalStack runs inside a Docker container, and the above options are different ways to start and manage the LocalStack Docker container. +Use Docker Compose when you want a reusable configuration file that can be shared across a team or checked into a project repository. +Create a `docker-compose.yml` with the following configuration: -The LocalStack emulator is available on Docker Hub (`localstack/localstack-pro`). - -For a comprehensive overview of the LocalStack images, check out our [Docker images documentation](/aws/customization/other-installations/docker-images). - -### LocalStack Desktop - -Learn more about our desktop client at [LocalStack Desktop](/aws/developer-tools/running-localstack/localstack-desktop) and download it [here](https://app.localstack.cloud/download). - -### LocalStack Docker Extension - -Install our [official Docker Desktop extension](https://hub.docker.com/extensions/localstack/localstack-docker-desktop) to manage LocalStack. -See [LocalStack Docker Extension](/aws/customization/other-installations/localstack-docker-extension) for more information. - -### Docker-Compose - -To use LocalStack without the [LocalStack CLI](#localstack-cli), you have the option of running the LocalStack Docker container by yourself. -If you want to manually manage your Docker container, it's usually a good idea to use [Docker Compose](https://docs.docker.com/compose/reference/) in order to simplify your container configuration. - -#### Prerequisites - -- [Docker](https://docs.docker.com/get-docker/) -- [Docker Compose](https://docs.docker.com/compose/install/) (version 1.9.0+) - -#### Starting LocalStack with Docker-Compose - -You can start LocalStack with [Docker Compose](https://docs.docker.com/compose/) by configuring a `docker-compose.yml` file. -Docker Compose v1.9.0 and above is supported. - -```yaml showshowLineNumbers +```yaml showLineNumbers services: localstack: container_name: '${LOCALSTACK_DOCKER_NAME:-localstack-main}' - image: localstack/localstack-pro # required for Pro + image: localstack/localstack ports: - '127.0.0.1:4566:4566' # LocalStack Gateway - '127.0.0.1:4510-4559:4510-4559' # external services port range - - '127.0.0.1:443:443' # LocalStack HTTPS Gateway (Pro) + - '127.0.0.1:443:443' # LocalStack HTTPS Gateway environment: # Activate LocalStack for AWS: https://docs.localstack.cloud/getting-started/auth-token/ - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} # required for Pro @@ -310,55 +88,11 @@ services: - '/var/run/docker.sock:/var/run/docker.sock' ``` -Start the container by running the following command: +Execute `docker compose up` to start. -```bash -docker compose up -``` +### Docker CLI -:::note - -- This command pulls the current nightly build from the `main` branch (if you don't have the image locally) and **not** the latest supported version. - If you want to use a specific version, set the appropriate LocalStack image tag at `services.localstack.image` in the `docker-compose.yml` file (for example `localstack/localstack:`). - -- If you are using LocalStack with an [Auth Token](/aws/getting-started/auth-token), you need to specify the image tag as `localstack/localstack-pro` in the `docker-compose.yml` file. - Going forward, `localstack/localstack-pro` image will contain our Pro-supported services and APIs. - -- This command reuses the image if it's already on your machine, i.e. it will **not** pull the latest image automatically from Docker Hub. - -- Mounting the Docker socket `/var/run/docker.sock` as a volume is required for some services that use Docker to provide the emulation, such as AWS Lambda. - Check out the [Lambda providers](/aws/services/lambda) documentation for more information. - -- To facilitate interoperability, configuration variables can be prefixed with `LOCALSTACK_` in docker. - For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`. - -- If using the Docker default bridge network using `network_mode: bridge`, container name resolution will not work inside your containers. - Please consider removing it, if this functionality is needed. - -- To configure an Auth Token, refer to the [Auth Token](/aws/getting-started/auth-token) documentation. - ::: - -Please note that there are a few pitfalls when configuring your stack manually via docker-compose (e.g., required container name, Docker network, volume mounts, and environment variables). -We recommend using the LocalStack CLI to validate your configuration, which will print warning messages in case it detects any potential misconfigurations: - -```bash -localstack config validate -``` - -### Docker - -You can also directly start the LocalStack container using the Docker CLI instead of [Docker-Compose](#docker-compose). -This method requires more manual steps and configuration, but it gives you more control over the container settings. - -#### Prerequisites - -Please make sure that you have a working [Docker installation](https://docs.docker.com/get-docker/) on your machine before moving on. -You can check if Docker is correctly configured on your machine by executing `docker info` in your terminal. -If it does not report an error (but shows information on your Docker system), you're good to go. - -#### Starting LocalStack with Docker - -You can start the Docker container simply by executing the following `docker run` command: +Use the Docker CLI for one-off starts or when you want to test a container configuration before moving it into Compose: ```bash docker run \ @@ -368,50 +102,39 @@ docker run \ -p 127.0.0.1:443:443 \ -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ -v /var/run/docker.sock:/var/run/docker.sock \ - localstack/localstack-pro + localstack/localstack ``` :::note +The Docker Compose and Docker CLI examples above use the same runtime settings: -- This command pulls the current nightly build from the `main` branch (if you don't have the image locally) and **not** the latest supported version. - If you want to use a specific version of LocalStack, use the appropriate tag: `docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack:`. - Check-out the [changelog page](/aws/changelog) to know more about specific LocalStack versions. - -- If you are using LocalStack with an [Auth Token](/aws/getting-started/auth-token), you need to specify the image tag as `localstack/localstack-pro` in your Docker setup. - Going forward, `localstack/localstack-pro` image will contain our Pro-supported services and APIs. +- The `4566` port exposes the LocalStack Gateway. +- The `4510-4559` range exposes external service ports used by services that bind additional endpoints. +- The `443` port exposes the LocalStack HTTPS Gateway. +- The Docker socket mount is required for services that start additional containers, such as Lambda. +- Docker reuses a local image if one already exists. Pull explicitly or pin an image tag, such as `localstack/localstack:`, when you need reproducible CI or team environments. +- If you use Docker bridge networking, container name resolution may not work as expected from other containers. Prefer the default LocalStack networking setup unless you have a specific reason to customize it. +- Configuration variables can be prefixed with `LOCALSTACK_` in Docker. For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`. -- This command reuses the image if it's already on your machine, i.e. it will **not** pull the latest image automatically from Docker Hub. - -- Mounting the Docker socket `/var/run/docker.sock` as a volume is required for some services that use Docker to provide the emulation, such as AWS Lambda. - Check out the [Lambda providers](/aws/services/lambda) documentation for more information. - -- When using Docker to manually start LocalStack, you will have to configure the container on your own (see [docker-compose-pro.yml](https://github.com/localstack/localstack/blob/main/docker-compose-pro.yml) and [Configuration](/aws/customization/configuration-options). - This could be seen as the "expert mode" of starting LocalStack. - If you are looking for a simpler method of starting LocalStack, please use the [LocalStack CLI](#localstack-cli). +For more details, see the [Docker images](/aws/customization/other-installations/docker-images/), [configuration](/aws/customization/configuration-options/), and [networking](/aws/customization/networking/) documentation. +::: -- To facilitate interoperability, configuration variables can be prefixed with `LOCALSTACK_` in docker. - For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`. +### Helm (Kubernetes) -- To configure an Auth Token, refer to the [Auth Token](/aws/getting-started/auth-token) documentation. - ::: +Deploy LocalStack to a Kubernetes cluster: -### LocalStack Operator +```bash +helm repo add localstack-repo https://helm.localstack.cloud +helm upgrade --install localstack localstack-repo/localstack +``` -If you want to deploy LocalStack in your [Kubernetes](https://kubernetes.io) cluster, you can use the [LocalStack Operator](/aws/customization/kubernetes/kubernetes-operator). +## Graphical user interfaces (GUIs) -## What's next? +### LocalStack Desktop -Now that you have LocalStack up and running, the following resources might be useful for your next steps: +Manage local instances via a standalone desktop application. [Download here](https://app.localstack.cloud/download). -- Check out our [Quickstart guide](/aws/getting-started/quickstart) if you are a new user to get started with LocalStack quickly. -- [Use the LocalStack integrations](/aws/customization/integrations) to interact with LocalStack and other integrated tools, for example: - - Use `awslocal` to use the AWS CLI against your local cloud! - - Use the Serverless Framework with LocalStack! - - And many more! -- [Find out how to configure LocalStack](/aws/customization/configuration-options) such that it perfectly fits your need. -- [Use LocalStack in your CI environment](/aws/ci-pipelines/) to increase your code quality. -- [Checkout LocalStack's Cloud Developer Tools](/aws/developer-tools/) to further increase your development efficiency with LocalStack. -- Find out about the ways you can [configure LocalStack](/aws/customization/configuration-options). +Install the [official extension](https://hub.docker.com/extensions/localstack/localstack-docker-desktop) to manage LocalStack directly from the Docker Desktop. ## Troubleshooting @@ -446,9 +169,13 @@ DNS_ADDRESS=0 localstack start You can now avail logging output and error reporting using LocalStack logs. To access the logs, run the following command: + + ```bash -localstack logs +lstk logs ``` + + AWS requests are now logged uniformly in the INFO log level (set by default or when `DEBUG=0`). The format is: @@ -483,3 +210,7 @@ After running the task, run the diagnostic endpoint and share the archive file w We have extensive network troubleshooting documentation available [here](/aws/customization/networking/). If this does not solve your problem then please [reach out to LocalStack Support](/aws/help-support/get-help/). + +## Next steps + +Now that you've completed installation, proceed to the [Auth Token guide](/aws/getting-started/auth-token/) to activate LocalStack and prepare your environment for local development. diff --git a/src/content/docs/aws/getting-started/local-development.mdx b/src/content/docs/aws/getting-started/local-development.mdx new file mode 100644 index 000000000..7b490037c --- /dev/null +++ b/src/content/docs/aws/getting-started/local-development.mdx @@ -0,0 +1,285 @@ +--- +title: Local Development +description: Deploy an AWS serverless API locally using Lambda and DynamoDB on LocalStack. +template: doc +sidebar: + order: 3 +--- + +import { Code, Tabs, TabItem, Steps } from '@astrojs/starlight/components'; +import { LOCALSTACK_AWS_VERSION } from 'astro:env/server'; + +## Introduction + +This guide walks you through starting LocalStack and deploying a serverless API consisting of a Lambda function and a DynamoDB table. You will perform the entire deployment on your local machine without an AWS account. + +A successful deployment results in a: + +- **Serverless API:** A Lambda function with a configured function URL. +- **Persistence Layer:** A DynamoDB table for message storage. +- **Local Cloud Environment:** A fully functional local sandbox that emulates AWS services. + +Choose your preferred deployment method: **Terraform** or **AWS CLI**. + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) engine installed and running. +- A [LocalStack account](https://app.localstack.cloud/sign-up) and a valid [LocalStack Auth Token](/aws/getting-started/auth-token/). +- Either [Terraform CLI](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) or [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed, depending on your preferred deployment method. + +If you haven't installed LocalStack yet, follow the [installation guide](/aws/getting-started/installation/) to get started. + +## Step 1: Install and start LocalStack + +Start LocalStack: + +```bash +lstk start +``` + +The first run triggers a browser-based authentication flow. After authentication, the CLI pulls the LocalStack image and initializes the container. + +When the container is ready, you will see the following logs: + +```text +✔︎ LocalStack ready (containerId: 400b3e61f3c6) +• Endpoint: localhost.localstack.cloud:4566 +• Web app: https://app.localstack.cloud +``` + +## Step 2: Deploy the serverless API + +You can deploy the Lambda function and DynamoDB table using either our AWS CLI wrapper `lstk aws` or our Terraform wrapper `tflocal`. +These tools automatically route AWS API calls to your LocalStack container, so you do not need AWS account credentials for this guide. + + + + + + 1. Create the Lambda function source. Execute the following to create a project directory, a function file and a Python handler: + + ```bash + mkdir -p /tmp/localstack-demo + cat > /tmp/localstack-demo/handler.py << 'EOF' + import json, boto3, os, uuid + + def handler(event, context): + table = boto3.resource('dynamodb').Table(os.environ['TABLE_NAME']) + method = event.get('requestContext', {}).get('http', {}).get('method', 'GET') + # Function URL POST, or direct invoke (e.g. Resource Browser) with a message + if method == 'POST' or 'message' in event: + data = json.loads(event.get('body', '{}')) if method == 'POST' else event + item = {'id': str(uuid.uuid4()), **data} + table.put_item(Item=item) + return {'statusCode': 200, 'body': json.dumps(item)} + result = table.scan() + return {'statusCode': 200, 'body': json.dumps(result['Items'])} + EOF + cd /tmp/localstack-demo && zip handler.zip handler.py + ``` + + 2. Create the DynamoDB table: + + ```bash + lstk aws dynamodb create-table \ + --table-name Messages \ + --attribute-definitions AttributeName=id,AttributeType=S \ + --key-schema AttributeName=id,KeyType=HASH \ + --billing-mode PAY_PER_REQUEST + ``` + + 3. Deploy the Lambda function: + + ```bash + lstk aws lambda create-function \ + --function-name messages-api \ + --runtime python3.12 \ + --handler handler.handler \ + --zip-file fileb:///tmp/localstack-demo/handler.zip \ + --role arn:aws:iam::000000000000:role/lambda-role \ + --environment Variables={TABLE_NAME=Messages} + + lstk aws lambda wait function-active --function-name messages-api + ``` + + 4. Configure a function URL and retrieve the endpoint: + + ```bash + lstk aws lambda create-function-url-config \ + --function-name messages-api \ + --auth-type NONE + + LAMBDA_URL=$(lstk aws lambda list-function-url-configs \ + --function-name messages-api \ + --query 'FunctionUrlConfigs[0].FunctionUrl' \ + --output text) + echo $LAMBDA_URL + ``` + + + + + + + + 1. Create a project directory and a `main.tf` file: + + ```bash + mkdir -p /tmp/localstack-demo + cat > /tmp/localstack-demo/main.tf << 'TF' + terraform { + required_providers { + aws = { source = "hashicorp/aws" } + archive = { source = "hashicorp/archive" } + } + } + + resource "aws_dynamodb_table" "messages" { + name = "Messages" + billing_mode = "PAY_PER_REQUEST" + hash_key = "id" + attribute { + name = "id" + type = "S" + } + } + + data "archive_file" "lambda" { + type = "zip" + output_path = "${path.module}/handler.zip" + source { + filename = "handler.py" + content = <<-EOF + import json, boto3, os, uuid + def handler(event, context): + table = boto3.resource('dynamodb').Table(os.environ['TABLE_NAME']) + method = event.get('requestContext', {}).get('http', {}).get('method', 'GET') + # Function URL POST, or direct invoke (e.g. Resource Browser) with a message + if method == 'POST' or 'message' in event: + data = json.loads(event.get('body', '{}')) if method == 'POST' else event + item = {'id': str(uuid.uuid4()), **data} + table.put_item(Item=item) + return {'statusCode': 200, 'body': json.dumps(item)} + result = table.scan() + return {'statusCode': 200, 'body': json.dumps(result['Items'])} + EOF + } + } + + resource "aws_iam_role" "lambda_role" { + name = "lambda-role" + assume_role_policy = jsonencode({ + Version = "2012-10-17" + Statement = [{ Action = "sts:AssumeRole", Effect = "Allow", + Principal = { Service = "lambda.amazonaws.com" } }] + }) + } + + resource "aws_lambda_function" "messages_api" { + function_name = "messages-api" + runtime = "python3.12" + handler = "handler.handler" + filename = data.archive_file.lambda.output_path + source_code_hash = data.archive_file.lambda.output_base64sha256 + role = aws_iam_role.lambda_role.arn + environment { + variables = { TABLE_NAME = aws_dynamodb_table.messages.name } + } + } + + resource "aws_lambda_function_url" "messages_api" { + function_name = aws_lambda_function.messages_api.function_name + authorization_type = "NONE" + } + + output "function_url" { + value = aws_lambda_function_url.messages_api.function_url + } + TF + cd /tmp/localstack-demo + ``` + + 2. Initialize and apply the configuration: + + ```bash + lstk terraform init && lstk terraform apply -auto-approve + ``` + + 3. Retrieve the endpoint: + + ```bash + LAMBDA_URL=$(lstk terraform output -raw function_url) + echo $LAMBDA_URL + ``` + + + + + +## Step 3: Test the API + +Send a POST request to store a message in the locally emulated DynamoDB table: + +```bash +curl -X POST "$LAMBDA_URL" \ + -H "Content-Type: application/json" \ + -d '{"message": "Hello, LocalStack!"}' +``` + +You will get back a response: + +```json title="Output" +{ + "id": "3e1b5cae-4386-447b-8567-f0615fdb0fff", + "message": "Hello, LocalStack!" +} +``` + +Retrieve all your messages: + +```bash +curl "$LAMBDA_URL" +``` + +The Lambda function executes within the local environment and interacts with the locally emulated DynamoDB service. +Because no actual cloud resources are created, you won't incur any real AWS cloud costs or infrastructure changes. + +## Step 4: Inspect resources + +View the state of your local infrastructure via the [LocalStack Web Application](https://app.localstack.cloud/). +Navigate to the [Stack Overview](https://app.localstack.cloud/inst/default/overview) to inspect your running resources, which are the Lambda function and DynamoDB table you just deployed. You can expand each service to see the details of the deployed resources. +![Inspect Resources using LocalStack Web Application](/images/aws/stack-overview.jpg) + +## Step 5 (Optional): `Application Inspection & Tracing` Quickstart + +There's a lot more you can do with LocalStack than just emulate AWS services. To learn more about how LocalStack can help you inspect, manage, snapshot, and debug your AWS project, check out the [**Application Inspection & Tracing** quickstart](/aws/quickstart-library/application-inspection-tracing/) to continue this tutorial (Make sure to **skip Step 6**, the cleanup step, below). + +## Step 6: Clean up + +Stop your LocalStack container to remove all emulated resources. LocalStack is ephemeral by default; stopping the instance clears the state. + +{/* prettier-ignore-start */} + + + + ```bash + lstk stop + ``` + + + + +{/* prettier-ignore-end */} + +To persist resource state, like S3 buckets or DynamoDB tables, across restarts, check out our [state management tools](/aws/capabilities/state-management/). + +Remove the local files you created in this guide: + +```bash +rm -rf /tmp/localstack-demo +``` + +## Next steps + +You have successfully deployed and tested a serverless API on your local workstation. +Proceed to the [CI/CD guide](/aws/getting-started/ci-cd/) to learn how to integrate LocalStack into your automated continuous integration (CI) pipelines across a wide range of providers and platforms. diff --git a/src/content/docs/aws/getting-started/quickstart.mdx b/src/content/docs/aws/getting-started/quickstart.mdx deleted file mode 100644 index d512d8bfb..000000000 --- a/src/content/docs/aws/getting-started/quickstart.mdx +++ /dev/null @@ -1,364 +0,0 @@ ---- -title: Quickstart -description: How to run an AWS application on your local machine and test local cloud development with LocalStack. -template: doc -sidebar: - order: 4 ---- -import { Code, LinkButton, Tabs, TabItem } from '@astrojs/starlight/components'; - -## Introduction - -In this quickstart guide, we'll walk you through the process of starting LocalStack on your local machine and deploying a [serverless image resizer application](https://github.com/localstack-samples/sample-serverless-image-resizer-s3-lambda) that utilizes several AWS services. -This guide aims to help you understand how to use LocalStack for the development and testing of your AWS applications locally. -It introduces you to the following key concepts: - -- Starting a LocalStack instance on your local machine. -- Deploying an AWS serverless application infrastructure locally. -- Running an automated integration test suite against local infrastructure. -- Exploring the LocalStack Web Application to view deployed resources. -- Destroying the local infrastructure you have provisioned. - -## Architecture - -The following diagram shows the architecture that we will deploy locally using LocalStack: - -![An AWS architecture demonstrating a sample serverless image resizer application](https://user-images.githubusercontent.com/3996682/229322761-92f52eec-5bfb-412a-a3cb-8af4ee1fed24.png) - -The architecture: - -- Configures S3 bucket notifications to invoke a Lambda function. -- Provides S3 pre-signed POST URLs for direct uploads to the S3 bucket. -- Creates S3 website hosting for serving the static application client. -- Configures direct invocation URLs for Lambda functions accessible to the client. -- Establishes Lambda SNS to SNS topic notifications for failure handling. -- Creates SNS to SES subscriptions for email notifications triggered by specific events. - -An internal SES LocalStack testing endpoint (`/_localstack/aws/ses`) is configured as well, to test email sending functionality while running our local integration test suite. - -## Prerequisites - -- [LocalStack CLI](/aws/getting-started/installation/#installing-localstack-cli) -- [LocalStack account](https://www.localstack.cloud/pricing) & [Auth Token](/aws/getting-started/auth-token/) -- [Docker](https://docs.docker.com/get-docker/) -- [Python 3.11+](https://www.python.org/downloads/) & `pip` -- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) & [`awslocal` wrapper](/aws/connecting/aws-cli/#localstack-aws-cli-awslocal) -- `jq`, `zip` & `curl` - -You can start LocalStack using the `localstack` CLI. -Start the LocalStack for AWS container with your `LOCALSTACK_AUTH_TOKEN` pre-configured: - - - - \nlocalstack start`} lang="shell" /> - - - \nlocalstack start`} lang="shell" /> - - - -If you prefer running LocalStack in detached mode, you can add the `-d` flag to the `localstack start` command, and use Docker Desktop to view the logs. - -## Instructions - -To get started, clone the sample application repository from GitHub: - -```bash -git clone https://github.com/localstack-samples/sample-serverless-image-resizer-s3-lambda.git -cd sample-serverless-image-resizer-s3-lambda -``` - -You can now follow the instructions below to start LocalStack, deploy the sample application, and test the application. - -### Setup a virtual environment - -To deploy the sample application, you need to have specific Python packages are installed. -It is advisable to utilize a virtual environment for the installation process, allowing the packages to be installed in an isolated environment. -Execute the following commands to create a virtual environment and install the packages in `requirements-dev.txt`: - - - - ```shell - python -m venv .venv - source .venv/bin/activate - pip install -r requirements-dev.txt - ``` - - - ```shell - python -m venv .venv - .venv\Scripts\activate - pip install -r requirements-dev.txt - ``` - - - -:::tip -If you are encountering issues with the installation of the packages, such as Pillow, ensure you use the same version as the Python Lambdas (3.11.6) for Pillow to work. -If you're using pyenv, install and activate Python 3.11 with the following commands: -```bash -pyenv install 3.11 -pyenv global 3.11 -``` -::: - -### Setup the serverless image resizer - -This application enables serverless image resizing using [S3](/aws/services/s3/), [SSM](/aws/services/ssm/), [Lambda](/aws/services/lambda/), [SNS](/aws/services/sns/), and [SES](/aws/services/ses/). -A simple web interface allows users to upload and view resized images. -A Lambda function generates S3 pre-signed URLs for direct uploads, while S3 bucket notifications trigger image resizing. -Another Lambda function lists and provides pre-signed URLs for browser display. -The application also handles Lambda failures through SNS and SES email notifications. - -The sample application uses AWS CLI and our `awslocal` wrapper to deploy the application to LocalStack. -Before going further, you need to build your Lambda functions. -You can use the following script that will cover all three of them: - -```bash -deployment/build-lambdas.sh -``` - -You can now deploy the sample application on LocalStack by running the following command: - -```bash -deployment/awslocal/deploy.sh -``` - -Alternatively, you can follow these instructions to deploy the sample application manually step-by-step. - -:::tip -In absence of the `awslocal` wrapper, you can use the `aws` CLI directly, by configuring an [endpoint URL](/aws/connecting/aws-cli/#configuring-an-endpoint-url) or a [custom profile](/aws/connecting/aws-cli/#configuring-a-custom-profile) like `localstack`. -You can then swap `awslocal` with `aws --endpoint-url=http://localhost:4566` or `aws --profile=localstack` in the commands below. -::: - -#### Create the S3 buckets - -```bash -awslocal s3 mb s3://localstack-thumbnails-app-images -awslocal s3 mb s3://localstack-thumbnails-app-resized -``` - -#### Add bucket names into the parameter store - -```bash -awslocal ssm put-parameter \ - --name /localstack-thumbnail-app/buckets/images \ - --type "String" \ - --value "localstack-thumbnails-app-images" -awslocal ssm put-parameter \ - --name /localstack-thumbnail-app/buckets/resized \ - --type "String" \ - --value "localstack-thumbnails-app-resized" -``` - -#### Create SNS DLQ Topic for failed lambda invocations - -```bash -awslocal sns create-topic --name failed-resize-topic -``` - -To receive immediate alerts in case of image resize failures, subscribe an email address to the system. -You can use the following command to subscribe an email address to the SNS topic: - -```bash -awslocal sns subscribe \ - --topic-arn arn:aws:sns:us-east-1:000000000000:failed-resize-topic \ - --protocol email \ - --notification-endpoint my-email@example.com -``` - -#### Create the Presign Lambda - -```bash showshowLineNumbers -(cd lambdas/presign; rm -f lambda.zip; zip lambda.zip handler.py) -awslocal lambda create-function \ - --function-name presign \ - --runtime python3.11 \ - --timeout 10 \ - --zip-file fileb://lambdas/presign/lambda.zip \ - --handler handler.handler \ - --role arn:aws:iam::000000000000:role/lambda-role \ - --environment Variables="{STAGE=local}" -awslocal lambda wait function-active-v2 --function-name presign -awslocal lambda create-function-url-config \ - --function-name presign \ - --auth-type NONE -``` - -#### Create the Image List Lambda - -```bash showshowLineNumbers -(cd lambdas/list; rm -f lambda.zip; zip lambda.zip handler.py) -awslocal lambda create-function \ - --function-name list \ - --handler handler.handler \ - --zip-file fileb://lambdas/list/lambda.zip \ - --runtime python3.11 \ - --timeout 10 \ - --role arn:aws:iam::000000000000:role/lambda-role \ - --environment Variables="{STAGE=local}" -awslocal lambda wait function-active-v2 --function-name list -awslocal lambda create-function-url-config \ - --function-name list \ - --auth-type NONE -``` - -#### Build the Image Resizer Lambda - - - - ```bash showshowLineNumbers - cd lambdas/resize - rm -rf libs lambda.zip - docker run --platform linux/x86_64 -v "$PWD":/var/task "public.ecr.aws/sam/build-python3.11" /bin/sh -c "pip install -r requirements.txt -t libs; exit" - cd libs && zip -r ../lambda.zip . && cd .. - zip lambda.zip handler.py - rm -rf libs - cd ../.. - ``` - - - ```bash showshowLineNumbers - cd lambdas/resize - rm -rf package lambda.zip - mkdir package - pip install -r requirements.txt -t package --platform manylinux_2_28_x86_64 --python-version 3.11 --no-deps - zip lambda.zip handler.py - cd package - zip -r ../lambda.zip *; - cd ../.. - ``` - - - ```bash showshowLineNumbers - cd lambdas/resize - rm -rf package lambda.zip - mkdir package - pip install -r requirements.txt -t package - zip lambda.zip handler.py - cd package - zip -r ../lambda.zip\_; - cd ../.. - ``` - - - -#### Create the Image Resizer Lambda - -```bash showshowLineNumbers -awslocal lambda create-function \ - --function-name resize \ - --runtime python3.11 \ - --timeout 10 \ - --zip-file fileb://lambdas/resize/lambda.zip \ - --handler handler.handler \ - --dead-letter-config TargetArn=arn:aws:sns:us-east-1:000000000000:failed-resize-topic \ - --role arn:aws:iam::000000000000:role/lambda-role \ - --environment Variables="{STAGE=local}" -awslocal lambda wait function-active-v2 --function-name resize -awslocal lambda put-function-event-invoke-config \ - --function-name resize \ - --maximum-event-age-in-seconds 3600 \ - --maximum-retry-attempts 0 -``` - -#### Connect S3 bucket to Resizer Lambda - -```bash -awslocal s3api put-bucket-notification-configuration \ - --bucket localstack-thumbnails-app-images \ - --notification-configuration "{\"LambdaFunctionConfigurations\": [{\"LambdaFunctionArn\": \"$(awslocal lambda get-function --function-name resize --output json | jq -r .Configuration.FunctionArn)\", \"Events\": [\"s3:ObjectCreated:*\"]}]}" -``` - -#### Create the S3 static website - -```bash -awslocal s3 mb s3://webapp -awslocal s3 sync --delete ./website s3://webapp -awslocal s3 website s3://webapp --index-document index.html -``` - -#### Retrieve the Lambda Function URLs - -Retrieve the Lambda function URLs for the `presign` and `list` Lambda functions using the following commands: - -```bash -awslocal lambda list-function-url-configs --function-name presign --output json | jq -r '.FunctionUrlConfigs[0].FunctionUrl' -awslocal lambda list-function-url-configs --function-name list --output json | jq -r '.FunctionUrlConfigs[0].FunctionUrl' -``` - -Save these URLs for later use in the sample application. - -### Run the sample AWS application - -To access the application, go to [**https://webapp.s3-website.localhost.localstack.cloud:4566**](https://webapp.s3-website.localhost.localstack.cloud:4566) in your browser. - -![Serverless image resizer application](/images/aws/serverless-image-resizer-application.png) - -Paste the `presign` and `list` Lambda function URLs into the application and click **Apply**. -Alternatively, click on **Load from API** to automatically load the URLs. - -Upload an image, and click **Upload**. -The upload form uses the `presign` Lambda to request an S3 pre-signed POST URL, forwarding the POST request to S3. -Asynchronous resizing (maximum 400x400 pixels) occurs through S3 bucket notifications. - -If successful, the application displays a **success!** alert. -Click **Refresh** to trigger your browser to request the `list` Lambda URL, returning a JSON document of all items in the images (`localstack-thumbnails-app-images`) and resized images (`localstack-thumbnails-app-resized`) bucket. - -![Serverless image resizer application displaying a resized image](/images/aws/resized-image-sample-application.png) - -### View the deployed resources - -You can inspect the resources deployed as part of the sample application by accessing the [**LocalStack Web Application**](https://app.localstack.cloud/). -Navigate to your [**Default Instance**](https://app.localstack.cloud/inst/default/status) to view the deployed resources. - -![Status Page of the LocalStack Web Application"](/images/aws/localstack-web-application-status.png) - -Click on [S3](https://app.localstack.cloud/inst/default/resources/s3) or [Lambda](https://app.localstack.cloud/inst/default/resources/lambda/functions) to view the S3 buckets and Lambda functions respectively. - -![The Lambda Resource Browser Page of the LocalStack Web Application](/images/aws/localstack-web-application-lambda.png) - -### Run integration tests - -To run automated integration tests against the sample application, use the following command: - -```bash -pytest -v -``` - -Additionally, you can verify that when the `resize` Lambda fails, an SNS message is sent to a topic that an SES subscription listens to, triggering an email with the raw failure message. -Since there's no real email server involved, you can use the LocalStack SES developer endpoint to list messages sent via SES: - -```bash -curl -s http://localhost.localstack.cloud:4566/_aws/ses | jq -``` - -An alternative option is to use a service like MailHog or `smtp4dev`. -Start LocalStack with `SMTP_HOST=host.docker.internal:1025`, pointing to the mock SMTP server. - -### Destroy the local infrastructure - -Now that you've learned how to deploy a local AWS infrastructure for your sample application, let's clean up and tear down the resources associated with the project: - -```bash -localstack stop -``` - -LocalStack is ephemeral, meaning it doesn't persist any data across restarts. -It runs inside a Docker container, and once it's stopped, all locally created resources are automatically removed. - -To persist the local cloud resources across restarts, navigate to our [persistence documentation](/aws/developer-tools/snapshots/persistence) or learn about [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods), our next generation state management utility. - -## Next Steps - -Congratulations on deploying an AWS application locally using LocalStack! -To expand your LocalStack capabilities, explore the following based on your expertise: - -- [Tutorials](/aws/tutorials): Check out our tutorials to learn how to use LocalStack across various AWS services and application stacks. -- [Supported Services](/aws/services): Explore LocalStack's emulated AWS services. -- [Connecting](/aws/connecting/): Connect to LocalStack from the AWS CLI, SDKs, IaC tools, IDEs, and the web Console. -- [Developer Tools](/aws/developer-tools/): Use LocalStack's tooling, including App Inspector, Cloud Pods, Chaos Engineering, and the Lambda developer tools. -- [CI Pipelines](/aws/ci-pipelines/): Run LocalStack in your CI pipelines for automated integration testing. -- [Customization](/aws/customization/): Customize how LocalStack behaves, from configuration options and Kubernetes to third-party integrations. -- [Organizations & Admin](/aws/organizations-admin/): Manage accounts, workspaces, users, licenses, and single sign-on for your team. -- [Blog](https://blog.localstack.cloud): Read our blog posts about LocalStack and the latest enhancements for a better local development and testing experience. diff --git a/src/content/docs/aws/quickstart-library/application-inspection-tracing.mdx b/src/content/docs/aws/quickstart-library/application-inspection-tracing.mdx new file mode 100644 index 000000000..127c5c8a6 --- /dev/null +++ b/src/content/docs/aws/quickstart-library/application-inspection-tracing.mdx @@ -0,0 +1,244 @@ +--- +title: App Inspection & Tracing +description: This Quickstart uses the LocalStack Web Application to inspect, browse, snapshot, and trace a deployed serverless API. +template: doc +sidebar: + order: 2 +--- + +import { Steps } from '@astrojs/starlight/components'; + +## Introduction + +This quickstart picks up where the **Getting Started** guide left off and introduces the **LocalStack Web Application**, which you can leverage to inspect, manage, snapshot, and debug your LocalStack instance. + +In the [Getting Started](/aws/getting-started/local-development/), you deployed a Lambda function and a DynamoDB table entirely from the command line. We will be using that exact deployment for this quickstart. + +Now, you're going to step away from the terminal and use the web application to visually inspect, browse, snapshot, and trace that serverless API. + +Specifically, you will use the [LocalStack Web Application](https://app.localstack.cloud/) to: + +1. **Confirm** your local instance is running and find it in the browser. +2. **Get a visual summary** of your deployed resources with **Stack Overview**. +3. **Trigger** your Lambda function and browse the resulting DynamoDB rows with the **Resource Browser**. +4. **Snapshot** the entire application state, wipe it, and bring it back with **Cloud Pods**. +5. **Trace** the request flow between your Lambda function and DynamoDB table with **App Inspector**. + +## Prerequisites + +- Complete the [Getting Started's 'Local Development' section](/aws/getting-started/local-development/), but **skip Step 6**. You don't want to run run the cleanup step because your `messages-api` Lambda function and `Messages` DynamoDB table should still be deployed. +- The LocalStack container from the Getting Started must still be running. If you closed your terminal, the container keeps running in the background. Verify by running: + + ```bash + lstk status + ``` + + If it reports that the AWS emulator is not running, start it again with `lstk start`. Since LocalStack is ephemeral by default, this gives you a fresh, empty instance. Redeploy the Lambda function and DynamoDB table from the Getting Started before continuing. + +- Sign in to the [LocalStack Web Application](https://app.localstack.cloud/). + +## Step by Step + +### Step 1: Find your running instance + +Before opening the browser, confirm LocalStack is actually up and check what it currently has deployed: + +```bash +lstk status +``` + +```text title="Output" +LocalStack AWS Emulator is running +• Endpoint: localhost:4566 +• Container: localstack-main +• Version: 4.9.1 +• Uptime: 12m 3s + +~ 2 resources · 2 services + +Service Resource Region Account +Lambda messages-api us-east-1 000000000000 +DynamoDB Messages us-east-1 000000000000 +``` + + + +1. Open the [LocalStack Web Application](https://app.localstack.cloud/) and sign in. +2. In the sidebar, under **LocalStack Instances**, click on your running instance (e.g. `localhost.localstack.cloud`). The instance should display a green **running** badge. + ![LocalStack Web Application sidebar showing a running instance](/images/aws/running-instance-sidebar.jpg) + + + +**Expected result:** the instance card shows a green **running** badge. Clicking into it opens the instance dashboard with tabs for **Overview**, **Status**, **Resource Browser**, **State**, and **Extensions**. The default tab is **Resource Browser**, which displays a list of all the resources you can inspect via the web application. + +If you don't see a running instance, see [Troubleshooting](#troubleshooting) before continuing. + +### Step 2: Inspect your app with Stack Overview + +Stack Overview gives you a summary of everything deployed on the instance. + + + +1. From the instance dashboard, click the [**Overview** tab](https://app.localstack.cloud/inst/default/overview). +2. Look for the **Lambda Function** and **DynamoDB Table** items in the list. +3. Click the arrow (`>`) next to **Lambda Function** to expand it and confirm `messages-api` is listed. Do the same for **DynamoDB Table** to confirm the `Messages` table is deployed. + + + +![Stack Overview showing deployed resource types with counts](/images/aws/stack-overview.jpg) + +:::note +Stack Overview is a **preview** feature. It only tracks a defined set of [supported resource types](/aws/connecting/console/stack-overview/#supported-resources). Lambda functions and DynamoDB tables are both covered, but if you extend this app with a service that isn't on the list, it won't show up here even though it's running fine. +::: + +**Expected result:** you can confirm, at a glance, that both the Lambda function and the DynamoDB table are deployed without needing to use the CLI. + +### Step 3: Trigger the Lambda and inspect data with the Resource Browsers + +Many supported services in LocalStack for AWS come with a resource browse that allows you to view configuration details and manage individual resources. Use it here to check the Lambda function's configuration, trigger the function, and then validate that a new row lands in DynamoDB. + + + +1. Navigate to the [**Status** tab](https://app.localstack.cloud/inst/default/status). It displays a list of the running services at the top as well as additional services that are available to use within the LocalStack emulator. +2. Under **Running** services, click **Lambda**, then, within the **Functions** tab, and click the `messages-api` function. From here you can review the function's details including the ARN, runtime, handler, and the `TABLE_NAME` environment variable pointing at `Messages`. You can also update the function code, invoke the function, and view the function logs. + ![Lambda Resource Browser showing the details of a deployed Lambda function](/images/aws/lambda-resource-browser.jpg) +3. Click **Invoke** to open the invoke dialog and paste the following JSON payload into the input field: + ```json + { + "message": "Checked out from the Resource Browser" + } + ``` +4. Click **Submit** to trigger the function. You will see the function invoked and the response returned. The log result of the response should look like this: + + ```json title="Output" + { + "statusCode": 200, + "body": { + "id": "faa4dc54-f0b7-4b6b-9e52-39702af78d73", + "message": "Checked out from the Resource Browser" + } + } + ``` + + + +With the Lambda invoked, switch to the DynamoDB side to see what it wrote: + + + +1. Back in the [**Status** tab](https://app.localstack.cloud/inst/default/status) and click on **DynamoDB** and then, fromthe **Tables** tab, click the `Messages` table. This will open the table details page where you can view the table's details including the table name, key schema, and the number of items in the table. +2. Click the **Items** tab to view the table's contents. You should see the message you posted _and_ the new one you just sent. + ![DynamoDB Resource Browser showing the Items list](/images/aws/dynamodb-resource-browser.jpg) + + + +**Expected result:** the Items view for the DynamoDB "Messages" table lists the message you posted _and_ the new one you just sent confirming that the Lambda function is writing to the table. + +:::tip +If the table doesn't appear, check the **region** dropdown in the top-right corner of the Resource Browser. It must match the region your resources were created in (`us-east-1` by default in the Getting Started). +::: + +### Step 4: Save and restore state with Cloud Pods + +[Cloud Pods](/aws/developer-tools/snapshots/cloud-pods/) let you snapshot your entire LocalStack state, including resources _and_ their data, and restore it later or share it with your team. You can save a Cloud Pod and view saved pods using the web application or CLI. Try this by saving your current app, wiping it, and restoring it via the web application. + + + +1. In your instance dashboard, click the **State** tab and then click the **Cloud** view. +2. Under **Save State to Cloud Pod**, enter `messages-api-demo` for the pod name. Leave the other options as default and click **Create New Pod**. + ![Cloud Pods Save State to Cloud Pod dialog](/images/aws/export-cloud-pod-web-app.jpg) +3. Verify it in the web application by navigating to **Cloud Pods** in the sidebar (`https://app.localstack.cloud/pods`). You should see `messages-api-demo` listed with a version `1`. + ![Cloud Pods Browser listing saved Cloud Pods](/images/aws/verify-cloud-pod-save.jpg) + + + +Now let's clear the instance and confirm it's actually gone and then restore it: + + + +1. Reset the LocalStack instance: + + ```bash + lstk reset + ``` + +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 [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) + + + +**Expected result:** Return to the [**Stack Overview** tab](https://app.localstack.cloud/inst/default/overview) again. You should see the `messages-api` and `Messages` tables are back. Opening the DynamoDB table in the resource browser and clicking the **Items** tab will show the items you saved before the restart are back as well. Cloud Pods restored the _data_ in the table, not just the table definition. + +:::note +You can do the same save/restore flow from `lstk` instead of the web applicatin using the `lstk snapshot save` and `lstk snapshot load` commands. For more details, see the [lstk documentation](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/#snapshot). +::: + +### Step 5: Trace the request flow with App Inspector + +[App Inspector](/aws/developer-tools/app-inspector/) records every call your application makes to LocalStack, so you can see the flow between services, inspect the exact payloads exchanged, and catch IAM or configuration issues before they become deployment surprises. + + + +1. Navigate to [**App Inspector** tab](https://app.localstack.cloud/inst/default/appinspector/spans?region=us-east-1) for your instance. +2. App Inspector hasn't been enabled on this instance yet, so click the **Enable App Inspector Now** button to enable it. You won't see any operations listed yet. +3. Fetch a fresh function URL, then trigger the Lambda: + + ```bash + LAMBDA_URL=$(lstk aws lambda list-function-url-configs \ + --function-name messages-api \ + --query 'FunctionUrlConfigs[0].FunctionUrl' \ + --output text) + echo $LAMBDA_URL + + curl -X POST "$LAMBDA_URL" \ + -H "Content-Type: application/json" \ + -d '{"message": "Hello, App Inspector!"}' + ``` + +4. Return to the App Inspector tab and you should see the operations listed. This is a simple demo, so you'll only see two operations: one to get the function URL and one to invoke the function. + ![App Inspector event list showing a request flow across services](/images/aws/app-inspector-operations.jpg) + + + +**Expected result:** App Inpsector correctly captures the two operations you triggered. Clicking on an operation will open the operation details panel. This will show a diagram of the request flow and the service, action, resource ARN, duration, status, and the exact request/response payload. In this case, the operations details are extremely simple and don't show any errors, but this kind of detail is invaluable for debugging and understanding the flow of your application. + +:::note +App Inspector requires LocalStack **2026.04.0** or later. If you don't see it in the sidebar, check your version with `lstk status` and update your image. +::: + +## Troubleshooting + +### Instance shows as "not running" in Instance Management +Run `lstk status` from your terminal to confirm the container's actual state, and check that Docker is running. Start it again with `lstk start` if needed — remember this gives you an empty instance unless you load a Cloud Pod afterwards. + +### Resource Browser shows a "Network Failure" error +The LocalStack container isn't running, or isn't reachable at the endpoint configured for the instance. Confirm the endpoint in Instance Management matches your running container (`https://localhost.localstack.cloud:4566` by default). Ensure that you have enabled **Private Network Access** if you are using Google Chrome (see [Troubleshooting](https://docs.localstack.cloud/aws/getting-started/faq/#why-cant-i-access-my-localstack-instance-in-the-web-application-when-using-chrome) for more details). + +### Lambda function or DynamoDB table don't appear anywhere in the web app +Check the region dropdown in the top-right of the Resource Browser. If it's set to a region other than the one you deployed to (`us-east-1` by default in the Getting Started), switch it. + +### Resources are missing after a restart, even though you didn't mean to wipe them +LocalStack does not persist state across restarts by default. Either avoid stopping the container, enable [persistence](https://docs.localstack.cloud/aws/developer-tools/snapshots/persistence/), or restore your last Cloud Pod with `lstk snapshot load pod:`. + +### `lstk snapshot save` fails with an authentication or license error +Cloud Pods require a valid LocalStack account. Run `lstk login`, or confirm `LOCALSTACK_AUTH_TOKEN` is set correctly, and try again. + +### `lstk snapshot load` warns about a version mismatch +This happens when the LocalStack version that saved the pod differs from the one running now. It's safe to proceed for this demo; in real projects, pin your LocalStack version to avoid state incompatibilities. + +## Next steps + +You've now used all four core areas of the LocalStack Web Application to inspect, manage, snapshot, and debug a running application. + +To dig deeper on any of these features, you can explore: + +- [Instance Management](https://docs.localstack.cloud/aws/connecting/console/instance-management/): bookmarking instances and connecting to a LocalStack instance running on another machine. +- [Stack Overview](https://docs.localstack.cloud/aws/connecting/console/stack-overview/): the full list of supported resource types. +- [Resource Browser](https://docs.localstack.cloud/aws/connecting/console/resource-browser/): the complete list of supported services beyond Lambda and DynamoDB. +- [Cloud Pods](https://docs.localstack.cloud/aws/developer-tools/snapshots/cloud-pods/): merge strategies, remotes, auto-loading pods on startup, and sharing state with your team. +- [App Inspector](https://docs.localstack.cloud/aws/developer-tools/app-inspector/): using it from the [LocalStack Toolkit for VS Code](https://docs.localstack.cloud/aws/connecting/ides/vscode-extension/) without leaving your editor. +- [`lstk` CLI reference](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/): the full set of `snapshot`, `status`, and `reset` commands used in this guide. + +Once you're comfortable with the local workflow, continue to the [CI/CD guide](https://docs.localstack.cloud/aws/getting-started/ci-cd/) to bring LocalStack into your automated pipelines. diff --git a/src/content/docs/aws/quickstart-library/index.mdx b/src/content/docs/aws/quickstart-library/index.mdx new file mode 100644 index 000000000..e89892b3e --- /dev/null +++ b/src/content/docs/aws/quickstart-library/index.mdx @@ -0,0 +1,23 @@ +--- +title: Overview +description: LocalStack Quickstart Library. +template: doc +sidebar: + order: 1 +--- + +import { SectionCards } from '../../../../components/SectionCards.tsx'; + +Our Quickstart Library is a growing collection of quickstart guides that help you get started with LocalStack immediately. Each quickstart walks you through a specific use case or feature of LocalStack. + + diff --git a/src/content/docs/aws/services/dsql.mdx b/src/content/docs/aws/services/dsql.mdx index 2df735c49..ea37c1b49 100644 --- a/src/content/docs/aws/services/dsql.mdx +++ b/src/content/docs/aws/services/dsql.mdx @@ -13,7 +13,7 @@ Aurora DSQL is a serverless, distributed, PostgreSQL-compatible database service It offers active-active high availability and is designed for transactional workloads that require scalability without the operational overhead of managing database infrastructure. LocalStack allows you to use the Aurora DSQL APIs to create and manage clusters, tags, resource policies, and streams in your local environment. -The data plane is backed by an embedded PostgreSQL instance, so you can connect to a cluster and run SQL against it. +The data plane is backed by an embedded PostgreSQL instance, so you can connect to a cluster and run SQL against it, including DSQL-specific dialect such as `CREATE INDEX ASYNC` and the `sys.jobs` system view. The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of Aurora DSQL's integration with LocalStack. ## Getting started @@ -266,11 +266,70 @@ awslocal dsql get-vpc-endpoint-service-name --identifier 8a71d298-c086-4fb4-a698 } ``` +## SQL dialect + +Aurora DSQL is PostgreSQL wire-compatible but adds dialect-specific DDL that vanilla Postgres rejects. +LocalStack accepts the DSQL-specific statements that applications commonly rely on so DSQL-targeted apps can run against the emulator. + +### Asynchronous indexes + +On real Aurora DSQL, [`CREATE INDEX ASYNC`](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-create-index-async.html) (and `CREATE UNIQUE INDEX ASYNC`) submits a background index build, returns a `job_id` immediately, and records the job in the [`sys.jobs`](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-systems-tables.html) system view for the application to poll. + +LocalStack accepts the same syntax. +The index is built synchronously under the hood; the observable result matches AWS: a `job_id` is returned, the index exists afterwards, and `sys.jobs` reports the job as `completed` with `job_type` `INDEX_BUILD`. + +Connect to the cluster as shown in [Connect to the cluster](#connect-to-the-cluster), then run: + +```sql +CREATE TABLE departments (name varchar(255) PRIMARY KEY, manager varchar(255)); +INSERT INTO departments (name, manager) VALUES ('HR', 'John Doe'); + +CREATE INDEX ASYNC idx_dept_name_manager ON departments (name, manager); +``` + +```bash title="Output" + job_id +------------------------------------ + a1b2c3d4e5f6g7h8i9j0k1l2m3 +(1 row) +``` + +Query `sys.jobs` to inspect the job, or call `sys.wait_for_job` to wait until it reports completion: + +```sql +SELECT job_id, status, job_type, object_name FROM sys.jobs; +SELECT sys.wait_for_job('a1b2c3d4e5f6g7h8i9j0k1l2m3'); +``` + +```bash title="Output" + job_id | status | job_type | object_name +----------------------------------+-----------+-------------+--------------------- + a1b2c3d4e5f6g7h8i9j0k1l2m3 | completed | INDEX_BUILD | idx_dept_name_manager +(1 row) + + wait_for_job +-------------- + t +(1 row) +``` + +`CREATE UNIQUE INDEX ASYNC` works the same way and enforces uniqueness once the index exists: + +```sql +CREATE UNIQUE INDEX ASYNC uidx_dept_manager ON departments (manager); +``` + +:::note +Index builds run synchronously under the hood. +Async timing (background processing, `submitted`/`processing` statuses) and the AWS 30-minute auto-cleanup of completed or failed jobs from `sys.jobs` are not modelled. +::: + ## Current Limitations - CloudFormation is not yet supported for Aurora DSQL resources. - The data plane is backed by a standard embedded PostgreSQL instance rather than the real Aurora DSQL distributed engine. - DSQL-specific SQL dialect restrictions are not enforced, so behaviour may differ from AWS for unsupported statements. +- LocalStack accepts DSQL-specific `CREATE [UNIQUE] INDEX ASYNC` and exposes `sys.jobs` / `sys.wait_for_job`, but broader DSQL dialect restrictions (for example rejecting foreign keys or `TRUNCATE`) are not enforced, so behaviour may differ from AWS for unsupported statements. +- Asynchronous index builds complete synchronously; timing semantics and automatic cleanup of old `sys.jobs` rows are not modelled. - Multi-region clusters are tracked at the control-plane level only. Peering metadata is recorded, but there is no real cross-region replication. - Data-plane data is not persisted yet. Cluster metadata survives restarts when persistence is enabled, but the data written through the embedded PostgreSQL backend (tables, rows) is not retained. diff --git a/src/content/docs/aws/services/ec2.mdx b/src/content/docs/aws/services/ec2.mdx index 677782fc5..c4a67296d 100644 --- a/src/content/docs/aws/services/ec2.mdx +++ b/src/content/docs/aws/services/ec2.mdx @@ -494,7 +494,7 @@ If you are using the [Docker Compose template](/aws/getting-started/installation "/var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock" ``` -If you are using [Docker CLI](/aws/getting-started/installation#docker), include the following parameter in `docker run`: +If you are using [Docker CLI](/aws/getting-started/installation#docker-cli), include the following parameter in `docker run`: ```text -v /var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock diff --git a/src/content/docs/aws/services/lambda.mdx b/src/content/docs/aws/services/lambda.mdx index df73abc57..e659e278c 100644 --- a/src/content/docs/aws/services/lambda.mdx +++ b/src/content/docs/aws/services/lambda.mdx @@ -589,7 +589,7 @@ With the new implementation, the following changes have been introduced: - To run Lambda functions in LocalStack, mount the Docker socket into the LocalStack container. Add the following Docker volume mount to your LocalStack startup configuration: `/var/run/docker.sock:/var/run/docker.sock`. - You can find an example of this configuration in our official [`docker-compose.yml` file](/aws/getting-started/installation/#starting-localstack-with-docker-compose). + You can find an example of this configuration in our official [`docker-compose.yml` file](/aws/getting-started/installation/#docker-compose). - The `v2` provider discontinues Lambda Executor Modes such as `LAMBDA_EXECUTOR=local`. Previously, this mode was used as a fallback when the Docker socket was unavailable in the LocalStack container, but many users unintentionally used it instead of the configured `LAMBDA_EXECUTOR=docker`. The new provider now behaves similarly to the old `docker-reuse` executor and does not require such configuration. 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 diff --git a/src/content/docs/azure/services/blob-storage.mdx b/src/content/docs/azure/services/blob-storage.mdx index c0d1ac523..08a2d8914 100644 --- a/src/content/docs/azure/services/blob-storage.mdx +++ b/src/content/docs/azure/services/blob-storage.mdx @@ -264,6 +264,7 @@ The Blob Storage emulator supports the following features: - **Storage account keys**: Keys are emulator-generated rather than managed by Azure. - **Header validation**: Unsupported request headers or parameters are silently accepted instead of being rejected. - **API version enforcement**: The emulator does not validate the `x-ms-version` header; all API versions are accepted. +- **RBAC enforcement is opt-in**: By default, data-plane operations succeed regardless of role assignments. Set `LS_AZURE_ENFORCE_RBAC` to require the caller to hold a role such as `Storage Blob Data Contributor`; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement). ## Samples diff --git a/src/content/docs/azure/services/key-vault.mdx b/src/content/docs/azure/services/key-vault.mdx index baed48a22..6f728c367 100644 --- a/src/content/docs/azure/services/key-vault.mdx +++ b/src/content/docs/azure/services/key-vault.mdx @@ -141,7 +141,8 @@ az keyvault secret list \ ## Limitations -Key Vault keys, HSM-related operations, and getting a real certificate from an official CA are not supported. +- **Keys and HSM not supported:** Key Vault keys, HSM-related operations, and getting a real certificate from an official CA are not supported. +- **RBAC enforcement is opt-in and covers secrets/certificates only:** By default, data-plane operations succeed regardless of role assignments. Set `LS_AZURE_ENFORCE_RBAC` to enforce roles such as `Key Vault Secrets User` or `Key Vault Certificates Officer` on vaults created with `enableRbacAuthorization=true`; keys are not covered. See [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement). ## Samples diff --git a/src/content/docs/azure/services/managed-identity.mdx b/src/content/docs/azure/services/managed-identity.mdx index 1aa10cfc9..74bd8c314 100644 --- a/src/content/docs/azure/services/managed-identity.mdx +++ b/src/content/docs/azure/services/managed-identity.mdx @@ -276,6 +276,7 @@ The Managed Identity emulator supports the following features: - **Management locks**: Create, delete, retrieve, and list management locks at the resource group level. Supported lock levels are `CanNotDelete` and `ReadOnly`. - **Microsoft Graph service principal queries**: List, create, and delete service principals through the Microsoft Graph `/v1.0/servicePrincipals` endpoint with OData query support including `$filter`, `$select`, `$top`, `$count`, and `$orderby`. - **Directory object lookups**: Resolve multiple directory objects by ID through the `/v1.0/directoryObjects/getByIds` endpoint. +- **Principal propagation**: Tokens minted for a managed identity via the Instance Metadata Service (IMDS) or AKS Workload Identity carry that identity's principal ID, which is what [RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement) evaluates role assignments against when enabled. ## Limitations diff --git a/src/content/docs/azure/services/queue-storage.mdx b/src/content/docs/azure/services/queue-storage.mdx index 235f4623d..940df0977 100644 --- a/src/content/docs/azure/services/queue-storage.mdx +++ b/src/content/docs/azure/services/queue-storage.mdx @@ -253,6 +253,7 @@ The Queue Storage emulator supports the following features: - **Storage account keys**: Keys are emulator-generated rather than managed by Azure. - **Header validation**: Unsupported request headers or parameters are silently accepted instead of being rejected. - **API version enforcement**: The emulator does not validate the `x-ms-version` header; all API versions are accepted. +- **RBAC enforcement is opt-in**: By default, data-plane operations succeed regardless of role assignments. Set `LS_AZURE_ENFORCE_RBAC` to require the caller to hold a role such as `Storage Queue Data Contributor`; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement). ## Samples diff --git a/src/content/docs/azure/services/resource-manager.mdx b/src/content/docs/azure/services/resource-manager.mdx index ace9b3c88..e3decd431 100644 --- a/src/content/docs/azure/services/resource-manager.mdx +++ b/src/content/docs/azure/services/resource-manager.mdx @@ -241,7 +241,7 @@ The Resource Manager emulator supports the following features: - **No what-if analysis**: The `az deployment group what-if` operation is not implemented. - **ARM template function coverage**: While over 60 functions are supported, some less common functions or advanced overloads may not be fully implemented. - **No resource tags on generic resource listings**: Tags and extended properties may not be fully populated when listing resources across a subscription. -- **No RBAC enforcement on resource operations**: All API calls succeed without role-based access control checks. +- **RBAC enforcement on resource operations is opt-in**: By default, all API calls succeed without role-based access control checks. Set `LS_AZURE_ENFORCE_RBAC` to enable control-plane checks across ARM resource types; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement). - **Deployment concurrency**: Resources within a single deployment are created sequentially with dependency resolution, not in full parallel as in Azure. - **No deployment cancellation**: Running deployments cannot be cancelled. - **No deployment deletion**: Deployments are retained in memory and cannot be explicitly deleted via the API. diff --git a/src/content/docs/azure/services/role-assignment.mdx b/src/content/docs/azure/services/role-assignment.mdx index 434b5d871..f2f1dd872 100644 --- a/src/content/docs/azure/services/role-assignment.mdx +++ b/src/content/docs/azure/services/role-assignment.mdx @@ -1,10 +1,10 @@ --- -title: "Role Assignment" +title: 'Role Assignment' description: Get started with Azure Role Assignments on LocalStack template: doc --- -import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureFeatureCoverage"; +import AzureFeatureCoverage from '../../../../components/feature-coverage/AzureFeatureCoverage'; ## Introduction @@ -316,6 +316,18 @@ az role assignment delete \ --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/rg-rbac-demo" ``` +## Enabling RBAC enforcement + +By default, Azure RBAC on LocalStack is **not enforced**: role assignments and role definitions are stored, but every operation succeeds regardless of the assigned roles. Set `LS_AZURE_ENFORCE_RBAC` to `true`, `yes`, or `1` when starting the emulator to turn on enforcement. + +With enforcement enabled: + +- **Control plane**: every ARM request, across all Azure services and resource types, is checked against the caller's role assignments at the target scope and denied with a `403` if unauthorized. +- **Data plane**: checked for [Blob](/azure/services/blob-storage/), [Queue](/azure/services/queue-storage/), and [Table](/azure/services/table-storage/) Storage, RBAC-mode [Key Vault](/azure/services/key-vault/) vaults (secrets and certificates only), and Event Grid publish/receive. Denials match the shape Azure returns for each service, for example a Storage `AuthorizationPermissionMismatch` XML error or a Key Vault `ForbiddenByRbac` error. +- **Not covered yet**, even with enforcement enabled: Storage File, the Service Bus data plane, Cosmos DB's data plane, and Microsoft Entra database authentication for Azure SQL, PostgreSQL, and MySQL flexible servers. Requests to these continue to succeed regardless of role assignments. + +The default SDK/Terraform service principal and the `az` CLI's `any-app` principal are always treated as a Global Administrator and subscription Owner, and bypass data-plane checks by default too. To observe a deny, use a managed identity or service principal that assumes neither role — for example, the identity created in [Create a user-assigned managed identity](#create-a-user-assigned-managed-identity) without a role assigned at the target scope. + ## Features - **Role assignment creation:** Create role assignments by specifying an assignee principal ID, role name or ID, and scope. @@ -327,7 +339,7 @@ az role assignment delete \ ## Limitations -- **RBAC not enforced:** Role assignments are stored but not evaluated. All operations on LocalStack succeed regardless of assigned roles. +- **RBAC enforcement is opt-in:** By default, role assignments are stored but not evaluated, and all operations succeed regardless of assigned roles. Set `LS_AZURE_ENFORCE_RBAC` to enable enforcement. - **Condition-based assignments:** Attribute-based access control (ABAC) conditions in assignments are accepted at the model level but are not evaluated. - **Deny assignments:** `Microsoft.Authorization/denyAssignments` are not supported. - **Management group scopes:** Assignments at management group scope are not supported. diff --git a/src/content/docs/azure/services/role-definition.mdx b/src/content/docs/azure/services/role-definition.mdx index 4a93fb012..9e3a7b187 100644 --- a/src/content/docs/azure/services/role-definition.mdx +++ b/src/content/docs/azure/services/role-definition.mdx @@ -166,7 +166,7 @@ az role definition list --name "Custom Storage Reader" ## Limitations -- **RBAC not enforced:** Role definitions and assignments are stored in the emulator but permissions are not enforced: API calls are not gated the way they are in Azure, and effective access for a principal at a scope is not evaluated from assignments and role definitions. +- **RBAC enforcement is opt-in:** By default, role definitions and assignments are stored but permissions are not enforced, so API calls are not gated the way they are in Azure. Set `LS_AZURE_ENFORCE_RBAC` to enable enforcement; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement) for scope and coverage. - **Management group scopes:** Management group–level assignable scopes are not supported. ## Samples diff --git a/src/content/docs/azure/services/table-storage.mdx b/src/content/docs/azure/services/table-storage.mdx index d70d3211b..6553f5dfc 100644 --- a/src/content/docs/azure/services/table-storage.mdx +++ b/src/content/docs/azure/services/table-storage.mdx @@ -308,6 +308,7 @@ The Table Storage emulator supports the following features: - **Storage account keys**: Keys are emulator-generated rather than managed by Azure. - **Header validation**: Unsupported request headers or parameters are silently accepted (Azurite runs in loose mode) instead of being rejected. - **API version enforcement**: The emulator does not validate the `x-ms-version` header; all API versions are accepted. +- **RBAC enforcement is opt-in**: By default, data-plane operations succeed regardless of role assignments. Set `LS_AZURE_ENFORCE_RBAC` to require the caller to hold a role such as `Storage Table Data Contributor`; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement). ## Samples diff --git a/src/content/docs/snowflake/tutorials/aws-lambda-localstack-snowpark.md b/src/content/docs/snowflake/tutorials/aws-lambda-localstack-snowpark.md index e0501c60f..368123de1 100644 --- a/src/content/docs/snowflake/tutorials/aws-lambda-localstack-snowpark.md +++ b/src/content/docs/snowflake/tutorials/aws-lambda-localstack-snowpark.md @@ -114,11 +114,12 @@ Run the following command: ```bash showLineNumbers pip3 install \ - --platform manylinux2010_x86_64 \ + --platform manylinux2014_x86_64 \ --implementation cp \ + --python-version 3.10 \ --only-binary=:all: --upgrade \ --target ./libs \ - snowflake-connector-python==2.7.9 boto3==1.26.153 botocore==1.29.153 + snowflake-connector-python==2.7.9 boto3==1.26.153 botocore==1.29.153 ``` ## Package the Lambda function @@ -127,6 +128,7 @@ Package the Lambda function and its dependencies into a ZIP file. Run the follow ```bash showLineNumbers mkdir -p build +cp handler.py build/ cp -r libs/* build/ (cd build && zip -q -r function-py.zip .) ``` @@ -164,7 +166,8 @@ After successfully deploying the Lambda function, you will receive a response wi ```bash showLineNumbers awslocal lambda invoke --function-name localstack-snowflake-lambda-example \ - --payload '{"body": "test" }' output.txt + --cli-binary-format raw-in-base64-out \ + --payload '{"body": "test"}' output.txt ``` You will receive a response with the details of the invocation. You can view the output in the `output.txt` file. To see the SQL queries executed by the Lambda function, check the logs by navigating to LocalStack logs (`localstack logs`). diff --git a/src/styles/custom.css b/src/styles/custom.css index c5839b94a..14a36c634 100644 --- a/src/styles/custom.css +++ b/src/styles/custom.css @@ -24,6 +24,19 @@ vertical-align: middle; } +.lightning-icon::before { + content: ""; + display: inline-block; + width: 16px; + height: 16px; + background-image: url('/src/assets/images/lightning.svg'); + background-size: contain; + background-repeat: no-repeat; + background-position: center; + margin-right: 6px; + vertical-align: middle; +} + .file-icon::before { content: ""; display: inline-block;