From b096004a131f653ba3d0fe82cd841b44b369c7c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 9 Jul 2026 11:39:44 +0000 Subject: [PATCH] docs: catch up README and RELEASING guide with undocumented CLI features README was missing coverage of several existing but undocumented user-facing features: the `lstk aws` and `lstk sam` proxies, `lstk reset`/`lstk restart`, the `image` config field for custom/offline images, GATEWAY_LISTEN host exposure, the `setup az` alias, extension bundled-dir resolution, the single-`[[containers]]`-block restriction, and the `lstk save`/`lstk load` top-level shortcuts. docs/RELEASING.md didn't mention the automated weekly release workflow (`automated-release.yml`), only the manual tag-creation path. Co-Authored-By: Claude Sonnet 5 --- README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++--- docs/RELEASING.md | 15 +++++----- 2 files changed, 78 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 95bac133..83bbae00 100644 --- a/README.md +++ b/README.md @@ -47,9 +47,13 @@ Running `lstk` will automatically handle configuration setup and start LocalStac - **Log streaming** — tail emulator logs in real-time with `--follow`; use `--verbose` to show all logs without filtering - **Snapshots** — save, load, and remove emulator state as local files, named cloud snapshots (`pod:` prefix), or in your own S3 bucket (`s3://`), and auto-load one on start - **Browser-based login** — authenticate via browser and store credentials securely in the system keyring +- **AWS CLI proxy** — run `lstk aws ` with endpoint, credentials, and region pre-configured - **AWS CLI profile** — optionally configure a `localstack` profile in `~/.aws/` after start - **Terraform integration** — proxy Terraform commands to LocalStack with automatic AWS provider endpoint configuration - **CDK integration** — proxy AWS CDK commands to LocalStack with automatic endpoint configuration (requires AWS CDK >= 2.177.0) +- **SAM integration** — proxy AWS SAM CLI commands to LocalStack (requires AWS SAM CLI >= 1.95.0) +- **Reset / restart** — clear in-memory emulator state with `lstk reset`, or restart the emulator with `lstk restart` +- **Extensions** — Git-style `lstk-` executables extend the CLI with new commands - **Self-update** — check for and install the latest `lstk` release with `lstk update` - **Shell completions** — bash, zsh, and fish completions included @@ -94,11 +98,14 @@ port = "4566" The chosen emulator must be running before you set up or use its CLI integration below. +> [!NOTE] +> Only one `[[containers]]` block can be enabled at a time — running multiple emulators together (e.g. AWS and Snowflake) isn't supported yet. + You can also configure cloud CLI integration: ```bash lstk setup aws # localstack profile in ~/.aws/ -lstk setup azure # isolated Azure CLI config for `lstk az` (requires the Azure CLI) +lstk setup azure # isolated Azure CLI config for `lstk az` (requires the Azure CLI); alias: lstk setup az ``` After starting the Azure emulator and running `lstk setup azure`, run Azure CLI commands against LocalStack with `lstk az`: @@ -132,6 +139,7 @@ lstk --config /path/to/config.toml start type = "aws" # Emulator type. Currently supported: "aws", "snowflake", "azure" tag = "latest" # Docker image tag, e.g. "latest", "2026.03" port = "4566" # Host port the emulator will be accessible on +# image = "" # Override the default Docker image, e.g. an internal registry mirror (see below) # volumes = [] # Bind mounts, "host:container[:ro]" (see below) # env = [] # Named environment profiles to apply (see [env.*] sections below) # snapshot = "pod:my-baseline" # Snapshot REF auto-loaded on start (AWS only); see Snapshots below @@ -141,6 +149,7 @@ port = "4566" # Host port the emulator will be accessible on - `type`: emulator type; one of `"aws"`, `"snowflake"`, or `"azure"` - `tag`: Docker image tag for LocalStack (e.g. `"latest"`, `"4.14.0"`); useful for pinning a version - `port`: port LocalStack listens on (default `4566`) +- `image`: (optional) override the default `localstack/:` image, e.g. `"my-registry.example.com/localstack:latest"` for an internal mirror or a locally loaded offline image; if it already carries a tag, `tag` above is ignored - `volumes`: (optional) list of `"host:container[:ro]"` bind mounts, e.g. for init hooks or the persistent-state directory (see below) - `env`: (optional) list of named environment variable groups to inject into the container (see below) - `snapshot`: (optional) snapshot REF auto-loaded after the emulator starts on a fresh run — a local file path or a `pod:` cloud snapshot (see [Snapshots](#snapshots)) @@ -168,6 +177,22 @@ EAGER_SERVICE_LOADING = "1" Host environment variables prefixed with `LOCALSTACK_` are also forwarded to the emulator. +### Exposing the emulator beyond localhost + +By default the gateway (and its published ports) are only reachable from `localhost`. To expose it more broadly (e.g. on an EC2 or VM host), set `GATEWAY_LISTEN` in an `[env.*]` profile: + +```toml +[[containers]] +type = "aws" +port = "4566" +env = ["public"] + +[env.public] +GATEWAY_LISTEN = "0.0.0.0:4566,0.0.0.0:443" +``` + +The host part of the first entry becomes the bind address for every published port (the gateway ports and the 4510-4559 service range); it defaults to `127.0.0.1` when unset. + ### Mounting volumes and init hooks Use `volumes` to bind-mount host files or directories into the emulator, given as Docker-style `"host:container[:ro]"` strings. The most common use is [init hooks](https://docs.localstack.cloud/snowflake/capabilities/init-hooks/) — scripts LocalStack runs automatically on startup when mounted into `/etc/localstack/init/{boot,start,ready,shutdown}.d`: @@ -223,6 +248,15 @@ lstk --non-interactive | `LSTK_OTEL=1` | Enables OpenTelemetry trace export (disabled by default). When enabled, standard `OTEL_EXPORTER_OTLP_*` env vars are respected by the SDK (e.g. `OTEL_EXPORTER_OTLP_ENDPOINT` defaults to `http://localhost:4318`). Requires an OTLP-compatible backend to receive and visualize telemetry — for local development, `make otel` starts one (UI at http://localhost:16686). | | `DOCKER_HOST` | Override the Docker daemon socket (e.g. `unix:///home/user/.colima/default/docker.sock`). When unset, lstk tries the default socket and then probes common alternatives (Colima, OrbStack). | +### AWS CLI Proxy + +`lstk aws ` runs the AWS CLI against LocalStack with the endpoint, credentials, and region pre-configured — equivalent to `aws --endpoint-url http://localhost:4566 ` with `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_DEFAULT_REGION` set automatically. Requires the AWS CLI on your `PATH`. This is separate from `lstk setup aws`, which configures a persistent `localstack` profile in `~/.aws/` instead. + +```bash +lstk aws s3 ls +lstk aws sqs list-queues +``` + ### Terraform Integration `lstk terraform` (alias `tf`) is a proxy that runs Terraform commands against LocalStack, automatically configuring the AWS provider to use LocalStack's endpoints. This allows you to test infrastructure-as-code locally before deploying to AWS. @@ -256,6 +290,25 @@ CDK always targets the default LocalStack account 000000000000; there is no --ac - `AWS_ENDPOINT_URL_S3` — Override the auto-derived S3 endpoint - `AWS_REGION` — Fallback for `--region` flag +### SAM Integration + +`lstk sam` is a proxy that runs AWS SAM CLI commands against LocalStack, automatically configuring the endpoint and credentials. + +**Requires AWS SAM CLI version 1.95.0 or newer** on your `PATH` (older versions ignore `AWS_ENDPOINT_URL` and would target real AWS). + +**lstk-specific flags** (appear after the `sam` subcommand): +- `--region ` — Deployment region (default: `us-east-1`) +- `--account ` — Target AWS account ID, 12 digits (default: `000000000000`) + +**Environment variables:** +- `LSTK_SAM_CMD` — SAM binary to invoke (default: `sam`) +- `AWS_ENDPOINT_URL` — Override the auto-resolved LocalStack endpoint +- `AWS_ENDPOINT_URL_S3` — Override the auto-derived S3 endpoint +- `AWS_REGION` — Fallback for `--region` flag +- `AWS_ACCESS_KEY_ID` — Fallback for `--account` flag + +Known limitations versus `samlocal`: image/container-based Lambda (ECR) deploys and nested CloudFormation stacks are not supported. + ## Usage ```bash @@ -268,6 +321,12 @@ LOCALSTACK_AUTH_TOKEN= lstk --non-interactive # Stop the running emulator lstk stop +# Restart the emulator +lstk restart + +# Clear in-memory emulator state (buckets, functions, etc.) without stopping it +lstk reset + # Show emulator status and deployed resources lstk status @@ -292,6 +351,9 @@ lstk update # Show resolved config file path lstk config path +# Run AWS CLI commands against LocalStack +lstk aws s3 ls + # Set up AWS CLI profile integration lstk setup aws @@ -305,7 +367,7 @@ lstk az group list lstk az start-interception lstk az stop-interception -# Save emulator state to a local file +# Save emulator state to a local file (`lstk save` is a shortcut for `lstk snapshot save`) lstk snapshot save ./my-snapshot.snapshot # Save emulator state as a named cloud snapshot on the LocalStack platform @@ -314,7 +376,7 @@ lstk snapshot save pod:my-baseline # Save to your own S3 bucket (credentials from AWS_* env vars or --profile) lstk snapshot save my-pod s3://my-bucket/prefix -# Load a snapshot back into the running emulator +# Load a snapshot back into the running emulator (`lstk load` is a shortcut for `lstk snapshot load`) lstk snapshot load pod:my-baseline lstk snapshot load my-pod s3://my-bucket/prefix @@ -346,6 +408,10 @@ lstk cdk deploy --require-approval never # Synthesize a CDK app (offline, no running emulator needed) lstk cdk synth +# Build and deploy a SAM app against LocalStack +lstk sam build +lstk sam deploy + ``` ## Snapshots @@ -425,7 +491,7 @@ lstk start --no-snapshot # skip auto-loading this run ## Extensions -lstk supports Git-style extensions: running `lstk `, for a name that isn't a built-in command, delegates to an external `lstk-` executable found on your `PATH`, forwarding all arguments and passing stdin/stdout/stderr through. +lstk supports Git-style extensions: running `lstk `, for a name that isn't a built-in command, resolves and delegates to an external `lstk-` executable — checked first in lstk's bundled-extensions directory, then on your `PATH` — forwarding all arguments and passing stdin/stdout/stderr through. ```bash lstk my-tool --flag # resolves and runs lstk-my-tool, if it exists diff --git a/docs/RELEASING.md b/docs/RELEASING.md index f347db59..58ee6da3 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -10,16 +10,17 @@ Every PR must carry exactly one release label (enforced by `Require release labe ## Release workflows -Release automation uses two workflows: +Release automation uses three workflows: -1. `Create Release Tag` (`.github/workflows/create-release-tag.yml`) -2. `LSTK CI` (`.github/workflows/ci.yml`) +1. `Automated Weekly Release` (`.github/workflows/automated-release.yml`) — runs on a schedule (Thursdays) and can also be triggered manually. +2. `Create Release Tag` (`.github/workflows/create-release-tag.yml`) — manual-only. +3. `LSTK CI` (`.github/workflows/ci.yml`) -How it works: +**Automated weekly release** (the default path): every Thursday, the workflow checks whether `main` has any commits since the last `v*.*.*` tag. If so, it inspects the labels on every PR merged since that tag, picks the highest release label found (`major` > `minor` > `patch`, defaulting to `patch`), runs full CI, then creates and pushes the next version tag — which in turn triggers `LSTK CI`'s `release` job below. If there are no changes since the last tag, it skips the release entirely. -1. Manually run `Create Release Tag` from GitHub Actions (default ref: `main`), choosing a `patch` or `minor` bump. -2. The workflow computes and pushes the next version tag (e.g. `v0.2.4`). -3. Pushing the tag triggers `LSTK CI`, which runs the `release` job and publishes the GitHub release with GoReleaser. +**Manual release**: run `Create Release Tag` from GitHub Actions (default ref: `main`), choosing a `patch` or `minor` bump, when you need to cut a release outside the weekly schedule. + +Either path pushes a version tag (e.g. `v0.2.4`), which triggers `LSTK CI`, running the `release` job to publish the GitHub release with GoReleaser. To validate release packaging locally without publishing: