[localstack] LocalStack image requires authentication from March 23, 2026

[HarshCasper]

Hey folks 👋

I'm Harsh from the LocalStack team. Wanted to flag an upcoming change that will directly affect users of the LocalStack module in this crate.

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:

Any user who instantiates LocalStack::default() after March 23 without a LOCALSTACK_AUTH_TOKEN set will hit an authentication error and the container will fail to start.

The places most likely to need updating:

• src/localstack/mod.rs — LOCALSTACK_AUTH_TOKEN should be passed as an environment variable
• Module docs / README — auth token setup should be listed as a prerequisite
• CI/CD workflows — any workflow running LocalStack::default() in tests needs the token injected as a secret

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 testcontainers-rs, this would look like:

use testcontainers::runners::AsyncRunner;
use testcontainers_modules::localstack::LocalStack;
use std::env;

#[tokio::test]
async fn test_with_localstack() {
    let request = LocalStack::default()
        .with_env_var("LOCALSTACK_AUTH_TOKEN", env::var("LOCALSTACK_AUTH_TOKEN").unwrap_or_default());
    let container = request.start().await.unwrap();
    // your test code here
}

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:

• https://blog.localstack.cloud/the-road-ahead-for-localstack/
• https://blog.localstack.cloud/localstack-single-image-next-steps/
• https://blog.localstack.cloud/2026-upcoming-pricing-changes/

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 the LocalStack module for the Rust community! 🙏

[DDtKey]

Hi Harsh 👋

Thanks for sharing the details, that's really helpful to maintain the modules in working state!

I believe we need to:

• Update the tag
• Document LOCALSTACK_AUTH_TOKEN
• Ideally, we can introduce a method, like .with_auth_from_env as an alias that most likely will cover most of the needs. It will simply pass-through the env var env::var("LOCALSTACK_AUTH_TOKEN")
  • for custom env-variables and different configuration approaches, users always can rely on existing with_env_var

Actually very similar to

testcontainers-rs-modules-community/src/localstack/pro.rs

Lines 42 to 55 in c4b8d84

	/// Create new [`LocalStackPro`](LocalStackPro) container instance using the
	/// [auth token](https://docs.localstack.cloud/getting-started/auth-token/)
	/// from the local `LOCALSTACK_AUTH_TOKEN` environment variable
	pub fn from_env() -> Self {
	Self::with_auth_token(std::env::var("LOCALSTACK_AUTH_TOKEN").ok())
	}
	/// Create new [`LocalStackPro`](LocalStackPro) container instance using the
	/// specified (optional) [auth token](https://docs.localstack.cloud/getting-started/auth-token/)
	pub fn with_auth_token(auth_token: Option<impl Into<String>>) -> Self {
	Self {
	auth_token: auth_token.map(Into::into),
	}
	}

Perhaps we should simply unify and have only 1 image definition now

[DDtKey]

Any user who instantiates LocalStack::default() after March 23 without a LOCALSTACK_AUTH_TOKEN set will hit an authentication error and the container will fail to start.

Is that the case even for pinned 4.5 version? Is it gonna be rewritten?

[HarshCasper]

Hi @DDtKey — Previous versions are not going to be rewritten. They can be used without authentication. This is for all the upcoming versions of LocalStack for AWS (including anyone using the latest tag).

[vieiralucas]

fakecloud could work as an alternative module here. Written in Rust, runs on port 4566, no auth token needed. Conformance tested against the AWS Smithy models.

Docker image at ghcr.io/faiscadev/fakecloud, or it can run as a standalone binary without Docker. Happy to contribute a fakecloud module — being a Rust project itself, it feels like a natural fit for the Rust testcontainers ecosystem.

@DDtKey if you think that makes sense, I'll be happy to contribute that.

Disclosure: I'm the author of fakecloud.

[DDtKey]

@vieiralucas I certainly don’t mind creating a separate module for that.
It's mostly community-driven set of modules

They can coexist under separate features, allowing users to make a choice.

[vieiralucas]

@DDtKey opened a PR: #467

Let me know if anything needs adjusting!