AWS AmazonECS documentation change
Summary
Expanded documentation about service throttle logic with clearer structure, added resolution steps, and detailed failure scenarios. Reorganized content into sections with bullet points and explicit guidance.
Security assessment
The changes improve documentation clarity and operational guidance but don't address specific security vulnerabilities. The throttle logic described is a reliability/cost control mechanism rather than a security feature. While it mentions permission-related failures (e.g., image pull permissions), this is part of normal error documentation rather than addressing a security flaw.
Diff
diff --git a/AmazonECS/latest/developerguide/service-throttle-logic.md b/AmazonECS/latest/developerguide/service-throttle-logic.md index e1f91a22d..be2cb1edc 100644 --- a//AmazonECS/latest/developerguide/service-throttle-logic.md +++ b//AmazonECS/latest/developerguide/service-throttle-logic.md @@ -4,0 +5,2 @@ +Resolving throttling issues + @@ -7 +9,14 @@ -The Amazon ECS service scheduler includes logic that throttles how often service tasks are launched if they repeatedly fail to start. +The Amazon ECS service scheduler includes protective logic that throttles task launches when tasks repeatedly fail to start. This helps prevent unnecessary resource consumption and reduces costs. + +When tasks in a service fail to transition from `PENDING` to `RUNNING` state and instead move directly to `STOPPED`, the scheduler: + + * Incrementally increases the time between restart attempts + + * Continues increasing delays up to a maximum of 27 minutes between attempts + + * Generates a service event message to notify you of the issue + + + + +###### Note @@ -9 +24,3 @@ The Amazon ECS service scheduler includes logic that throttles how often service -If tasks for a service repeatedly fail to enter the `RUNNING` state (progressing directly from a `PENDING` to a `STOPPED` status), then the time between subsequent restart attempts is incrementally increased up to a maximum of 27 minutes. This maximum period is subject to change in the future. This behavior reduces the effect that failing tasks have on your Amazon ECS cluster resources or Fargate infrastructure costs. If your service initiates the throttle logic, you receive the following [service event message](./service-event-messages-list.html#service-event-messages-5): +The maximum delay period of 27 minutes may change in future updates. + +When throttling is activated, you receive this service event message: @@ -14 +31,12 @@ If tasks for a service repeatedly fail to enter the `RUNNING` state (progressing -Amazon ECS doesn't ever stop a failing service from retrying. It also doesn't attempt to modify it in any way other than increasing the time between restarts. The service throttle logic doesn't provide any user-tunable parameters. +Important characteristics of the throttle logic: + + * Services continue retry attempts indefinitely + + * The only modification is the increased time between restarts + + * There are no user-configurable parameters + + + + +## Resolving throttling issues @@ -16 +44 @@ Amazon ECS doesn't ever stop a failing service from retrying. It also doesn't at -If you update your service to use a new task definition, your service returns to a normal, non-throttled state immediately. For more information, see [Updating an Amazon ECS service](./update-service-console-v2.html). +To resolve throttling, you can: @@ -18 +46 @@ If you update your service to use a new task definition, your service returns to -The following are some common causes that initiate this logic. We recommend that you take manual action to address the issue: + * Update the service to use a new task definition, which immediately returns the service to normal, non-throttled operation. For more information, see [Updating an Amazon ECS service](./update-service-console-v2.html). @@ -20 +48 @@ The following are some common causes that initiate this logic. We recommend that - * A lack of resources to host your task with, such as ports, memory, or CPU units in your cluster. In this case, you also see the [insufficient resource service event message](./service-event-messages-list.html#service-event-messages-1). + * Address the underlying cause of the task failures. @@ -22 +49,0 @@ The following are some common causes that initiate this logic. We recommend that - * The Amazon ECS container agent can't pull your task Docker image. This might be because a bad container image name, image, or tag, or a lack of private registry authentication or permissions. In this case, you also see `CannotPullContainerError` in your [stopped task errors](./stopped-task-errors.html). @@ -24 +51,19 @@ The following are some common causes that initiate this logic. We recommend that - * Insufficient disk space on your container instance to create the container. In this case, you also see `CannotCreateContainerError` in your [stopped task errors](./stopped-task-errors.html). For more information, see [Troubleshoot the Docker API error (500): devmapper in Amazon ECS](./CannotCreateContainerError.html). + + +Common causes of task failures that trigger throttling include: + + * Insufficient cluster resources (ports, memory, or CPU) + + * Indicated by an [insufficient resource service event message](./service-event-messages-list.html#service-event-messages-1) + + * Container image pull failures + + * Can be caused by invalid image names, tags, or insufficient permissions + + * Results in `CannotPullContainerError` in [Viewing Amazon ECS stopped task errors](./stopped-task-errors.html) + + * Insufficient disk space + + * Results in `CannotCreateContainerError` in [stopped task errors](./stopped-task-errors.html) + + * For resolution steps, see [Troubleshoot the Docker API error (500): devmapper in Amazon ECS](./CannotCreateContainerError.html) @@ -31 +76,10 @@ The following are some common causes that initiate this logic. We recommend that -Tasks that are stopped after they reach the `RUNNING` state don't start the throttle logic or the associated service event message. For example, assume that failed Elastic Load Balancing health checks for a service cause a task to be flagged as unhealthy, and Amazon ECS deregisters it and stops the task. At this point, the tasks aren't throttled. Even if a task's container command immediately exits with a non-zero exit code, the task already moved to the `RUNNING` state. Tasks that fail immediately because command errors don't cause the throttle or the service event message. +The following scenarios do NOT trigger throttle logic: + + * Tasks that stop after reaching `RUNNING` state + + * Tasks stopped due to failed Elastic Load Balancing health checks + + * Tasks where the container command exits with a non-zero code after reaching `RUNNING` state + + +