Amazon ECS events - Amazon Elastic Container Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon ECS events

Amazon ECS tracks the state of each of your tasks and services. If the state of a task or service changes, an event is generated and is sent to Amazon EventBridge. These events are classified as task state change events and service action events. These events and their possible causes are described in greater detail in the following sections.

Amazon ECS generated and sends the following types of events to EventBridge: container instance state change events, task state change events, service action, and service deployment state change events.

  • Container instance state change

  • Task state change

  • Deployment state change

  • Service action

Note

Amazon ECS may add other event types, sources, and details in the future. If you are de-serializing event JSON data in code, make sure that your application is prepared to handle unknown properties to avoid issues if and when these additional properties are added.

In some cases, multiple events are generated for the same activity. For example, when a task is started on a container instance, a task state change event is generated for the new task. A container instance state change event is generated to account for the change in available resources, such as CPU, memory, and available ports, on the container instance. Likewise, if a container instance is terminated, events are generated for the container instance, the container agent connection status, and every task that was running on the container instance.

Container state change and task state change events contain two version fields: one in the main body of the event, and one in the detail object of the event. The following describes the differences between these two fields:

  • The version field in the main body of the event is set to 0 on all events. For more information about EventBridge parameters, see Amazon service event metadata in the Amazon EventBridge User Guide.

  • The version field in the detail object of the event describes the version of the associated resource. Each time a resource changes state, this version is incremented. Because events can be sent multiple times, this field allows you to identify duplicate events. Duplicate events have the same version in the detail object. If you are replicating your Amazon ECS container instance and task state with EventBridge, you can compare the version of a resource reported by the Amazon ECS APIs with the version reported in EventBridge for the resource (inside the detail object) to verify that the version in your event stream is current.

Service action events only contain the version field in the main body.

Service action events specify the service in 2 differernt fields:

  • For events generated by create-service, the service is in the serviceName field.

  • For events generated by update-service, the service is in the service field.

If you use automated tooling for service events, you need to code for both fields.

For information about how to create a rule for service action events, see Amazon ECS service action events.

For additional information about how to integrate Amazon ECS and EventBridge, see Integrating Amazon EventBridge and Amazon ECS.