# Amazon ECS

ARNscope opens an ECS service where an incident starts: is the rollout healthy? One page shows the service's deployments and events, its CPU and memory, every task with its containers and stop reason, and each container's logs, with a server-side search and a live tail. Changes are rare and deliberate: a deploy always asks first.

<figure class="doc-video">
<video controls playsinline preload="none" poster="/media/docs/ecs/ecs-explainer.webp?v=1" aria-label="ECS in ARNscope: a narrated tour of about seventy seconds">
<source src="/media/docs/ecs/ecs-explainer.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-explainer.mp4?v=1" type="video/mp4">
<track kind="captions" srclang="en" label="English" src="/media/docs/ecs/ecs-explainer.vtt?v=1" default>
</video>
<figcaption>A narrated tour of about seventy seconds, with captions: a rollout, warnings and utilization, a stopped task, its logs, split view and a deploy. Sample data.</figcaption>
</figure>

## Clusters and services

Open **ECS** in ARNscope and choose the profile and region. The list shows every cluster with its service count and running and pending tasks; expand a cluster to see its services, each with running over desired tasks. Type in the filter to narrow clusters and services by name.

Select a service to open it. The header shows its status (for example **Deploying** or **Degraded**), the task definition revision and the cluster, then a strip with running, desired, pending and failed tasks, the capacity provider or launch type, the rollout state and the number of deployments.

| Tab | What it shows |
| --- | --- |
| **Overview** | Recent warnings, deployments, utilization, load balancing, network and configuration |
| **Tasks** | Running or recently stopped tasks, and a task pane with details, containers and logs |
| **Events** | The service's latest events, newest first |
| **Network** | Who the service talks to, from VPC flow logs |
| **Task definition** | The revision the service runs |

## Deployments

**Deployments** lists each deployment with its role (**Primary** or **Active**), its rollout state, the revision, when it started and was last updated, a bar of running and pending tasks against desired, and the failed count. During a rollout you see the new revision coming up beside the old one draining, with ECS's own message under each.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/ecs/ecs-rollout.webp?v=1" aria-label="Opening checkout-api mid-rollout: the strip says Rollout In progress, and two deployments show revision 187 coming up and 186 completed.">
<source src="/media/docs/ecs/ecs-rollout.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-rollout.mp4?v=1" type="video/mp4">
</video>
<figcaption>A rollout in progress: the new revision's tasks coming up beside the previous deployment.</figcaption>
</figure>

## Warnings and events

Warnings from the last 24 hours sit at the top of the Overview, such as failing load balancer health checks or unhealthy targets. **All events** opens the **Events** tab, which lists the latest events newest first. Filter them by text, or tick **Warnings only**; the tab's badge counts the warnings.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/ecs/ecs-events.webp?v=1" aria-label="search-api's recent warnings on the Overview, then the Events tab filtered to warnings only.">
<source src="/media/docs/ecs/ecs-events.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-events.mp4?v=1" type="video/mp4">
</video>
<figcaption>Recent warnings first; the Events tab keeps the history.</figcaption>
</figure>

## Utilization

**Utilization** charts CPU and memory (average and maximum across the service's tasks) and, when Container Insights is on for the cluster, the running task count. The data is CloudWatch's `AWS/ECS` metrics; choose the last 3 or 24 hours. A service whose memory climbs until tasks restart shows it as a sawtooth.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/ecs/ecs-metrics.webp?v=1" aria-label="search-api's CPU and memory charts, memory climbing in a sawtooth, then the 24-hour range.">
<source src="/media/docs/ecs/ecs-metrics.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-metrics.mp4?v=1" type="video/mp4">
</video>
<figcaption>Memory climbing to the limit and dropping as tasks restart.</figcaption>
</figure>

## Tasks

**Tasks** lists the service's running tasks, or with **Stopped** the ones that stopped recently (ECS keeps stopped tasks for about an hour). Filter by task id, IP address, availability zone or stop reason. Select a task to open its pane:

- **Details**: status and health, the stop code and reason for a stopped task, its lifecycle (created, started, stopped, how long it ran), placement and attachments.
- **Containers**: each container's image and digest, health, exit code and reason, CPU and memory, private IP and ports.
- **Logs**: the container's log stream; see below.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/ecs/ecs-stopped-task.webp?v=1" aria-label="Stopped tasks of search-api; one stopped with EssentialContainerExited, and its container exited with code 137, out of memory.">
<source src="/media/docs/ecs/ecs-stopped-task.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-stopped-task.mp4?v=1" type="video/mp4">
</video>
<figcaption>Why a task stopped: the stop code, then the container's exit code and reason.</figcaption>
</figure>

## Container logs

The **Logs** tab reads the container's stream when its task definition uses the `awslogs` log driver with a stream prefix; ARNscope works out the stream name from the task id. Lines open newest first, 200 at a time, and **Load older** walks back through the stream. With several containers, pick one from the menu.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/ecs/ecs-task-logs.webp?v=1" aria-label="A running task's Logs tab: the newest lines first, then Load older.">
<source src="/media/docs/ecs/ecs-task-logs.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-task-logs.mp4?v=1" type="video/mp4">
</video>
<figcaption>Newest first; <strong>Load older</strong> continues back through the stream.</figcaption>
</figure>

To search, type a CloudWatch Logs filter pattern and press Enter, or click **Search warnings and errors**, which searches for common error and warning words. The search runs in CloudWatch Logs over that one stream, so it finds matches the loaded page does not hold.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/ecs/ecs-log-search.webp?v=1" aria-label="Searching the task's stream for warnings and errors, then for a quoted phrase.">
<source src="/media/docs/ecs/ecs-log-search.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-log-search.mp4?v=1" type="video/mp4">
</video>
<figcaption>Warnings and errors, or any filter pattern, searched on the server.</figcaption>
</figure>

For a running task, **Live tail** follows new lines as the container writes them. It uses CloudWatch Logs Live Tail, which AWS bills per minute, so it starts only when you click it and stops when you click again or leave the tab.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/ecs/ecs-live-tail.webp?v=1" aria-label="Turning on live tail for the container: new lines arrive, then the tail is stopped.">
<source src="/media/docs/ecs/ecs-live-tail.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-live-tail.mp4?v=1" type="video/mp4">
</video>
<figcaption>Live tail while the task runs; it is billed per minute, so it runs only while you watch.</figcaption>
</figure>

**Open in Logs** opens the container's log group on the [CloudWatch Logs](https://arnscope.com/docs/logs) page, on the same stream, for searches across streams, Logs Insights and favourites.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/ecs/ecs-open-in-logs.webp?v=1" aria-label="Open in Logs: the Logs page opens on /ecs/search-api at the task's stream.">
<source src="/media/docs/ecs/ecs-open-in-logs.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-open-in-logs.mp4?v=1" type="video/mp4">
</video>
<figcaption>From a task to its whole log group, on the same stream.</figcaption>
</figure>

## Split view

Drag a cluster or service from the list onto the right side of the window to open it beside the one you have. Each side keeps its own tab and selection, so you can watch a rollout on one service and the errors on another.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/ecs/ecs-split.webp?v=1" aria-label="Dragging search-api beside checkout-api to compare them side by side.">
<source src="/media/docs/ecs/ecs-split.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-split.mp4?v=1" type="video/mp4">
</video>
<figcaption>Two services side by side.</figcaption>
</figure>

## Deploying

**Deploy** offers **Force new deployment** (the same revision, new tasks) and **Deploy a revision…** (pick a registered revision). Either one opens a confirmation bar naming the service, cluster and profile; nothing changes until you click **Deploy now**. ARNscope then follows the rollout, refreshing the service every five seconds, until ECS reports it completed or failed (for up to 15 minutes).

**Edit task definition** edits the current revision as a form or as JSON, shows what changed, and registers it as a new revision with **Save revision**, or registers and deploys it with **Save & deploy**. Both ask first.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/ecs/ecs-deploy.webp?v=1" aria-label="Deploy, Force new deployment, the confirmation bar, Deploy now, and the notice following the rollout until it completes.">
<source src="/media/docs/ecs/ecs-deploy.webm?v=1" type="video/webm">
<source src="/media/docs/ecs/ecs-deploy.mp4?v=1" type="video/mp4">
</video>
<figcaption>A deploy asks first, then follows the rollout.</figcaption>
</figure>

## Permissions

| What | Actions |
| --- | --- |
| Clusters, services and tasks | `ecs:ListClusters`, `ecs:DescribeClusters`, `ecs:ListServices`, `ecs:DescribeServices`, `ecs:ListTasks`, `ecs:DescribeTasks` |
| Task definitions | `ecs:DescribeTaskDefinition`, `ecs:ListTaskDefinitions` |
| Utilization | `cloudwatch:GetMetricData` |
| Container logs | `logs:GetLogEvents`, `logs:FilterLogEvents`; live tail `logs:DescribeLogGroups`, `logs:StartLiveTail`, `logs:StopLiveTail` |
| Deploy | `ecs:UpdateService`; editing also `ecs:RegisterTaskDefinition` and `iam:PassRole` for the task's roles |
| Network | `ec2:DescribeNetworkInterfaces`, `ec2:DescribeFlowLogs`, and Logs Insights on the flow log group |

Use [the permission check](https://arnscope.com/docs/iam-permission-check) to see which your profile is missing. When your role is denied `ecs:UpdateService`, **Deploy** is disabled and says why.

## Limitations

- **No stop, scale or exec.** ARNscope does not stop tasks, change a service's desired count or open ECS Exec sessions.
- **`awslogs` only.** Container logs are shown for the `awslogs` driver with a stream prefix. FireLens, Splunk and other drivers ship logs elsewhere.
- **Recently stopped tasks only.** ECS returns stopped tasks for about an hour after they stop.
- **Task counts need Container Insights.** CPU and memory come from `AWS/ECS`; the running task chart needs Container Insights on the cluster.
- **Live tail costs money.** CloudWatch Logs Live Tail is billed per minute while it runs.

Source: https://arnscope.com/docs/ecs
