From ef16f22de32af158c740943465e9bf973f22427a Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Tue, 25 Aug 2026 20:55:05 +0200 Subject: [PATCH 1/2] DOC-404: Document orphaned containers after Docker Compose stop Add an FAQ entry explaining that Docker Compose's default 10s SIGTERM-to-SIGKILL grace period can be too short for LocalStack to finish tearing down auxiliary containers (including k3d containers backing an EKS cluster), leaving them behind as orphans, and how to raise stop_grace_period to avoid it. The CLI is not affected since it waits for shutdown to finish. Cross-link the same behavior from the EKS docs where k3d-backed cluster creation is introduced. --- src/content/docs/aws/getting-started/faq.mdx | 21 ++++++++++++++++++++ src/content/docs/aws/services/eks.mdx | 4 ++++ 2 files changed, 25 insertions(+) diff --git a/src/content/docs/aws/getting-started/faq.mdx b/src/content/docs/aws/getting-started/faq.mdx index d394245bb..9d6b4aeb4 100644 --- a/src/content/docs/aws/getting-started/faq.mdx +++ b/src/content/docs/aws/getting-started/faq.mdx @@ -154,6 +154,27 @@ For example, a container which attempts to deploy a stack and interact with the Refer to our [network troubleshooting guide](/aws/customization/networking/) covering several scenarios. +### Why are some containers left behind after I stop LocalStack with Docker Compose? + +When LocalStack shuts down, it cleans up the auxiliary containers it started, including k3d containers that back an EKS cluster. + +Docker Compose sends `SIGTERM` to the container and then, after a grace period of 10 seconds, follows up with `SIGKILL`. +That default window might be too short for LocalStack to finish its cleanup in some scenarios, so it is killed mid-teardown and the containers survive as orphans. + +To give LocalStack enough time to shut down cleanly, raise `stop_grace_period` on the LocalStack service in your `docker-compose.yml` (for example, `3m`): + +```yaml +services: + localstack: + image: localstack/localstack-pro:latest + stop_grace_period: 3m + # ... +``` + +If a previous run already left containers behind, remove them before starting LocalStack again. + +This applies to Docker Compose specifically. Starting LocalStack with the CLI is not affected, as the CLI waits for LocalStack to finish shutting down. + ### How to resolve the pull rate limit issue for LocalStack's Docker image? If you receive `ERROR: toomanyrequests: Too Many Requests.` when pulling the LocalStack Docker image, you have reached your pull rate limit. diff --git a/src/content/docs/aws/services/eks.mdx b/src/content/docs/aws/services/eks.mdx index e09fccda5..4e57cd16b 100644 --- a/src/content/docs/aws/services/eks.mdx +++ b/src/content/docs/aws/services/eks.mdx @@ -102,6 +102,10 @@ K3D_START_LB_INGRESS=1 ``` ::: +:::note +If you run LocalStack with Docker Compose, the k3d containers backing an EKS cluster can be left behind as orphans if LocalStack is killed before it finishes shutting down. See [Why are some containers left behind after I stop LocalStack with Docker Compose?](/aws/getting-started/faq/#why-are-some-containers-left-behind-after-i-stop-localstack-with-docker-compose) for the cause and how to configure `stop_grace_period` to avoid it. +::: + You can create a new cluster using the [`CreateCluster` API](https://docs.aws.amazon.com/eks/latest/APIReference/API_CreateCluster.html). Run the following command: From ca6574bedcdc38dbf3cde67ac8be81da204cfbdf Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Tue, 1 Sep 2026 22:53:51 +0200 Subject: [PATCH 2/2] DOC-404: Apply nik's review suggestions on the orphaned-containers FAQ - Generalize the FAQ entry away from EKS/k3d specifics (Lambda, ECS, RDS, and EKS all start auxiliary containers); keep the k3d-specific framing in the EKS doc's cross-referencing note instead. - Explain both timing windows that can cause orphaned containers: Docker Compose's stop_grace_period and LocalStack's own SHUTDOWN_TIMEOUT, and note both need to be raised together. - Clarify the CLI callout refers to lstk specifically, not the legacy localstack CLI. - Fix the cleanup instruction to actually say how to find the containers (docker ps) before removing them. --- src/content/docs/aws/getting-started/faq.mdx | 13 ++++++++----- src/content/docs/aws/services/eks.mdx | 2 +- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/src/content/docs/aws/getting-started/faq.mdx b/src/content/docs/aws/getting-started/faq.mdx index 9d6b4aeb4..ea5b3e32b 100644 --- a/src/content/docs/aws/getting-started/faq.mdx +++ b/src/content/docs/aws/getting-started/faq.mdx @@ -156,10 +156,9 @@ Refer to our [network troubleshooting guide](/aws/customization/networking/) cov ### Why are some containers left behind after I stop LocalStack with Docker Compose? -When LocalStack shuts down, it cleans up the auxiliary containers it started, including k3d containers that back an EKS cluster. +When LocalStack shuts down, it cleans up the auxiliary containers it started for services such as Lambda, ECS, RDS or EKS. If it is stopped before that cleanup finishes, those containers are left running. -Docker Compose sends `SIGTERM` to the container and then, after a grace period of 10 seconds, follows up with `SIGKILL`. -That default window might be too short for LocalStack to finish its cleanup in some scenarios, so it is killed mid-teardown and the containers survive as orphans. +By default, LocalStack gets only a few seconds. Docker Compose sends `SIGTERM` to the container and follows up with `SIGKILL` once `stop_grace_period` expires (10 seconds by default), and LocalStack stops waiting for its own cleanup after `SHUTDOWN_TIMEOUT` (5 seconds by default). Whichever window runs out first, LocalStack is stopped mid-cleanup and the containers survive as orphans. Cleanup that takes longer than a few seconds is the most likely to be cut short. To give LocalStack enough time to shut down cleanly, raise `stop_grace_period` on the LocalStack service in your `docker-compose.yml` (for example, `3m`): @@ -168,12 +167,16 @@ services: localstack: image: localstack/localstack-pro:latest stop_grace_period: 3m + environment: + - SHUTDOWN_TIMEOUT=180 # ... ``` -If a previous run already left containers behind, remove them before starting LocalStack again. +Raise them together. If you raise only `stop_grace_period`, LocalStack still gives up on its cleanup after 5 seconds and the container then stays up until the grace period runs out, so every docker compose stop waits the full three minutes. + +If a previous run already left containers behind, run docker ps and remove the ones LocalStack started before starting it again. -This applies to Docker Compose specifically. Starting LocalStack with the CLI is not affected, as the CLI waits for LocalStack to finish shutting down. +This applies to Docker Compose specifically. Starting LocalStack with `lstk` is not affected, as `lstk` waits for LocalStack to finish shutting down. ### How to resolve the pull rate limit issue for LocalStack's Docker image? diff --git a/src/content/docs/aws/services/eks.mdx b/src/content/docs/aws/services/eks.mdx index 4e57cd16b..ffb18b2f9 100644 --- a/src/content/docs/aws/services/eks.mdx +++ b/src/content/docs/aws/services/eks.mdx @@ -103,7 +103,7 @@ K3D_START_LB_INGRESS=1 ::: :::note -If you run LocalStack with Docker Compose, the k3d containers backing an EKS cluster can be left behind as orphans if LocalStack is killed before it finishes shutting down. See [Why are some containers left behind after I stop LocalStack with Docker Compose?](/aws/getting-started/faq/#why-are-some-containers-left-behind-after-i-stop-localstack-with-docker-compose) for the cause and how to configure `stop_grace_period` to avoid it. +If you run LocalStack with Docker Compose, the k3d containers backing an EKS cluster can be left behind as orphans if LocalStack is killed before it finishes shutting down. See [Why are some containers left behind after I stop LocalStack with Docker Compose?](/aws/getting-started/faq/#why-are-some-containers-left-behind-after-i-stop-localstack-with-docker-compose) for the cause and how to configure `stop_grace_period` and `SHUTDOWN_TIMEOUT` to avoid it. ::: You can create a new cluster using the [`CreateCluster` API](https://docs.aws.amazon.com/eks/latest/APIReference/API_CreateCluster.html).