Skip to main content
Amazon ECS 0.38.3Last updated in version 0.38.0

ECS Task Scheduler Module

View Source Release Notes

This terraform module allows for scheduling of ECS tasks

How do you configure when the ECS task will run?​

This module provides two options for defining when ECS tasks will be run:

In variables.tf there are two variables (task_event_pattern and task_schedule_expression) that can be provided in the module definition. At least one, but not both of these fields, must be provided. This is what is passed to the EventBridge rule to determine when to invoke your ECS task.

Note that this approach has AWS limitations with monitoring the event trigger and ECS task. AWS EventBridge fires the event but does not monitor whether the task ran successfully so if there is a failure, EventBridge does not attempt any retries or report failures.

Event Patterns​

The event pattern variable is a json string that defines which events to listen to and invoke your ECS task from.

module "ecs_task_scheduler" {

  task_event_pattern = <<EOF
    {
      "source": ["aws.ec2"],
      "detail-type": ["EC2 Instance State-change Notification"],
      "detail": {
        "state": ["terminated"]
      }
    }
  EOF

  #(additional arguments omitted)
}

For more information see the AWS Documentation on event rule patterns

Schedule Expressions​

With schedule expressions, you can define based on Cron schedules, and rate expressions. For more information on how to use expressions see AWS documention and examples below:

module "ecs_task_scheduler" {

  task_schedule_expression = "rate(5 minutes)"  

  #(additional arguments omitted)
}
module "ecs_task_scheduler" {

  task_schedule_expression = "cron(0 12 * * ? *)"  

  #(additional arguments omitted)
}

For more information see the AWS Documentation on schedule rules

Can I enable or disable the rule?​

The rule is enabled by default, and can be disabled by setting the is_enabled variable to false

Can I use my own IAM role?​

To provide an IAM role instead of using the role provided by the module you can:

  • Set create_iam_role variable to false
  • Provide the IAM role ARN to the ecs_task_iam_role_arn variable

How do I pass inputs and overrides to my ECS task from the EventBridge rule?​

This module provides support for passing the following additional inputs and overrides:

  • Task Count

  • Target Group

  • Launch Type

  • Platform Version

  • Propagate Tags

  • Enable Execute Command

  • Enable ECS Managed Tags

  • Network Configuration

    Example Network Configuration Block

    module "ecs_task_scheduler" {

      ecs_target_network_configuration = {
        assign_public_ip = false
        security_groups = [
          "sg-xxxx"
        ]
        subnets = [
          "subnet-xxxx",
          "subnet-xxxx"
        ]
      }

      #(additional arguments omitted)
    }

    Note that subnets is the only required parameter if the network_configuration block is defined.

  • Placement Contstraints

    Example Placement Constraints Configuration Block

    module "ecs_task_scheduler" {

      ecs_target_placement_constraints = [
        {
          type = "memberOf"
          expression = "attribute:ecs.availability-zone in [us-west-2a, us-west-2b, us-west-2c, us-west-2d]"
        },
        {
          type = "memberOf"
          expression = "attribute:ecs.subnet-id in [subnet-xxxx]"
        }
      ]

      #(additional arguments omitted)
    }

    Note that there is a maximum limit of 10 placement constraint objects. See AWS Documention for additional information on placement constraints

  • Container Overrides

    Example Container Overrides configuration input

    module "ecs_task_scheduler" {

      ecs_target_container_overrides = <<DOC
        {
          "containerOverrides": [
            {
              "name": "name-of-container-to-override",
              "command": ["bin/console", "scheduled-task"]
            }
          ]
        }
      DOC

      #(additional arguments omitted)
    }

See variables.tf for specific variable definitions.

Sample Usage​

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S ECS-TASK-SCHEDULER MODULE
# ------------------------------------------------------------------------------------------------------

module "ecs_task_scheduler" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-ecs.git//modules/ecs-task-scheduler?ref=v0.38.3"

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # The arn of the ECS cluster to use.
  ecs_target_cluster_arn = <string>

  # The task definition ARN for cloudwatch schedule to run.
  ecs_target_task_definition_arn = <string>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # Creation of the Eventbridge IAM role within the module. If omitted IAM role
  # ARN must be provided in ecs_task_iam_role variable.
  create_iam_role = true

  # String of JSON that defines container overrides that are passed to the task.
  ecs_target_container_overrides = null

  # Whether or not to enable the execute command functionality for the
  # containers in this task.
  ecs_target_enable_execute_command = null

  # Specifies an ECS task group for the task.
  ecs_target_group = null

  # Specifies the launch type on which your task is running.
  ecs_target_launch_type = null

  # Object that defines the target network configuration.
  ecs_target_network_configuration = null

  # An array of placement constraint objects to use for the task.
  ecs_target_placement_constraints = []

  # Specifies the platform version for the task.
  ecs_target_platform_version = null

  # Specifies whether to propagate the tags from the task definition to the
  # task.
  ecs_target_propagate_tags = null

  # The number of tasks to create based on the TaskDefinition.
  ecs_target_task_count = 1

  # ARN of IAM role for eventbridge to use. Only use if create_iam_role is set
  # to true
  ecs_task_iam_role = null

  # Specifies whether to enable Amazon ECS managed tags for the task.
  enable_ecs_managed_tags = null

  # Set to true to enable the rule and false to disable
  is_enabled = true

  # The event pattern to use. See README for usage examples. Leave null if using
  # task_schedule_expression.
  task_event_pattern = null

  # The scheduling expression to use (rate or cron - see README for usage
  # examples). Leave null if using task_event_pattern.
  task_schedule_expression = null

}


Reference​

Required​

The arn of the ECS cluster to use.

The task definition ARN for cloudwatch schedule to run.

Optional​

create_iam_rolebooloptional

Creation of the Eventbridge IAM role within the module. If omitted IAM role ARN must be provided in ecs_task_iam_role variable.

true

String of JSON that defines container overrides that are passed to the task.

null

Whether or not to enable the execute command functionality for the containers in this task.

null
ecs_target_groupstringoptional

Specifies an ECS task group for the task.

null

Specifies the launch type on which your task is running.

null

Object that defines the target network configuration.

null
ecs_target_placement_constraintslist(map(…))optional

An array of placement constraint objects to use for the task.

list(map(string))
[]

Specifies the platform version for the task.

null

Specifies whether to propagate the tags from the task definition to the task.

null
ecs_target_task_countnumberoptional

The number of tasks to create based on the TaskDefinition.

1
ecs_task_iam_rolestringoptional

ARN of IAM role for eventbridge to use. Only use if create_iam_role is set to true

null

Specifies whether to enable Amazon ECS managed tags for the task.

null
is_enabledbooloptional

Set to true to enable the rule and false to disable

true
task_event_patternstringoptional

The event pattern to use. See README for usage examples. Leave null if using task_schedule_expression.

null

The scheduling expression to use (rate or cron - see README for usage examples). Leave null if using task_event_pattern.

null