Amazon ECS
User Guide for AWS Fargate (API Version 2014-11-13)

Tutorial: Sending Amazon Simple Notification Service Alerts for Task Stopped Events

In this tutorial, you configure a CloudWatch Events event rule that only captures task events where the task has stopped running because one of its essential containers has terminated. The event sends only task events with a specific stoppedReason property to the designated Amazon SNS topic.

Prerequisite: Set Up a Test Cluster

If you do not have a running cluster to capture events from, follow the steps in Getting Started with Amazon ECS to create one. At the end of this tutorial, you run a task on this cluster to test that you have configured your Amazon SNS topic and CloudWatch Events event rule correctly.

Step 1: Create and Subscribe to an Amazon SNS Topic

For this tutorial, you configure an Amazon SNS topic to serve as an event target for your new event rule.

To create an Amazon SNS topic

  1. Open the Amazon SNS console at https://console.aws.amazon.com/sns/v3/home.

  2. Choose Topics, Create topic.

  3. On the Create topic screen, for Name, enter TaskStoppedAlert and choose Create topic.

  4. On the TaskStoppedAlert details screen, choose Create subscription.

  5. On the Create subscription screen, for Protocol, choose Email. For Endpoint, enter an email address to which you currently have access and choose Create subscription.

  6. Check your email account, and wait to receive a subscription confirmation email message. When you receive it, choose Confirm subscription.

Step 2: Register Event Rule

Next, you register an event rule that captures only task-stopped events for tasks with stopped containers.

To create an event rule

  1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  2. On the navigation pane, choose Events, Rules, Create rule.

  3. For Event Source, choose Event Pattern, select Custom event pattern and then replace the existing text with the following text:

    { "source":[ "aws.ecs" ], "detail-type":[ "ECS Task State Change" ], "detail":{ "lastStatus":[ "STOPPED" ], "stoppedReason":[ "Essential container in task exited" ] } }

    This code defines a CloudWatch Events event rule that matches any event where the lastStatus and stoppedReason fields match the indicated values. For more information about event patterns, see Events and Event Patterns in the Amazon CloudWatch User Guide.

  4. For Targets, choose Add target. For Target type, choose SNS topic, and then choose TaskStoppedAlert.

  5. Choose Configure details.

  6. For Rule definition, type a name and description for your rule and then choose Create rule.

Step 3: Test Your Rule

Verify that the rule is working by running a task that exits shortly after it starts. If your event rule is configured correctly, you receive an email message within a few minutes with the event text. If you have an existing task definition that can satisfy the rule requirements, run a task using it. If you do not, the following steps will walk you through registering a Fargate task definition and running it that will.

To test the rule

  1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.

  2. Choose Task Definitions, Create new Task Definition.

  3. For Select launch type compatibility, choose FARGATE, Next step.

  4. Choose Configure via JSON, copy and paste the following task definition JSON into the field and choose Save.

    { "containerDefinitions":[ { "command":[ "sh", "-c", "sleep 5" ], "essential":true, "image":"amazonlinux:2", "name":"test-sleep" } ], "cpu":"256", "executionRoleArn":"arn:aws:iam::012345678910:role/ecsTaskExecutionRole", "family":"fargate-task-definition", "memory":"512", "networkMode":"awsvpc", "requiresCompatibilities":[ "FARGATE" ] }
  5. Choose Create, View task definition.

  6. For Actions, choose Run Task.

  7. For Launch type, choose FARGATE. For VPC and security groups, choose a VPC and Subnets for the task to use and then choose Run Task.

  8. For Container name, type Wordpress, for Image, type wordpress, and for Maximum memory (MB), type 128.

  9. On the Tasks tab for your cluster, periodically choose the refresh icon until you no longer see your task running. To verify that your task has stopped, for Desired task status, choose Stopped.

  10. Check your email to confirm that you have received an email alert for the stopped notification.