# Runtime coverage and troubleshooting for Amazon ECS clusters Coverage and troubleshooting for Amazon ECS clusters The runtime coverage for Amazon ECS clusters includes the tasks running on AWS Fargate and Amazon ECS container instances[1](#ecs-container-instance). For an Amazon ECS cluster that runs on Fargate, the runtime coverage is assessed at the task level. The ECS clusters runtime coverage includes those Fargate tasks that have started running after you have enabled Runtime Monitoring and automated agent configuration for Fargate (ECS only). By default, a Fargate task is immutable. GuardDuty will not be able to install the security agent to monitor containers on already running tasks. To include such a Fargate task, you must stop and start the task again. Make sure to check if the associated service is supported. For information about Amazon ECS container, see [Capacity creation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-capacity.html). **Topics** + [ ## Reviewing coverage statistics ](#ecs-review-coverage-statistics-ecs-runtime-monitoring) + [ ## Coverage status change with EventBridge notifications ](#ecs-runtime-monitoring-coverage-status-change) + [ ## Troubleshooting Amazon ECS-Fargate runtime coverage issues ](#ecs-runtime-monitoring-coverage-issues-troubleshoot) ## Reviewing coverage statistics The coverage statistics for the Amazon ECS resources associated with your own account or your member accounts is the percentage of the healthy Amazon ECS clusters over all the Amazon ECS clusters in the selected AWS Region. This includes the coverage for Amazon ECS clusters associated with both Fargate and Amazon EC2 instances. The following equation represents this as: *(Healthy clusters/All clusters)\$1100* ### Considerations + The coverage statistics for the ECS cluster include the coverage status of the Fargate tasks or ECS container instances associated with that ECS cluster. The coverage status of the Fargate tasks include tasks that either are in running state or have recently finished running. + In the **ECS clusters runtime coverage** tab, the **Container instances covered** field indicates the coverage status of the container instances associated with your Amazon ECS cluster. If your Amazon ECS cluster contains only Fargate tasks, the count appears as **0/0**. + If your Amazon ECS cluster is associated with an Amazon EC2 instance that doesn't have a security agent, the Amazon ECS cluster will also have an **Unhealthy** coverage status. To identify and troubleshoot the coverage issue for the associated Amazon EC2 instance, see [Troubleshooting Amazon EC2 runtime coverage issues](gdu-assess-coverage-ec2.md#ec2-runtime-monitoring-coverage-issues-troubleshoot) for Amazon EC2 instances. Choose one of the access methods to review the coverage statistics for your accounts. ------ #### [ Console ] + Sign in to the AWS Management Console and open the GuardDuty console at [https://console.aws.amazon.com/guardduty/](https://console.aws.amazon.com/guardduty/). + In the navigation pane, choose **Runtime Monitoring**. + Choose the **Runtime coverage** tab. + Under the **ECS clusters runtime coverage** tab, you can view the coverage statistics aggregated by the coverage status of each Amazon ECS cluster that is available in the **Clusters list** table. + You can filter the **Cluster list** table by the following columns: + **Account ID** + **Cluster Name** + **Agent management type** + **Coverage status** + If any of your Amazon ECS clusters have the **Coverage status** as **Unhealthy**, the **Issue** column includes additional information about the reason for the **Unhealthy** status. If you Amazon ECS clusters are associated with an Amazon EC2 instance, navigate to the **EC2 instance runtime coverage** tab and filter by the **Cluster name** field to view the associated **Issue**. ------ #### [ API/CLI ] + Run the [ListCoverage](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListCoverage.html) API with your own valid detector ID, current Region, and service endpoint. You can filter and sort the instance list using this API. + You can change the example `filter-criteria` with one of the following options for `CriterionKey`: + `ACCOUNT_ID` + `ECS_CLUSTER_NAME` + `COVERAGE_STATUS` + `MANAGEMENT_TYPE` + You can change the example `AttributeName` in `sort-criteria` with the following options: + `ACCOUNT_ID` + `COVERAGE_STATUS` + `ISSUE` + `ECS_CLUSTER_NAME` + `UPDATED_AT` The field gets updated only when either a new task gets created in the associated Amazon ECS cluster or there is change in the corresponding coverage status. + You can change the *max-results* (up to 50). + To find the `detectorId` for your account and current Region, see the **Settings** page in the [https://console.aws.amazon.com/guardduty/](https://console.aws.amazon.com/guardduty/) console, or run the [https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListDetectors.html](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListDetectors.html) API. ``` aws guardduty --region us-east-1 list-coverage --detector-id 12abc34d567e8fa901bc2d34e56789f0 --sort-criteria '{"AttributeName": "ECS_CLUSTER_NAME", "OrderBy": "DESC"}' --filter-criteria '{"FilterCriterion":[{"CriterionKey":"ACCOUNT_ID", "FilterCondition":{"EqualsValue":"111122223333"}}] }' --max-results 5 ``` + Run the [GetCoverageStatistics](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_GetCoverageStatistics.html) API to retrieve coverage aggregated statistics based on the `statisticsType`. + You can change the example `statisticsType` to one of the following options: + `COUNT_BY_COVERAGE_STATUS` – Represents coverage statistics for ECS clusters aggregated by coverage status. + `COUNT_BY_RESOURCE_TYPE` – Coverage statistics aggregated based on the type of AWS resource in the list. + You can change the example `filter-criteria` in the command. You can use the following options for `CriterionKey`: + `ACCOUNT_ID` + `ECS_CLUSTER_NAME` + `COVERAGE_STATUS` + `MANAGEMENT_TYPE` + `INSTANCE_ID` + To find the `detectorId` for your account and current Region, see the **Settings** page in the [https://console.aws.amazon.com/guardduty/](https://console.aws.amazon.com/guardduty/) console, or run the [https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListDetectors.html](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListDetectors.html) API. ``` aws guardduty --region us-east-1 get-coverage-statistics --detector-id 12abc34d567e8fa901bc2d34e56789f0 --statistics-type COUNT_BY_COVERAGE_STATUS --filter-criteria '{"FilterCriterion":[{"CriterionKey":"ACCOUNT_ID", "FilterCondition":{"EqualsValue":"123456789012"}}] }' ``` ------ For more information about coverage issues, see [Troubleshooting Amazon ECS-Fargate runtime coverage issues](#ecs-runtime-monitoring-coverage-issues-troubleshoot). ## Coverage status change with EventBridge notifications The coverage status of your Amazon ECS cluster might appear as **Unhealthy**. To know when the coverage status changes, we recommend you to monitor the coverage status periodically, and troubleshoot if the status becomes **Unhealthy**. Alternatively, you can create an Amazon EventBridge rule to receive a notification when the coverage status changes from either **Unhealthy** to **Healthy** or otherwise. By default, GuardDuty publishes this in the [EventBridge bus](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-bus.html) for your account. ### Sample notification schema In an EventBridge rule, you can use the pre-defined sample events and event patterns to receive coverage status notification. For more information about creating an EventBridge rule, see [Create rule](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html#eb-gs-create-rule) in the *Amazon EventBridge User Guide*. Additionally, you can create a custom event pattern by using the following example notification schema. Make sure to replace the values for your account. To get notified when the coverage status of your Amazon ECS cluster changes from `Healthy` to `Unhealthy`, the `detail-type` should be *GuardDuty Runtime Protection Unhealthy*. To get notified when the coverage status changes from `Unhealthy` to `Healthy`, replace the value of `detail-type` with *GuardDuty Runtime Protection Healthy*. ``` { "version": "0", "id": "event ID", "detail-type": "GuardDuty Runtime Protection Unhealthy", "source": "aws.guardduty", "account": "AWS account ID", "time": "event timestamp (string)", "region": "AWS Region", "resources": [ ], "detail": { "schemaVersion": "1.0", "resourceAccountId": "string", "currentStatus": "string", "previousStatus": "string", "resourceDetails": { "resourceType": "ECS", "ecsClusterDetails": { "clusterName":"", "fargateDetails":{ "issues":[], "managementType":"" }, "containerInstanceDetails":{ "coveredContainerInstances":int, "compatibleContainerInstances":int } } }, "issue": "string", "lastUpdatedAt": "timestamp" } } ``` ## Troubleshooting Amazon ECS-Fargate runtime coverage issues If the coverage status of your Amazon ECS cluster is **Unhealthy**, you can view the reason under the **Issue** column. The following table provides the recommended troubleshooting steps for Fargate (Amazon ECS only) issues. For information about Amazon EC2 instance coverage issues, see [Troubleshooting Amazon EC2 runtime coverage issues](gdu-assess-coverage-ec2.md#ec2-runtime-monitoring-coverage-issues-troubleshoot) for Amazon EC2 instances. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/guardduty/latest/ug/gdu-assess-coverage-ecs.html)