Scheduled tasks - Amazon ECS

Scheduled tasks

Amazon ECS supports creating scheduled tasks. Scheduled tasks use Amazon EventBridge rules to run tasks either on a schedule or in a response to an EventBridge event.

If you want to run tasks at set intervals, such as a backup operation or a log scan, you can create a scheduled task that runs one or more tasks at specified times. You can specify a regular interval (run every N minutes, hours, or days), or for more complicated scheduling, you can use a cron expression. For more information, see Cron expressions and rate expressions in the Amazon EventBridge User Guide.

If you want to run tasks that are triggered by an event, there are AWS managed events for services (for example Amazon ECS task and container instance state change events) or you can create a custom event pattern. For more information, see Event patterns in the Amazon EventBridge User Guide.

Create a scheduled task

Scheduled tasks are triggered by Amazon EventBridge rules, which you can create using the EventBridge console. Although you can create a scheduled task in the Amazon ECS console, currently the EventBridge console provides more functionality so the following steps walk you through creating an EventBridge rule that triggers a scheduled task.

Before you can submit scheduled tasks with EventBridge rules and targets, the EventBridge service needs several permissions to run Amazon ECS tasks on your behalf. For more information about the required service principal and IAM permissions for this role, see Amazon ECS CloudWatch Events IAM Role.

Create a scheduled task (EventBridge console)

  1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

  2. In the navigation pane, choose Rules.

  3. Choose Create rule.

  4. Enter a name and description for the rule.

    Note

    A rule can't have the same name as another rule in the same Region and on the same event bus.

  5. For Event bus, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select AWS default event bus. When an AWS service in your account emits an event, it always goes to your account’s default event bus.

  6. Choose how to schedule the task.

    To create a rule based on... Do this...

    Event

    1. For Rule type, choose Rule with an event pattern.

    2. Choose Next.

    3. For Event source, choose AWS events.

    4. For Event pattern, do one of the following:

      • To use a template to create your event pattern, choose Event pattern form and choose the Event source, AWS service, and Event type. If you choose All Events as the event type, all events emitted by the AWS service will match the rule.

        To customize the template, choose Custom pattern (JSON editor) and make your changes.

      • To use a custom event pattern, choose Custom pattern (JSON editor) and create your event pattern.

    Schedule
    1. For Rule type, choose Schedule.

    2. Choose Next.

    3. For Schedule pattern, do one of the following:

      • To use a cron expression to define the schedule, choose A fine-grained schedule that runs at a specific time, such as 8:00 a.m. PST on the first Monday of every month and enter the cron expression.

      • To use a rate expression to define the schedule, choose A schedule that runs at a regular rate, such as every 10 minutes and enter the rate expression.

  7. Choose Next.

  8. For Target types, choose AWS service.

  9. For Select a target, select ECS task.

  10. For Cluster, select an Amazon ECS cluster.

  11. For Task definition, select a task definition family.

  12. For Task definition revision, select either Latest or Revision and select a specific task definition revision to use.

  13. For Count, specify the desired number of tasks to run.

  14. Choose how your scheduled task is distributed across your cluster infrastructure.

    Distribution method Steps

    Capacity provider strategy

    1. In the Compute options section, select Capacity provider strategy.

    2. Choose a strategy:

      • To use the cluster's default capacity provider strategy, choose Use cluster default.

      • If your cluster doesn't have a default capacity provider strategy, or to use a custom strategy, choose Use custom, Add capacity provider strategy and define your custom capacity provider strategy by specifying a Base, Capacity provider, and Weight.

    Note

    To use a capacity provider in a strategy, the capacity provider must be associated with the cluster. For more information about capacity provider strategies, see Amazon ECS capacity providers.

    Launch type
    1. In the Compute options section, select Launch type.

    2. For Launch type, choose a launch type.

    3. (Optional) When the Fargate launch type is specified, for Platform version, specify the platform version to use. If a platform version isn't specified, the LATEST platform version is used by default.

  15. If the task is hosted on Fargate or uses the awsvpc network mode, expand Configure network configuration and specify a network configuration.

    1. For Subnets, specify one or more subnet IDs.

    2. For Security groups, specify one or more security group IDs.

    3. For Auto-assign public IP, specify whether to assign a public IP address from your subnet to the task.

  16. (Optional) To specify additional parameters for your tasks, expand Configure additional properties.

    1. For Task group, specify a task group name. The task group name is used to identify a set of related tasks and is used in conjunction with the spread task placement strategy to ensure tasks in the same task group are spread out evenly among the container instances in the cluster.

    2. For Tags, choose Add tag to associate key value pair tags for the task.

    3. To add tags to use when reviewing cost allocation in your Cost and Usage Report, for Configure managed tags, choose Enable managed tags. For more information, see Tagging your resources for billing.

    4. To enable the ECS Exec functionality for the task, for Configure execute command, choose Enable execute command. For more information, see Using Amazon ECS Exec for debugging.

    5. To add the tags associated with the task definition to your task, for Configure propagate tags, choose Propagate tags from task definition. For more information, see Tagging your resources.

      Note

      If you specify a tag with the same key in the Tags section, that tag overrides the tag that is propagated from the task definition.

  17. For many target types, EventBridge needs permissions to send events to the target. In these cases, EventBridge can create the IAM role needed for your rule to run. Do one of the following:

    • To create an IAM role automatically, choose Create a new role for this specific resource.

    • To use an IAM role that you created earlier, choose Use existing role and select the existing role from the dropdown.

  18. (Optional) For Additional settings, do the following:

    1. For Maximum age of event, enter a value between one minute (00:01) and 24 hours (24:00).

    2. For Retry attempts, enter a number between 0 and 185.

    3. For Dead-letter queue, choose whether to use a standard Amazon SQS queue as a dead-letter queue. EventBridge sends events that match this rule to the dead-letter queue if they are not successfully delivered to the target. Do one of the following:

      • Choose None to not use a dead-letter queue.

      • Choose Select an Amazon SQS queue in the current AWS account to use as the dead-letter queue and then select the queue to use from the dropdown.

      • Choose Select an Amazon SQS queue in an other AWS account as a dead-letter queue and then enter the ARN of the queue to use. You must attach a resource-based policy to the queue that grants EventBridge permission to send messages to it. For more information, see Granting permissions to the dead-letter queue in the Amazon EventBridge User Guide.

  19. Choose Next.

  20. (Optional) Enter one or more tags for the rule. For more information, see Amazon EventBridge tags in the Amazon EventBridge User Guide.

  21. Choose Next.

  22. Review the details of the rule and choose Create rule.

View your scheduled tasks

Your scheduled tasks can be viewed in the classic Amazon ECS console. You can also view the Amazon EventBridge rules that trigger the scheduled tasks in the EventBridge console.

To view your scheduled tasks (Amazon ECS console)

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

  2. Choose the cluster your scheduled tasks are run in.

  3. On the Cluster: cluster-name page, choose the Scheduled Tasks tab.

  4. All of your scheduled tasks are listed.

Edit a scheduled task

Your scheduled tasks can be edited in the classic Amazon ECS console. You can also edit the Amazon EventBridge rules that trigger the scheduled tasks in the EventBridge console.

To edit a scheduled task (Amazon ECS console)

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

  2. Choose the cluster in which to edit your scheduled task.

  3. On the Cluster: cluster-name page, choose Scheduled Tasks.

  4. Select the box to the left of the schedule rule to edit, and choose Edit.

  5. Edit the fields to update and choose Update.