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 = falseis 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_tagsin the target), so the scheduler role does not needecs:TagResource.
Failure path (notify_on_failure)¶
Two triggers invoke one small Node.js Lambda, which posts an Adaptive Card to a Teams channel webhook:
- An EventBridge rule on
ECS Task State Change(STOPPED) for tasks in ajobs:*group, where a container exited non-zero or the task failed to start. - A CloudWatch alarm on the schedule group's
AWS/SchedulerInvocationDroppedCount, 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 (/ |
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({ |
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) |