`localstack/localstack:latest` will require auth token from March 23 — LocalStack module docs & examples need updating

[HarshCasper]

Problem

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 library.

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:

The LocalStackContainer in src/Testcontainers.LocalStack pulls localstack/localstack by default to spin up the container during tests. Any user who instantiates LocalStackContainer after March 23 without a LOCALSTACK_AUTH_TOKEN set will hit an authentication error and their tests will fail immediately.

The places most likely to need updating:

• The LocalStack module docs (docs/api/localstack.md) and any related examples, which don't currently mention auth token setup as a prerequisite
• The LocalStackBuilder in src/Testcontainers.LocalStack, where passing LOCALSTACK_AUTH_TOKEN as an environment variable should be documented or facilitated
• The CI/CD pipeline (.github/workflows/cicd.yml) if it runs LocalStack-based tests without an auth token

Solution

What users will need to do:

1. Sign up for a free LocalStack account at [localstack.cloud](https://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-dotnet, this would look like:

var localstack = new LocalStackBuilder()
  .WithEnvironment("LOCALSTACK_AUTH_TOKEN", Environment.GetEnvironmentVariable("LOCALSTACK_AUTH_TOKEN") ?? string.Empty)
  .Build();

await localstack.StartAsync();

Benefit

The good news: A free tier is staying — no one has to pay. CI credits are now unlimited on all plans, including free, and open-source projects like this one 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 easier — and thanks for maintaining the LocalStack module for the .NET community! 🙏

Alternatives

Permanently pin the LocalStack version so that no Auth Token is required.

Would you like to help contributing this enhancement?

No

[coderabbitai]

🔗 Related PRs

#1576 - feat: Support configuring Docker API version [merged]
#1605 - docs: Pin the image version explicitly [merged]
#1606 - chore: Set remaining container image explicit [merged]
#1609 - feat: Add Docker Engine v29 support [merged]
#1624 - fix(EventHubs): Workaround health API timeout [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[HofmeisterAn]

@HarshCasper Thanks for the heads-up. From which version onward will this breaking change apply, starting with v5? If so, we can raise an appropriate error, inform users what they need to do, and point them to the correct docs and guidelines. We don't recommend users use the latest tag.

[HarshCasper]

Hi @HofmeisterAn — A new version of LocalStack will go out next week. Once it's out, any user using localstack/localstack will have to input their Auth token. Previous versions (4.14 and older) of LocalStack for AWS will be unaffected. We are also switching from CalVer to SemVer. I'll keep you posted once the new version is out.