Skip to main content
AWS Lambda 1.4.0Last updated in version 1.4.0

Scheduled Lambda Job Module

View Source Release Notes

This module makes it easy to run an AWS Lambda function (such as one created with the lambda module) on a scheduled basis. This is useful for periodic background jobs, such as taking a daily snapshot of your servers.

Background info​

For more information on AWS Lambda, how it works, and how to configure your functions, check out the lambda module documentation.

Sample Usage​

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S SCHEDULED-LAMBDA-JOB MODULE
# ------------------------------------------------------------------------------------------------------

module "scheduled_lambda_job" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-lambda.git//modules/scheduled-lambda-job?ref=v1.4.0"

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

  # The ARN of the lambda function.
  lambda_function_arn = <string>

  # The name of the lambda function.
  lambda_function_name = <string>

  # An expression that defines the schedule for this lambda job. For example,
  # cron(0 20 * * ? *) or rate(5 minutes).
  schedule_expression = <string>

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

  # A custom assume role policy for the IAM role for EventBridge Scheduler. Only
  # applies on the EventBridge Scheduler path (when schedule_expression_timezone
  # is set). If not set, the default is a policy that allows the EventBridge
  # Scheduler service to assume the IAM role, which is what most users will
  # need. However, you can use this variable to override the policy for special
  # cases.
  assume_role_policy = null

  # Set to false to have this module skip creating resources. This weird
  # parameter exists solely because Terraform does not support conditional
  # modules. Therefore, this is a hack to allow you to conditionally decide if
  # this module should create anything or not.
  create_resources = true

  # Flag to add confused-deputy conditions (aws:SourceArn scoped to this module's schedule group, plus
  # aws:SourceAccount) to the trust relationship of the IAM role, so only EventBridge Scheduler schedules in this
  # module's schedule group can assume the role. Per AWS guidance the condition is scoped to the schedule group ARN,
  # not an individual schedule ARN (a schedule ARN cannot be validated at create time). Only applies to the
  # EventBridge Scheduler path (when schedule_expression_timezone is set). In a future release, this will default to true.
  #
  enforce_source_arn_condition = false

  # The ARN of existing IAM role that will be used by EventBridge Scheduler to
  # invoke the Lambda function. If set, the module will not create any IAM
  # entities and fully relies on caller to provide correct IAM role and its
  # policies. Using the variable allows the module to leverage an existing IAM
  # role - for example, when an account has centralized set of IAM entities, or
  # when deploying same function across multiple AWS region to avoid the module
  # attempting to create duplicate IAM entities.
  existing_role_arn = null

  # Determines whether the schedule is invoked within a flexible time window. 
  # Default is 'false' (don't run in a flexible time window)
  flexible_time_window_enabled = false

  # The name to use for the IAM role created for EventBridge Scheduler to invoke
  # the Lambda function. If null, default to the namespace (var.namespace). Only
  # used if var.existing_role_arn is null.
  iam_role_name = null

  # A map of tags to apply to the IAM role created for EventBridge Scheduler to
  # invoke the function. Only used if var.existing_role_arn is null.
  iam_role_tags = {}

  # ARN of a customer-managed key used to encrypt the Lambda function input
  # payload. If not set, the default AWS-managed key will be used.
  kms_key_arn = null

  # JSON text that will be passed to the lambda function on each invoke.
  lambda_function_input = null

  # The ARN of the policy that is used to set the permissions boundary for the
  # IAM role for EventBridge Scheduler
  lambda_role_permissions_boundary_arn = null

  # Maximum amount of time, in seconds, to continue to make retry attempts.
  # Ranges from 60 to 86400 (default).
  maximum_event_age_in_seconds = 86400

  # Maximum number of retry attempts to make before the request fails. Ranges
  # from 0 to 185 (default).
  maximum_retry_attempts = 185

  # Maximum time window during which a schedule can be invoked. Ranges from 1 to
  # 1440 minutes. Must be set if flexible_time_window_enabled is true.
  maximum_window_in_minutes = null

  # The namespace to use for all resources created by this module. If not set,
  # var.lambda_function_name, with '-scheduled' as a suffix, is used.
  namespace = null

  # Timezone in which the scheduling expression is evaluated. When set, the
  # module uses an EventBridge Scheduler schedule (which is timezone and
  # daylight-savings aware) instead of the default EventBridge rule (which is
  # always UTC). Leave null to keep the default rule-based behavior. Example:
  # Australia/Sydney.
  schedule_expression_timezone = null

  # A map of tags to apply to the EventBridge (CloudWatch Event) rule created on
  # the default schedule path (when schedule_expression_timezone is null). Not
  # used on the EventBridge Scheduler path, since Scheduler does not support
  # tagging schedules; tag the Scheduler IAM role via var.iam_role_tags instead.
  tags = {}

  # When true, all IAM policies will be managed as dedicated policies rather
  # than inline policies attached to the IAM roles. Dedicated managed policies
  # are friendlier to automated policy checkers, which may scan a single
  # resource for findings. As such, it is important to avoid inline policies
  # when targeting compliance with various security standards.
  use_managed_iam_policies = true

}


Reference​

Required​

lambda_function_arnstringrequired

The ARN of the lambda function.

lambda_function_namestringrequired

The name of the lambda function.

schedule_expressionstringrequired

An expression that defines the schedule for this lambda job. For example, cron(0 20 * * ? *) or rate(5 minutes).

Optional​

assume_role_policystringoptional

A custom assume role policy for the IAM role for EventBridge Scheduler. Only applies on the EventBridge Scheduler path (when schedule_expression_timezone is set). If not set, the default is a policy that allows the EventBridge Scheduler service to assume the IAM role, which is what most users will need. However, you can use this variable to override the policy for special cases.

null
create_resourcesbooloptional

Set to false to have this module skip creating resources. This weird parameter exists solely because Terraform does not support conditional modules. Therefore, this is a hack to allow you to conditionally decide if this module should create anything or not.

true

Flag to add confused-deputy conditions (aws:SourceArn scoped to this module's schedule group, plus aws:SourceAccount) to the trust relationship of the IAM role, so only EventBridge Scheduler schedules in this module's schedule group can assume the role. Per AWS guidance the condition is scoped to the schedule group ARN, not an individual schedule ARN (a schedule ARN cannot be validated at create time). Only applies to the EventBridge Scheduler path (when schedule_expression_timezone is set). In a future release, this will default to true.

false
existing_role_arnstringoptional

The ARN of existing IAM role that will be used by EventBridge Scheduler to invoke the Lambda function. If set, the module will not create any IAM entities and fully relies on caller to provide correct IAM role and its policies. Using the variable allows the module to leverage an existing IAM role - for example, when an account has centralized set of IAM entities, or when deploying same function across multiple AWS region to avoid the module attempting to create duplicate IAM entities.

null

Determines whether the schedule is invoked within a flexible time window. Default is 'false' (don't run in a flexible time window)

false
iam_role_namestringoptional

The name to use for the IAM role created for EventBridge Scheduler to invoke the Lambda function. If null, default to the namespace (namespace). Only used if existing_role_arn is null.

null
iam_role_tagsmap(string)optional

A map of tags to apply to the IAM role created for EventBridge Scheduler to invoke the function. Only used if existing_role_arn is null.

{}
kms_key_arnstringoptional

ARN of a customer-managed key used to encrypt the Lambda function input payload. If not set, the default AWS-managed key will be used.

null
lambda_function_inputstringoptional

JSON text that will be passed to the lambda function on each invoke.

null

The ARN of the policy that is used to set the permissions boundary for the IAM role for EventBridge Scheduler

null

Maximum amount of time, in seconds, to continue to make retry attempts. Ranges from 60 to 86400 (default).

86400

Maximum number of retry attempts to make before the request fails. Ranges from 0 to 185 (default).

185

Maximum time window during which a schedule can be invoked. Ranges from 1 to 1440 minutes. Must be set if flexible_time_window_enabled is true.

null
namespacestringoptional

The namespace to use for all resources created by this module. If not set, lambda_function_name, with '-scheduled' as a suffix, is used.

null

Timezone in which the scheduling expression is evaluated. When set, the module uses an EventBridge Scheduler schedule (which is timezone and daylight-savings aware) instead of the default EventBridge rule (which is always UTC). Leave null to keep the default rule-based behavior. Example: Australia/Sydney.

null
tagsmap(string)optional

A map of tags to apply to the EventBridge (CloudWatch Event) rule created on the default schedule path (when schedule_expression_timezone is null). Not used on the EventBridge Scheduler path, since Scheduler does not support tagging schedules; tag the Scheduler IAM role via iam_role_tags instead.

{}

When true, all IAM policies will be managed as dedicated policies rather than inline policies attached to the IAM roles. Dedicated managed policies are friendlier to automated policy checkers, which may scan a single resource for findings. As such, it is important to avoid inline policies when targeting compliance with various security standards.

true