Skip to content

[embedded-localstack] LocalStack image requires authentication from March 23, 2026 #2872

@HarshCasper

Description

@HarshCasper

Hey folks 👋

I'm Harsh from the LocalStack team. Wanted to flag an upcoming change that will directly affect users of the embedded-localstack module.

What's changing: Starting March 23, 2026, localstack/localstack:latest on Docker Hub will consolidate into a single unified image that requires authentication via a LOCALSTACK_AUTH_TOKEN. The free Community image, as it exists today, will no longer be available under that tag without an auth token set.

What this means for this repo:

LocalStackProperties.getDefaultDockerImage() currently returns localstack/localstack, and EmbeddedLocalStackBootstrapConfiguration starts the container using that image via ContainerUtils.getDockerImageName(properties). Any Spring Boot application that uses embedded.localstack without setting LOCALSTACK_AUTH_TOKEN will fail to start the container after March 23.

The places most likely to need updating:

  • LocalStackProperties.java — image tags after 4.14.0 will require auth; the property docs and any README guidance should note that LOCALSTACK_AUTH_TOKEN must be set in the environment
  • EmbeddedLocalStackBootstrapConfiguration.java — consider passing LOCALSTACK_AUTH_TOKEN as an env var to the container if present in the host environment
  • Documentation / README for embedded-localstack — auth token setup should be listed as a prerequisite

What users will need to do:

  1. Sign up for a free LocalStack account at localstack.cloud
  2. Generate an auth token from the LocalStack Web App
  3. Set LOCALSTACK_AUTH_TOKEN as an environment variable when starting the container

With embedded-localstack, this can be handled by adding the env var to the Spring Boot test properties or by passing it through the EmbeddedLocalStackBootstrapConfiguration:

// In your Spring Boot test, expose the token to the container:
// Set LOCALSTACK_AUTH_TOKEN in your environment before running tests,
// or add it to your application-test.properties / docker env config

Alternatively, users can override the image via the property:

embedded.localstack.dockerImage=localstack/localstack:4.14.0

but the auth token requirement applies to all tags from March 23 onward.

The good news: A free tier is staying. CI credits are now unlimited on all plans, including free, and open-source projects can apply for free access to paid plans.

Full details in our announcements:

Happy to help with any doc updates, review PRs, or answer questions. Let us know if there's anything we can do to make this transition easier — and thanks for maintaining embedded-localstack for the Spring Boot community! 🙏

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions