Menu
Amazon Elastic Container Service
Developer Guide (API Version 2014-11-13)

Tutorial: Listening for Amazon ECS CloudWatch Events

In this tutorial, you set up a simple AWS Lambda function that listens for Amazon ECS task events and writes them out to a CloudWatch Logs log stream.

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 using Fargate to create one. At the end of this tutorial, you run a task on this cluster to test that you have configured your Lambda function correctly.

Step 1: Create the Lambda Function

In this procedure, you will create a simple Lambda function to serve as a target for Amazon ECS event stream messages.

  1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.

  2. Choose Create a function.

  3. On the Author from scratch screen, do the following:

    1. choose a Name for the function.

    2. For Runtime, choose Python 2.7.

    3. For Role, choose Create a custom role. A new window pops up enabling you to create a new role for your Lambda function.

    4. On the AWS Lambda requires access to your resources screen, accept the defaults and choose Allow.

  4. Choose Create function.

  5. In the Function code section, edit the sample code to match the following example:

    import json def lambda_handler(event, context): if event["source"] != "aws.ecs": raise ValueError("Function only supports input from events with a source type of: aws.ecs") print('Here is the event:') print(json.dumps(event))

    This is a simple Python 2.7 function that prints the event sent by Amazon ECS. If everything is configured correctly, at the end of this tutorial, you see the event details appear in the CloudWatch Logs log stream associated with this Lambda function.

  6. In the Function code section, edit the value of Handler to be eventstream-handler.

  7. Choose Save.

Step 2: Register Event Rule

Next, you create a CloudWatch Events event rule that captures task events coming from your Amazon ECS clusters. This rule captures all events coming from all clusters within the account where it is defined. The task messages themselves contain information about the event source, including the cluster on which it resides, that you can use to filter and sort events programmatically.

Note

When you use the AWS Management Console to create an event rule, the console automatically adds the IAM permissions necessary to grant CloudWatch Events permission to call your Lambda function. If you are creating an event rule using the AWS CLI, you need to grant this permission explicitly. For more information, see Events and Event Patterns in the Amazon CloudWatch Events User Guide.

To route events to your Lambda function

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

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

  3. For Event Source, choose ECS as the event source. By default, the rule applies to all Amazon ECS events for all of your Amazon ECS groups. Alternatively, you can select specific events or a specific Amazon ECS group.

  4. For Targets, choose Add target, for Target type, choose Lambda function, and then select your Lambda function.

  5. Choose Configure details.

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

Step 3: Test Your Rule

Finally, you create a CloudWatch Events event rule that captures task events coming from your Amazon ECS clusters. This rule captures all events coming from all clusters within the account where it is defined. The task messages themselves contain information about the event source, including the cluster on which it resides, that you can use to filter and sort events programmatically.

To test your rule

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

  2. Choose Clusters, default.

  3. On the Cluster : default screen, choose Tasks, Run new Task.

  4. For Task Definition, select the latest version of console-sample-app-static and choose Run Task.

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

  6. On the navigation pane, choose Logs and select the log group for your Lambda function (for example, /aws/lambda/my-function).

  7. Select a log stream to view the event data.