DOC-404: Document orphaned containers after Docker Compose stop

[quetzalliwrites]

Summary

• Add an FAQ entry explaining why some containers (including k3d containers backing an EKS cluster) can be left behind after stopping LocalStack with Docker Compose, and how to raise stop_grace_period to avoid it.
• Add a cross-referencing note in the EKS docs, where k3d-backed cluster creation is introduced, pointing to the new FAQ entry.

Linear ticket

https://linear.app/localstack/issue/DOC-404/doc-faq-addition-of-why-are-some-containers-left-behind-after-i-stop

Test plan

• npx astro build completes successfully (401 pages built)
• Link validator confirms all internal links, including the new cross-link anchor between eks.mdx and faq.mdx, are valid

[cloudflare-workers-and-pages]

Deploying localstack-docs with    Cloudflare Pages

Latest commit:	81124a6
Status:	✅  Deploy successful!
Preview URL:	https://f33bed34.localstack-docs.pages.dev
Branch Preview URL:	https://doc-404-doc-faq-addition-of.localstack-docs.pages.dev

View logs

[quetzalliwrites]

@nik-localstack @pinzon heads up, looks like this PR is still pending eng review

[nik-localstack]

Thanks for putting this together, the entry describes a real problem, and it came up in an internal discussion recently too.

Some things from that are worth folding in:

• There's a second setting involved, and it isn't in our docs. Alongside docker-compose stop_grace_period, LocalStack applies its own SHUTDOWN_TIMEOUT (5 seconds by default) to its cleanup, and that one runs out first. Raising only stop_grace_period doesn't give the cleanup more time and it has a side effect worth warning about: docker compose stop then takes the full three minutes before the container exits, whereas raising both settings gets a clean shutdown in well under a minute. The inline suggestions reflect that.SHUTDOWN_TIMEOUT isn't listed in the configuration reference today, so this entry would be the first place we mention it. We should probably expose it in the configuration page.
• It isn't only EKS. The same shutdown budget is shared by every service that manages containers. ECS is the closest example, where a task's own stop timeout can consume the entire budget by itself.

I think we need more eyes before merging: shutdown behavior is being actively discussed internally right now, and how these settings interact may change. I don't think that blocks the changes but we should consider what should be advertised as a permanent solution and what not.

cc @purcell who was involved in this discussion about shutdown

btw I have added some inline suggestions but it may not be what we want to document in the end, so feel free to disregard them.

[quetzalliwrites]

Hey @purcell we need confirmation from ENG about whether this docs ticket request is still needed or if it's been cancelled, per @nik-localstack earlier Q:
#894 (review)

If you're not the right person to confirm, can you let us know who is? thx !

[quetzalliwrites]

Thanks @nik-localstack, while we wait confirmation on whether this ticket is cancelled, I still went ahead and pushed ca6574be applying all six suggestions:

• Generalized the FAQ entry away from EKS/k3d specifics (Lambda, ECS, RDS, and EKS all start auxiliary containers); kept the k3d-specific framing in the EKS doc's cross-referencing note instead.
• Explained both timing windows that can cause orphaned containers — Docker Compose's stop_grace_period and LocalStack's own SHUTDOWN_TIMEOUT — and noted they need to be raised together.
• Clarified the CLI callout refers to lstk specifically, not the legacy localstack CLI.
• Fixed the cleanup instruction to say how to find the containers (docker ps) before removing them.

One thing worth double-checking before merge (independent of the cancellation question): I couldn't find SHUTDOWN_TIMEOUT documented in src/content/docs/aws/customization/configuration-options.md to independently verify the name/default — applied your suggestion as given, but flagging in case it's worth a cross-check or a follow-up to add it to the config reference too.

[purcell]

This is all accurate and reasonable, so approving this in principle, with the few proposed edits below to fix some formatting and idioms.