Topic lessonTopic: Containers, ECS and Fargate
ECS health checks explained: task health, ALB targets and startup failures
RUNNING describes execution; HEALTHY reports a configured check. Neither alone proves a successful user operation. ECS container checks also differ from ALB checks. Use fixed report-API examples to identify what each observation establishes and which evidence to inspect next.
Separate lifecycle, container checks, ALB and business results; explain UNKNOWN aggregation, startup grace and a diagnostic order based on stop reasons.
A task is an execution unit; a service maintains executions toward a desired count. An ALB routes requests to targets. These are normalized teaching records, not live AWS logs. No account or secret input is needed.
Distinguish running from usable by the observation point
| Observation | What it checks | What it does not establish alone |
|---|---|---|
| Task RUNNING | Task lifecycle state. | Container-check results or user HTTP responses. |
| Container HEALTHY | Success of the command configured in the task definition. | Reachability from the ALB or every business operation. |
| ALB target healthy | Check response for a configured target, path and other settings. | Authenticated operations or correctness of saved data. |
| User business result | An outcome for that input, path and time. | Other inputs or continued future success. |
A container health check is a command executed inside the container; its tools must exist in the image. Success on localhost does not establish success through the ALB’s port, path or network route. ECS monitors checks specified in the task definition, rather than automatically monitoring a check present only in an image’s Dockerfile.
Read task health from two container checks
Aggregation example: API A and helper B belong to one task; both are essential and have checks in the task definition. Essential marks a container as required for the task. A is HEALTHY and B is UNKNOWN. Another helper C is nonessential and UNHEALTHY. Lifecycle is RUNNING; ALB and user responses are uncollected.
- A: HEALTHY → Task: UNKNOWNInclude A check state
- B: UNKNOWN → Task: UNKNOWNInclude B check state
- A: HEALTHY
- Essential; check in definition
- B: UNKNOWN
- Essential; check in definition
- Task: UNKNOWN
- Separate from RUNNING
| A | B | Task health |
|---|---|---|
| HEALTHY | HEALTHY | HEALTHY |
| HEALTHY | UNKNOWN | UNKNOWN |
| HEALTHY | UNHEALTHY | UNHEALTHY |
| UNKNOWN | UNHEALTHY | UNHEALTHY |
Aggregation checks UNHEALTHY first, then UNKNOWN. This example is UNKNOWN because B is UNKNOWN. C is excluded from this aggregation, but that does not prove its helper function is unaffected. UNKNOWN can mean evaluation in progress, no configured check or unavailable status; it is neither proven health nor confirmed downtime.
An agent disconnect does not by itself make a container UNHEALTHY. The last received health value can remain displayed. Check when and from where a HEALTHY observation was received, rather than treating it as a newly completed check.
Distinguish the two startup grace settings
Retries configures the consecutive failures used to determine unhealthy status. Read startup grace separately from failure counts to distinguish bootstrap failures from continuing failures.
| Setting | Scope | Do not confuse it with |
|---|---|---|
| Container startPeriod | Controls how bootstrap check failures count toward retries. | It does not mean checks never run during this period. |
| Service healthCheckGracePeriodSeconds | The scheduler ignores unhealthy LB, VPC Lattice and container checks after startup for this period. | It does not change the check result or repair the application. |
Startup example: startPeriod is 30 seconds; a check succeeds at second 10 and fails at second 20. After an early success, subsequent failures count toward retries even within startPeriod. This alone does not establish immediate UNHEALTHY; inspect actual checks, failure counts and retries. These times are teaching values, not universal AWS recommendations.
Read an ALB failure with its configuration and response
| Record | Value |
|---|---|
| ECS task health | HEALTHY |
| ALB target health / reason | unhealthy / Target.ResponseCodeMismatch |
| ALB check configuration | HTTP; port 8080; /healthz; success code 200 |
| Observed check response | 404 |
| User business outcome | Uncollected |
This ALB example records a mismatch between expected 200 and observed 404. First compare intended path, port and protocol with the actual responder and application behavior. A response-code mismatch differs from a timeout. Do not call it fixed merely by allowing all traffic or accepting 404; establish what the check should validate.
A healthy ALB check does not establish correct user operations or database writes. ALB can also fail open when all targets are unhealthy, so unhealthy does not prove user traffic can never arrive. Check target health separately from actual requests and business outcomes.
Separate startup failure from post-start health failure
| Observation | Evidence to inspect next | Avoid assuming |
|---|---|---|
| Never reaches RUNNING or becomes STOPPED | Match task stopCode, stoppedReason, container reason and service events. | Not every failure is insufficient health-check grace. |
| Image retrieval or initialization failure | Inspect revision, execution role, image reference and required connectivity. | Broad application task-role permissions are not a universal fix. |
| Container check failure | Inspect command, tools in the image, startup logs, time and configuration. | Localhost success is not ALB-path success. |
| ALB target check failure | Inspect reason code, registration/AZ, target settings, path and response. | ResponseCodeMismatch is not the same as a timeout. |
- Match service, task ID, task-definition revision and observation time.
- Check whether RUNNING was reached; inspect the same task’s stop reasons.
- Inspect configured checks, essential flags and individual container results.
- Separate ALB configuration, target state and reasons from local checks.
- Distinguish startup time from cause; recheck comparable conditions after a correction.
- Verify user requests and outcomes, then consider deployment counts and recovery.
Check what is observed and what remains unknown
Choose an option to see the result and explanation.
Check, then explain in your own words
- Explain the eligible A/B checks and UNKNOWN result.
- Distinguish startup grace settings using the startup example.
- Compare ALB configuration with its response and verify user outcomes separately.
Check your understanding: What should you distinguish when a RUNNING task fails ALB checks?
Match lifecycle, local container checks, ALB configuration/responses and user outcomes by revision, target and time.
Each observation checks a different condition. One healthy label does not establish end-to-end success; investigate evidence relevant to the reported failure.
Sources and conditions checked
The official references used in this lesson are collected here with their scope, conditions and corresponding sections. Independent expert review and live AWS comparison have not been performed.
- Amazon ECS task lifecycleChecked:
Scope and conditionsTask lifecycle states are distinct from application health and request success. Documentation review, not live AWS verification.
Used in this lessonDistinguish running from usable by the observation point
Scope and conditionsTask-definition health checks versus lifecycle, LB and application observations. Documentation review, not live AWS verification.
Used in this lessonDistinguish running from usable by the observation point Read task health from two container checks Distinguish the two startup grace settings Separate startup failure from post-start health failure Check what is observed and what remains unknown
Scope and conditionsMatch target settings, matcher and reason; separate fail-open behavior from business outcomes. Documentation review, not live AWS verification.
Used in this lessonDistinguish running from usable by the observation point Read an ALB failure with its configuration and response Separate startup failure from post-start health failure Check what is observed and what remains unknown
Scope and conditionsScope of unhealthy checks ignored after service-task startup; distinguish container startPeriod and actual check success. Documentation review, not live AWS verification.
Used in this lessonDistinguish the two startup grace settings
Scope and conditionsMatch task stopCode, stoppedReason, container reason and service events; history visibility is bounded. Documentation review, not live AWS verification.
Used in this lessonSeparate startup failure from post-start health failure
Scope and conditionsService events as a diagnostic starting point; bounded history and API/console differences. Documentation review, not live AWS verification.
Used in this lessonSeparate startup failure from post-start health failure