Important Changes in LocalStack 4.0

We’re preparing a major LocalStack release that includes new and significant features to enhance your cloud development experience. This post details some potentially breaking changes that you need to be aware of so you can update your LocalStack setup as needed.

Tentative Timeline

• Thursday, November 14, 2024: ⚠️ We will merge the release branch v4 into master, updating the latest Docker image with the release candidate of v4. This merge will implement all breaking changes in v4, impacting your pipeline if you use the latest tag.
• Thursday, November 21, 2024: We will publish the tagged release v4.0.0.

Users on the latest tag will automatically get the newest version. If you prefer to use the most recent tagged release from a previous series, you can use the major version tag (for example, 3), which points to the latest 3.x release.

How to migrate

Auth Tokens to replace CI Keys

Auth tokens have fully replaced legacy API and CI keys for both personal and CI use, increasing security and enabling more detailed access control. This update includes:

1. Personal Developer Auth Token: Remains unchanged for individual users, offering unique tokens for accessing the core cloud emulator and other platform features.
2. New CI Auth Token: A team-shared token designed for use in CI and automated environments, allowing access to the core cloud emulator and other platform features.

Existing API and CI keys will function until early 2025, after which only Auth Tokens will be supported. Transitioning is straightforward. You can set the new token in the LOCALSTACK_AUTH_TOKEN variable. For a temporary period, legacy credentials can be used by configuring the new Auth Token in the LOCALSTACK_API_KEY variable to maintain backward compatibility.

Migration of Lambda K8s Executor in Enterprise

We’ve updated our plan offerings and the Lambda Kubernetes Executor is now exclusively available with our Enterprise plan. If you’re using any tier other than Enterprise, setting LAMBDA_RUNTIME_EXECUTOR ( or lambda.executor when using the Helm configuration) to kubernetes will not have any effect.

Deprecation of non-prefixed environment variables

The LocalStack CLI is closely integrated with the runtime and needs to be able to determine which environment variables it should pass from the user’s environment to the Docker container. This requirement restricts the CLI’s compatibility with new environment variables introduced in later LocalStack versions, often leading to issues that are challenging to debug. Using a well-known prefix (LOCALSTACK_) will enable forwards-compatibility for newer configuration options.

To enhance flexibility, users are encouraged to use the variable prefix LOCALSTACK_ for more straightforward management of environment variables across different versions.

Deprecation of LocalStack Auth login

LocalStack CLI will now exclusively use Auth Tokens for user identification and authentication. The localstack auth login command is now deprecated and will be removed in the future. The CLI will either retrieve the Auth Token from the LOCALSTACK_AUTH_TOKEN environment variable, or you can directly set the auth token using the localstack auth set-token command.

Removal of default AWS credentials from Init Hooks

The default AWS credentials will no longer be set automatically during Init Hooks execution. This change requires updates to existing scripts that make use of Boto configuration environment variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, etc. which will now be required to be set explicitly.

Version Identification for LocalStack CLI

In addition to the LocalStack runtime, the LocalStack CLI also adheres to semantic versioning. Previously, the CLI version command would output a semantic number without clarifying whether it referred to LocalStack or the CLI itself. The recent update address this ambiguity by prefixing the output with LocalStack CLI before the version number. Here’s an example:

localstack --version

LocalStack CLI 3.8

Removal of Deprecated Features

The section below details the removal of configurations that were deprecated in earlier versions. Using these outdated configurations with current images already triggers warnings. If you have kept up with the latest updates from previous releases, these changes will not impact you.

Legacy Step Functions Provider

The legacy Step Functions provider is being removed. This will impact you if you have set PROVIDER_OVERRIDE_STEPFUNCTIONS=legacy or its alias v1. To transition, please remove this setting and use the new Step Functions provider.

Legacy S3 v2 Provider

The legacy S3 provider introduced in LocalStack 2.0 is being removed. This will impact you if you have set PROVIDER_OVERRIDE_S3=legacy_v2 or one of its aliases (v2, asf). To transition, please remove this setting and use the new S3 provider.

Legacy ElastiCache Provider

The legacy ElastiCache provider is being removed. This will impact you if you have set PROVIDER_OVERRIDE_ELASTICACHE=legacy. To transition, please remove this setting and use the new ElastiCache provider.

Legacy Event Source Mapping (ESM) implementation

The legacy Event Source Mapping (ESM) implementation is being removed. This will impact you if you have set LAMBDA_EVENT_SOURCE_MAPPING=v1. To transition, please remove this setting and use the new Event Source Mapping (ESM) implementation.

Removal of custom LocalStack FIS actions

The following custom LocalStack FIS actions, which were deprecated a long time ago, will now be removed:

• localstack:generic:api-error
• localstack:kms:inject-api-internal-error
• localstack:log-debug
• localstack:generic:latency

Give the Chaos API a try for this functionality.

Removal of Outages Extension

The LocalStack Outages Extension, which enabled you to simulate outages across any AWS region or service, has been replaced by the Chaos API starting with the v3.6 release. This extension will no longer be published on PyPI and will not be maintained anymore. Please follow our documentation to migrate to the Chaos API.

Removal of deprecated Airflow versions for MWAA

Earlier this year, we followed AWS in deprecating several Airflow versions.

Support for these deprecated Airflow versions has been removed. However, the Docker images will remain available on the Docker registry to support older LocalStack versions.

Others

In addition to the changes above, support for the following features has been removed as well:

1. Support for RDS PostgreSQL 10 which was deprecated in LocalStack v3.2.0.
2. Support for Ubuntu 20.04 AMI (ami-ff0fea8310f3) for EC2 which was deprecated in LocalStack v3.2.0.
3. Support for Python 3.8 in the Python distribution of the LocalStack CLI.