<!-- Release notes generated using configuration in .github/release.yml at v3.0.0 -->
Summary
This is our third major release for LocalStack featuring both updates to our core services as well as auxiliary tooling. With our third major release for LocalStack we’re introducing improved service providers for ElastiCache, StepFunctions and S3, improved write performance in DynamoDB, increased Multi-Account and Multi-Region support and much more! A simplified networking configuration, new default container name and lots of internal refactoring to unify endpoint generation will help developers when testing their cloud applications locally.
Additionally to our core emulation in LocalStack we’ve released many additional features available in our Web Application such as IAM policy streams and a Chaos Engineering section to help you bulletproof your applications, both in terms of minimal permissions and increased robustness against failures. Our new Desktop application, LocalStack Desktop, has been released as the successor to our legacy Cockpit App and can be downloaded in the Web Application.
Several of these changes require a migration and we have done our best to make the migration for you as smooth as possible. Head to the *How to migrate* section and the linked resources there, to find out more. If you have trouble migrating to LocalStack 3.0 please reach out to us, we’re happy to help!
AWS Features
- Native `v2` provider for StepFunctions (default since 3.0.0)
- Native `v3` provider for S3 (default since 3.0.0)
- **Pro** New ElastiCache provider (default since 3.0.0)
- Huge performance improvements for DynamoDB write operations (1.6x for single `PutItem` and up to 10x for `BatchWriteItem`)
- Improved Multi-Account and Multi-Region support in multiple services such as CloudWatch, StepFunctions, EventBridge, Glue and more.
- The way ARNs are constructed internally has been significantly revamped. This change is particularly beneficial for users working with LocalStack in scenarios involving non-default account IDs or regions.
- Updating Lambda Event Source Mappings to point to different function versions has been fixed to now correctly switch the target and trigger the new version.
- We now offer both a Query and JSON-protocol support for SQS to support recent low-level changes in the SQS API
- DocumentDB has received support for `MasterUsername` and `MasterUserPassword`. With the feature flag `DOCDB_PROXY_CONTAINER=1` a proxied container is started, and Lambda can connect to the container using `LOCALSTACK_HOSTNAME`
- RDS now actually uses MySQL (instead of MariaDB) if the engine `mysql` is used. It now also correctly returns only the hostname in the `Endpoint` field of responses to the `CreateDBCluster` operation.
- Lots of incremental improvements to CloudFormation
- Improved detection of undefined dependencies in templates
- Support for Fn::Select in conditionals
- Fix AWS::S3::Bucket EventBridge Notifications
- Resources in Community
- (New) AWS::EC2::NetworkAcl
- (New) AWS::EC2::DHCPOptions
- (Updated) AWS::DynamoDB::Table
- (Updated) AWS::OpenSearch::Domain
- Resources in **Pro**
- (New) AWS::ElasticBeanstalk::Application
- (New) AWS::ElasticBeanstalk::ApplicationVersion
- (New) AWS::ElasticBeanstalk::Environment
- (New) AWS::ElasticBeanstalk::ConfigurationTemplate
- (Updated) AWS::RDS::DBCluster
LocalStack Features
- We now create **native M1 binaries of our CLI**. When [installing via Brew](https://docs.localstack.cloud/getting-started/installation/#localstack-cli) these are automatically selected for you depending on your CPU architecture.
- Since 3.0 we publish **major tags**. You can pin the current major version like this: `localstack/localstack-pro:3` to stay on the latest tagged 3.x release but avoid unintentionally upgrading to the next major version.
- With 3.0 we’re also now for the first time publishing a `stable` tag, which will always point towards the latest tagged release.
- The localstack docker image is now based on Python 3.11 and Debian Bookworm
- The default container name for LocalStack is now `localstack-main` (previously `localstack_main`) to allow the use of the name in URLs.
- Networking configuration has been simplified by removing legacy options and moving to `GATEWAY_LISTEN` and `LOCALSTACK_HOST`. Check out our [Discuss page](https://discuss.localstack.cloud/t/networking-migration-guide-for-localstack-3-0/588) for more information.
- Strict Service Loading allows you to define a strict subset of services to load via the `SERVICES` variable, e.g. `SERVICES=s3` . Any services not listed here will now be prevented from loading.
- [Lots of enhancements for LocalStack Extensions](https://docs.localstack.cloud/user-guide/extensions/)
- [**LocalStack Desktop**](https://docs.localstack.cloud/user-guide/tools/localstack-desktop/) is replacing the deprecated Cockpit Desktop UI
- The IAM policy stream is a new feature in our Web Application that allows you to see exactly which permissions are needed for the API calls you’re making in LocalStack.
- We’ve improved the Chaos Engineering capabilities of LocalStack, extending or FIS (Fault Injection Simulator) implementation and added a UI to interface with it in our Web Application.
Provider Deprecations
- StepFunctions `legacy` / `v1` provider has been deprecated and will be removed in the next major version.
- S3 `v2` provider has been deprecated and will be removed in the next major version.
- ElastiCache `legacy` provider has been deprecated and will be removed in the next major version.
Removals
- Lambda `legacy` / `v1` provider has been removed.
- S3 `legacy` / `v1` provider has been removed.
- We’ve removed a lot of legacy code with this major release. If you’ve been using any internal constructs from localstack, e.g. via extensions, please make sure they are still working. Feel free to reach out to us if you need help migrating your extension.
- Community Cloud Pods have been removed.
- After its initial preview phase, AWS RAM is now part of our paid offering and will be further developed and integrated with our IAM enforcement in future releases.
- [Configuration](https://docs.localstack.cloud/references/configuration/)
- `DEFAULT_REGION`, `USE_SINGLE_REGION`
- `ES_ENDPOINT_STRATEGY`, `ES_MULTI_CLUSTER`, `ES_CUSTOM_BACKEND`
- `KINESIS_INITIALIZE_STREAMS`
- `SYNCHRONOUS_*_EVENTS`
- `EC2_AUTOSTART_DAEMON`
- `*_PORT_EXTERNAL`
- legacy `LAMBDA_*` settings, see the sections below for more details
How to migrate
Networking
We have published an extensive migration guide for our networking related changes on [this Discuss page ](https://discuss.localstack.cloud/t/networking-migration-guide-for-localstack-3-0/588)
- The default container name is renamed from **`localstack_main`** to **`localstack-main`**
- Our default container name `localstack_main` is not a valid URL, so when the container name is used as a hostname, some libraries refuse to connect. With this release, we use the default container name of `localstack-main`. There may be breakages with tooling that expects the new container name, but a container is running with the old container name. Please update your tooling accordingly.
- Most prominently, this is container name used in `docker-compose` files.
- If you are using the LocalStack CLI, please just make sure to update to the latest version after the release. The CLI will handle this migration automatically.
- `HOSTNAME_EXTERNAL` and `LOCALSTACK_HOSTNAME` are removed in favor of `LOCALSTACK_HOST`
- We are simplifying how to configure LocalStack by fully switching over to use `LOCALSTACK_HOST` to configure URLs returned by AWS services. Please update your usages of `HOSTNAME_EXTERNAL` (default: `localhost`) and `LOCALSTACK_HOSTNAME` to use `LOCALSTACK_HOST` (default: `localhost.localstack.cloud:4566`). You can find more details in our [Networking Migration Guide for LocalStack 3.0](https://discuss.localstack.cloud/t/networking-migration-guide-for-localstack-3-0/588).
New default protocol for the SQS API
AWS recently updated the default protocol for the SQS API in many of their SDKs, which started breaking with LocalStack since we didn't have JSON support yet. With 3.0.0 we now support both protocols, but if you are still on 2.x a workaround would be to downgrade or pin your used SDK/tool version.
Here is the list with all the SDK versions where the issue will start appearing:
Language | SDK client repository | Required SDK client version
--- | --- | ---
C++ | [aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp) | [1.11.98](https://github.com/aws/aws-sdk-cpp/releases/tag/1.11.198)