Amazon Batch jobs as EventBridge targets - Amazon Batch
Creating a scheduled jobCreating a rule with an event patternEvent input transformer
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon Batch jobs as EventBridge targets

Amazon EventBridge delivers a near real-time stream of system events that describe changes in Amazon Web Services resources. Typically, Amazon Batch on Amazon Elastic Container Service, Amazon Elastic Kubernetes Service, and Amazon Fargate jobs are available as EventBridge targets. Using simple rules, you can match events and submit Amazon Batch jobs in response to them. For more information, see What is EventBridge? in the Amazon EventBridge User Guide.

You can also use EventBridge to schedule automated actions that are invoked at certain times using cron or rate expressions. For more information, see Creating an Amazon EventBridge rule that runs on a schedule in the Amazon EventBridge User Guide.

For information about how to create a rule that runs when an event matches an event pattern, see Creating Amazon EventBridge rules that react to events in the Amazon EventBridge User Guide.

Common use cases for Amazon Batch jobs as an EventBridge target include the following use cases:

  • A scheduled job occurs at regular time intervals. For example, a cron job occurs only during low-usage hours when Amazon EC2 Spot Instances are less expensive.

  • An Amazon Batch job runs in response to an API operation that's logged in CloudTrail. For example, a job is submitted whenever an object is uploaded to a specified Amazon S3 bucket. Each time this happens, the EventBridge input transformer passes the bucket and key name of the object to Amazon Batch parameters.

    Note

    In this scenario, all of related Amazon resources must be in the same Region. This includes resources such as the Amazon S3 bucket, EventBridge rule, and CloudTrail logs.

Before you can submit Amazon Batch jobs with EventBridge rules and targets, the EventBridge service requires several permissions to run Amazon Batch jobs. When you create a rule in the EventBridge console that specifies an Amazon Batch job as a target, you can also create this role. For more information about the required service principal and IAM permissions for this role, see EventBridge IAM role.

Creating a scheduled Amazon Batch job

The following procedure covers how to create a scheduled Amazon Batch job and the required EventBridge IAM role.

To create a scheduled Amazon Batch job with EventBridge
Note

This procedure works for all Amazon Batch on Amazon ECS, Amazon EKS, and Amazon Fargate jobs.

  1. Open the Amazon EventBridge console at https://console.amazonaws.cn/events/.

  2. From the navigation bar, select the Amazon Web Services Region to use.

  3. In the navigation pane, choose Rules.

  4. Choose Create rule.

  5. For Name, specify a unique name for your compute environment. The name can contain up to 64 characters. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (_).

    Note

    A rule can't have the same name as another rule in the same Region and on the same event bus.

  6. (Optional) For Description, enter a description for the rule.

  7. For Event bus, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select default. When an Amazon Web Service in your account emits an event, it always goes to your account's default event bus.

  8. (Optional) Turn off the rule on the selected bus if you don't want to run the rule immediately.

  9. For Rule type, choose Schedule.

  10. Choose Continue to create rule or Next.

  11. For Schedule pattern, do one of the following:

    • Choose A fine-grained schedule that runs at a specific time, such as 8:00 a.m. PST on the first Monday of every month and then enter a cron expression. For more information, see Cron Expressions in the Amazon EventBridge User Guide.

    • Choose A schedule that runs at a regular rate, such as every 10 minutes. and then enter a rate expression.

  12. Choose Next.

  13. For Target types, choose Amazon Web Service.

  14. For Select a target, choose Batch job queue. Then, configure the following:

    • Job queue: Enter the Amazon Resource Name (ARN) of the job queue to schedule your job in.

    • Job definition: Enter the name and revision or full ARN of the job definition to use for your job.

    • Job name: Enter a name for your job.

    • Array size: (Optional) Enter an array size for your job to run more than one copy. For more information, see Array jobs.

    • Job attempts: (Optional) Enter the number of times to retry your job if it fails. For more information, see Automated job retries.

  15. For Batch job queue target types, EventBridge needs permission to send events to the target. EventBridge can create the IAM role needed for your rule to run. Do one of the following:

    • To create an IAM role automatically, choose Create a new role for this specific resource.

    • To use an IAM role that you've already created, choose Use existing role.

  16. (Optional) Expand Additional settings.

    1. For Configure target input, choose how the text from an event is processed before it's passed to the target.

    2. For Maximum age of event, specify the time interval for how long unprocessed events are kept.

    3. For Retry attempts, enter the number of times that an event is retried.

    4. For Dead-letter queue, choose an option for how unprocessed events are handled. If necessary, specify the Amazon SQS queue to use as the dead-letter queue.

  17. (Optional) Choose Add another target to add another target for this rule.

  18. Choose Next.

  19. (Optional) For Tags, choose Add new tag to add a resource label for the rule. For more information, see Amazon EventBridge tags.

  20. Choose Next.

  21. For Review and create, review the configuration steps. If you need to make changes, choose Edit. When you're finished, choose Create rule.

For more information about creating rules, see Creating an Amazon EventBridge rule that runs on a schedule in the Amazon EventBridge User Guide.

Creating a rule with an event pattern

The following procedure covers how to create a rule with an event pattern.

To create a rule that sends the event to a target when the event matches a defined pattern
Note

This procedure works for all Amazon Batch on Amazon ECS, Amazon EKS, and Amazon Fargate jobs.

  1. Open the Amazon EventBridge console at https://console.amazonaws.cn/events/.

  2. From the navigation bar, select the Amazon Web Services Region to use.

  3. In the navigation pane, choose Rules.

  4. Choose Create rule.

  5. For Name, specify a unique name for your compute environment. The name can contain up to 64 characters. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (_).

    Note

    A rule can't have the same name as another rule in the same Region and on the same event bus.

  6. (Optional) For Description, enter a description for the rule.

  7. For Event bus, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select default. When an Amazon Web Service in your account emits an event, it always goes to your account's default event bus.

  8. (Optional) Turn off the rule on the selected bus if you don't want to run the rule immediately.

  9. For Rule type, choose Rule with an event pattern.

  10. Choose Next.

  11. For Event Source, choose Amazon event or EventBridge partner events.

  12. (Optional) For Sample event:

    1. For Sample event type, choose Amazon events.

    2. For Sample events, choose Batch Job State Change.

  13. For Creation method, choose Use pattern form.

  14. For Event pattern:

    1. For Event source, choose Amazon Web Services.

    2. For Amazon Web Service, choose Batch.

    3. For Event type, choose Batch Job State Change.

  15. Choose Next.

  16. For Target types, choose Amazon Web Service.

  17. For Select a target, choose a target type. For example, choose Batch job queue. Then specify the following:

    • Job queue: Enter the Amazon Resource Name (ARN) of the job queue to schedule your job in.

    • Job definition: Enter the name and revision or full ARN of the job definition to use for your job.

    • Job name: Enter a name for your job.

    • Array size: (Optional) Enter an array size for your job to run more than one copy. For more information, see Array jobs.

    • Job attempts: (Optional) Enter the number of times to retry your job if it fails. For more information, see Automated job retries.

  18. For Batch job queue target types, EventBridge needs permission to send events to the target. EventBridge can create the IAM role needed for your rule to run. Do one of the following:

    • To create an IAM role automatically, choose Create a new role for this specific resource.

    • To use an IAM role that you created before, choose Use existing role.

  19. (Optional) Expand Additional settings.

    1. For Configure target input, choose how text from an event is processed.

    2. For Maximum age of event, specify the time interval for how long unprocessed events are kept.

    3. For Retry attempts, enter the number of times that an event is retried.

    4. For Dead-letter queue, choose an option for how unprocessed events are handled. If necessary, specify the Amazon SQS queue to use as the dead-letter queue.

  20. (Optional) Choose Add another target to add an additional target.

  21. Choose Next.

  22. (Optional) For Tags, choose Add new tag to add a resource label. For more information, see Amazon EventBridge tags in the Amazon EventBridge User Guide.

  23. Choose Next.

  24. For Review and create, review the configuration steps. If you need to make changes, choose Edit. After you're finished, choose Create rule.

    For more information about creating rules, see Creating Amazon EventBridge rules that react to events in the Amazon EventBridge User Guide.

Passing event information to an Amazon Batch Target on a schedule using the EventBridge input transformer

You can use the EventBridge input transformer to pass event information to Amazon Batch in a job submission. This can be especially valuable if you invoke jobs as a result of other Amazon event information. One example is an object upload to an Amazon S3 bucket. You can also use a job definition with parameter substitution values in the container's command. The EventBridge input transformer can provide the parameter values based on the event data.

Then, afterwards, you create an Amazon Batch event target that parses information from the event that starts it and transforms it into a parameters object. When the job runs, the parameters from the trigger event are passed to the command of the job container.

Note

In this scenario, all of the Amazon resources (such as Amazon S3 buckets, EventBridge rules, and CloudTrail logs) must be in the same Region.

To create an Amazon Batch target that uses the input transformer

  1. Open the Amazon EventBridge console at https://console.amazonaws.cn/events/.

  2. From the navigation bar, select the Amazon Web Services Region to use.

  3. In the navigation pane, choose Rules.

  4. Choose Create rule.

  5. For Name, specify a unique name for your compute environment. The name can contain up to 64 characters. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (_).

    Note

    A rule can't have the same name as another rule in the same Amazon Web Services Region and on the same event bus.

  6. (Optional) For Description, enter a description for the rule.

  7. For Event bus, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select default. When an Amazon Web Service in your account emits an event, it always goes to your account's default event bus.

  8. (Optional) Turn off the rule on the selected bus if you don't want to run the rule immediately.

  9. For Rule type, choose Schedule.

  10. Choose Continue to create rule or Next.

  11. For Schedule pattern, do one of the following:

    • Choose A fine-grained schedule that runs at a specific time, such as 8:00 a.m. PST on the first Monday of every month and then enter a cron expression. For more information, see Cron Expressions in the Amazon EventBridge User Guide.

    • Choose A schedule that runs at a regular rate, such as every 10 minutes. and then enter a rate expression.

  12. Choose Next.

  13. For Target types, choose Amazon Web Service.

  14. For Select a target, choose Batch job queue. Then, configure the following:

    • Job queue: Enter the Amazon Resource Name (ARN) of the job queue to schedule your job in.

    • Job definition: Enter the name and revision or full ARN of the job definition to use for your job.

    • Job name: Enter a name for your job.

    • Array size: (Optional) Enter an array size for your job to run more than one copy. For more information, see Array jobs.

    • Job attempts: (Optional) Enter the number of times to retry your job if it fails. For more information, see Automated job retries.

  15. For Batch job queue target types, EventBridge needs permission to send events to the target. EventBridge can create the IAM role needed for your rule to run. Do one of the following:

    • To create an IAM role automatically, choose Create a new role for this specific resource.

    • To use an IAM role that you've already created, choose Use existing role.

  16. (Optional) Expand Additional settings.

  17. In the Additional settings section, for Configure target input, choose Input Transformer.

  18. Choose Configure input transformer.

  19. (Optional) For Sample event:

    1. For Sample event type, choose Amazon events.

    2. For Sample events, choose Batch Job State Change.

  20. In the Target input transformer section, for Input path, specify the values to parse from the triggering event. For example, to parse Batch Job State Change event, use the following JSON format.

    {
    "instance": "$.detail.jobId",
    "state": "$.detail.status"
}

  21. For Template, enter the following.

    {
    "instance": <jobId> ,
    "status": <status>
}

  22. Choose Confirm.

  23. For Maximum age of event, specify the time interval for how long unprocessed events are kept.

  24. For Retry attempts, enter the number of times that an event is retried.

  25. For Dead-letter queue, choose an option for how unprocessed events are handled. If necessary, specify the Amazon SQS queue to use as the dead-letter queue.

  26. (Optional) Choose Add another target to add an additional target.

  27. Choose Next.

  28. (Optional) For Tags, choose Add new tag to add a resource label. For more information, see Amazon EventBridge tags in the Amazon EventBridge User Guide.

  29. Choose Next.

  30. For Review and create, review the configuration steps. If you need to make changes, choose Edit. After you're finished, choose Create rule.