Skip to content

Auto-generated

This page is generated by terraform-docs at build time from the infra/ repo. Do not edit manually.

scheduled-jobs

Runs one-shot jobs of an ECS service on a schedule: one EventBridge Scheduler schedule per entry in jobs, each calling ecs:RunTask on the service's cluster with a container command override. Built for core-api's job runner (node dist/jobs/run.js <job>, IS-200); a second service (dsar-api, IS-182) instantiates the same module with its own task definition family and container.

Design

  • EC2 launch type, bridge mode, the existing task definition family. The schedules reuse the service's task definition (same image, same SSM secrets, same roles) and the existing EC2 cluster. No awsvpc, no network_configuration, no extra task definition or image.
  • Newest ACTIVE revision. The target is the family ARN without a revision, so RunTask resolves the newest ACTIVE revision, which is whatever the last deploy registered. Nothing here pins a revision or uses ignore_changes.
  • RunTask ignores the service's desired_count. A schedule starts tasks even while the service runs at 0.
  • The runner's lock is the overlap guard. The job runner takes a MySQL GET_LOCK('job:<name>'), so an overlapping run, a duplicate start or a retried RunTask is harmless (the second one exits 0 as "lock held").
  • enabled = false is the per-environment switch. The schedule still exists but is DISABLED; flip it to true to turn the job on.
  • Tasks are not tagged (no tags/propagate_tags in the target), so the scheduler role does not need ecs:TagResource.

Failure path (notify_on_failure)

Two triggers invoke one small Node.js Lambda, which posts an Adaptive Card to a Teams channel webhook:

  1. An EventBridge rule on ECS Task State Change (STOPPED) for tasks in a jobs:* group, where a container exited non-zero or the task failed to start.
  2. A CloudWatch alarm on the schedule group's AWS/Scheduler InvocationDroppedCount, which catches schedules that never started a task once their retries are spent (e.g. no cluster capacity); the ECS rule cannot see those.

The webhook URL lives in an SSM SecureString created with a placeholder and ignore_changes = [value]. After the first apply, set the real value by hand (the org's CI Teams channel webhook); the URL is never in code, tfvars or state from Terraform. Until then the Lambda errors with a clear message.

Example

module "core_api_jobs" {
  source = "../../../modules/core/scheduled-jobs"

  name_prefix            = local.name_prefix
  environment            = var.environment
  service                = "core-api"
  region                 = var.region
  cluster_name           = module.core_ecs.cluster_name
  task_definition_family = module.core_api.task_definition_family
  container_name         = module.core_api.container_name
  task_role_arn          = module.core_api.task_role_arn
  execution_role_arn     = module.core_api.execution_role_arn
  log_group_name         = module.core_api.log_group_name
  tags                   = local.base_tags

  jobs = {
    "invitation-expire" = {
      cron    = "22 * * * ? *"
      enabled = true
      command = ["node", "dist/jobs/run.js", "invitation-expire"]
    }
  }
}

Requirements

Name Version
terraform >= 1.6.0
archive ~> 2.0
aws ~> 6.0

Providers

Name Version
archive ~> 2.0
aws ~> 6.0

Modules

No modules.

Resources

Name Type
archive_file.notify resource
aws_cloudwatch_event_rule.task_failed resource
aws_cloudwatch_event_target.task_failed resource
aws_cloudwatch_log_group.notify resource
aws_cloudwatch_metric_alarm.dropped_invocations resource
aws_iam_role.notify resource
aws_iam_role.scheduler resource
aws_iam_role_policy.notify resource
aws_iam_role_policy.scheduler_run_task resource
aws_lambda_function.notify resource
aws_lambda_permission.alarm resource
aws_lambda_permission.events resource
aws_scheduler_schedule.job resource
aws_scheduler_schedule_group.jobs resource
aws_ssm_parameter.teams_webhook_url resource
aws_caller_identity.current data source
aws_iam_policy_document.lambda_assume_role data source
aws_iam_policy_document.scheduler_assume_role data source

Inputs

Name Description Type Default Required
cluster_name Name of the ECS cluster the jobs run on string n/a yes
container_name Name of the container in the task definition whose command is overridden string n/a yes
environment Environment name (stage or prod); used in the SSM parameter path and shown on notifications string n/a yes
execution_role_arn ARN of the execution role of the task definition (the scheduler role may pass it to ECS) string n/a yes
group Group segment of the SSM parameter path (///-jobs/...) string "core" no
jobs Scheduled jobs keyed by job name. cron is the six-field EventBridge cron expression WITHOUT the cron() wrapper (UTC), e.g. "22 * * * ? *"; enabled=false keeps the schedule but sets it DISABLED; command is the container command override
map(object({
cron = string
enabled = bool
command = list(string)
}))
n/a yes
log_group_name CloudWatch log group the task writes to (awslogs, stream prefix ecs); only used to build the log link in failure notifications string n/a yes
log_retention_days Retention of the notifier Lambda's log group, in days number 30 no
name_prefix Prefix for resource names (environment-region-group, e.g. stage-euc1-core) string n/a yes
notify_on_failure Create the failure notification path (event rule, scheduler-error alarm, notifier Lambda, SSM webhook parameter) bool true no
region AWS region string n/a yes
service Service the jobs belong to (e.g. core-api); used in resource names string n/a yes
tags Tags applied to all resources map(string) {} no
task_definition_family Task definition family to run. The schedules target the family without a revision, so RunTask uses the newest ACTIVE revision (the one the last deploy registered) string n/a yes
task_role_arn ARN of the task role of the task definition (the scheduler role may pass it to ECS) string n/a yes

Outputs

Name Description
notifier_lambda_name Name of the failure notifier Lambda (null when notify_on_failure is false)
schedule_group_name Name of the EventBridge Scheduler schedule group holding the job schedules
scheduler_role_arn ARN of the IAM role the schedules assume to call ecs:RunTask
teams_webhook_ssm_parameter_name Name of the SSM SecureString holding the Teams webhook URL; set its real value by hand after apply (null when notify_on_failure is false)