Amazon ECS 0.36.0Last updated in version 0.34.2

ECS Task Scheduler Module

View SourceRelease 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:

• Event Patterns
• Schedule Expressions

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:

• Cron Expressions
• Rate Expressions

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

Terraform

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.36.0"

  # ----------------------------------------------------------------------------------------------------
  # 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

}

Terragrunt

terragrunt.hcl

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

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

inputs = {

  # ----------------------------------------------------------------------------------------------------
  # 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

Inputs

Required

ecs_target_cluster_arnstringrequired

The arn of the ECS cluster to use.

ecs_target_task_definition_arnstringrequired

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.

Default:true

ecs_target_container_overridesstringoptional

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

Default:null

ecs_target_enable_execute_commandbooloptional

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

Default:null

ecs_target_groupstringoptional

Specifies an ECS task group for the task.

Default:null

ecs_target_launch_typestringoptional

Specifies the launch type on which your task is running.

Default:null

ecs_target_network_configurationoptional

Object that defines the target network configuration.

Default:null

ecs_target_placement_constraintslist(map(…))optional

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

Type Details

list(map(string))

Default:[]

ecs_target_platform_versionstringoptional

Specifies the platform version for the task.

Default:null

ecs_target_propagate_tagsstringoptional

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

Default:null

ecs_target_task_countnumberoptional

The number of tasks to create based on the TaskDefinition.

Default:1

ecs_task_iam_rolestringoptional

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

Default:null

enable_ecs_managed_tagsbooloptional

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

Default:null

is_enabledbooloptional

Set to true to enable the rule and false to disable

Default:true

task_event_patternstringoptional

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

Default:null

task_schedule_expressionstringoptional

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

Default:null

Outputs

ecs_events_iam_role_arn

ecs_events_iam_role_name

ecs_schedule_task_rule_arn

ecs_schedule_task_rule_name