Namespace Amazon.CDK.AWS.Scheduler.Alpha
Amazon EventBridge Scheduler Construct Library
---The APIs of higher level constructs in this module are experimental and under active development.
They are subject to non-backward compatible changes or removal in any future version. These are
not subject to the <a href="https://semver.org/">Semantic Versioning</a> model and breaking changes will be
announced in the release notes. This means that while you may use them, you may need to update
your source code when upgrading to a newer version of this package.
Amazon EventBridge Scheduler is a feature from Amazon EventBridge that allows you to create, run, and manage scheduled tasks at scale. With EventBridge Scheduler, you can schedule one-time or recurrently tens of millions of tasks across many AWS services without provisioning or managing underlying infrastructure.
This module is part of the AWS Cloud Development Kit project. It allows you to define Event Bridge Schedules.
This module is in active development. Some features may not be implemented yet.
Defining a schedule
Function fn;
var target = new LambdaInvoke(fn, new ScheduleTargetBaseProps {
Input = ScheduleTargetInput.FromObject(new Dictionary<string, string> {
{ "payload", "useful" }
})
});
var schedule = new Schedule(this, "Schedule", new ScheduleProps {
Schedule = ScheduleExpression.Rate(Duration.Minutes(10)),
Target = target,
Description = "This is a test schedule that invokes lambda function every 10 minutes."
});
Schedule Expressions
You can choose from three schedule types when configuring your schedule: rate-based, cron-based, and one-time schedules.
Both rate-based and cron-based schedules are recurring schedules. You can configure each recurring schedule type using a schedule expression. For cron-based schedule you can specify a time zone in which EventBridge Scheduler evaluates the expression.
LambdaInvoke target;
var rateBasedSchedule = new Schedule(this, "Schedule", new ScheduleProps {
Schedule = ScheduleExpression.Rate(Duration.Minutes(10)),
Target = target,
Description = "This is a test rate-based schedule"
});
var cronBasedSchedule = new Schedule(this, "Schedule", new ScheduleProps {
Schedule = ScheduleExpression.Cron(new CronOptionsWithTimezone {
Minute = "0",
Hour = "23",
Day = "20",
Month = "11",
TimeZone = TimeZone.AMERICA_NEW_YORK
}),
Target = target,
Description = "This is a test cron-based schedule that will run at 11:00 PM, on day 20 of the month, only in November in New York timezone"
});
A one-time schedule is a schedule that invokes a target only once. You configure a one-time schedule when by specifying the time of the day, date, and time zone in which EventBridge Scheduler evaluates the schedule.
LambdaInvoke target;
var oneTimeSchedule = new Schedule(this, "Schedule", new ScheduleProps {
Schedule = ScheduleExpression.At(
new Date(2022, 10, 20, 19, 20, 23), TimeZone.AMERICA_NEW_YORK),
Target = target,
Description = "This is a one-time schedule in New York timezone"
});
Grouping Schedules
Your AWS account comes with a default scheduler group. You can access default group in CDK with:
var defaultGroup = Group.FromDefaultGroup(this, "DefaultGroup");
If not specified a schedule is added to the default group. However, you can also add the schedule to a custom scheduling group managed by you:
LambdaInvoke target;
var group = new Group(this, "Group", new GroupProps {
GroupName = "MyGroup"
});
new Schedule(this, "Schedule", new ScheduleProps {
Schedule = ScheduleExpression.Rate(Duration.Minutes(10)),
Target = target,
Group = group
});
Disabling Schedules
By default, a schedule will be enabled. You can disable a schedule by setting the enabled
property to false:
LambdaInvoke target;
new Schedule(this, "Schedule", new ScheduleProps {
Schedule = ScheduleExpression.Rate(Duration.Minutes(10)),
Target = target,
Enabled = false
});
Configuring a start and end time of the Schedule
If you choose a recurring schedule, you can set the start and end time of the Schedule by specifying the start
and end
.
LambdaInvoke target;
new Schedule(this, "Schedule", new ScheduleProps {
Schedule = ScheduleExpression.Rate(Duration.Hours(12)),
Target = target,
Start = new Date("2023-01-01T00:00:00.000Z"),
End = new Date("2023-02-01T00:00:00.000Z")
});
Scheduler Targets
The @aws-cdk/aws-scheduler-targets-alpha
module includes classes that implement the IScheduleTarget
interface for
various AWS services. EventBridge Scheduler supports two types of targets: templated targets invoke common API
operations across a core groups of services, and customizable universal targets that you can use to call more
than 6,000 operations across over 270 services. A list of supported targets can be found at @aws-cdk/aws-scheduler-targets-alpha
.
Input
Target can be invoked with a custom input. Class ScheduleTargetInput
supports free form text input and JSON-formatted object input:
var input = ScheduleTargetInput.FromObject(new Dictionary<string, string> {
{ "QueueName", "MyQueue" }
});
You can include context attributes in your target payload. EventBridge Scheduler will replace each keyword with its respective value and deliver it to the target. See full list of supported context attributes:
var text = $"Attempt number: {ContextAttribute.attemptNumber}";
var input = ScheduleTargetInput.FromText(text);
Specifying Execution Role
An execution role is an IAM role that EventBridge Scheduler assumes in order to interact with other AWS services on your behalf.
The classes for templated schedule targets automatically create an IAM role with all the minimum necessary
permissions to interact with the templated target. If you wish you may specify your own IAM role, then the templated targets
will grant minimal required permissions. For example: for invoking Lambda function target LambdaInvoke
will grant
execution IAM role permission to lambda:InvokeFunction
.
Function fn;
var role = new Role(this, "Role", new RoleProps {
AssumedBy = new ServicePrincipal("scheduler.amazonaws.com")
});
var target = new LambdaInvoke(fn, new ScheduleTargetBaseProps {
Input = ScheduleTargetInput.FromObject(new Dictionary<string, string> {
{ "payload", "useful" }
}),
Role = role
});
Cross-account and cross-region targets
Executing cross-account and cross-region targets are not supported yet.
Specifying Encryption key
EventBridge Scheduler integrates with AWS Key Management Service (AWS KMS) to encrypt and decrypt your data using an AWS KMS key. EventBridge Scheduler supports two types of KMS keys: AWS owned keys, and customer managed keys.
By default, all events in Scheduler are encrypted with a key that AWS owns and manages.
If you wish you can also provide a customer managed key to encrypt and decrypt the payload that your schedule delivers to its target using the key
property.
Target classes will automatically add AWS KMS Decrypt permission to your schedule's execution role permissions policy.
Key key;
Function fn;
var target = new LambdaInvoke(fn, new ScheduleTargetBaseProps {
Input = ScheduleTargetInput.FromObject(new Dictionary<string, string> {
{ "payload", "useful" }
})
});
var schedule = new Schedule(this, "Schedule", new ScheduleProps {
Schedule = ScheduleExpression.Rate(Duration.Minutes(10)),
Target = target,
Key = key
});
Visit <a href="https://docs.aws.amazon.com/scheduler/latest/UserGuide/data-protection.html">Data protection in Amazon EventBridge Scheduler</a> for more details.
Configuring flexible time windows
You can configure flexible time windows by specifying the timeWindow
property.
Flexible time windows is disabled by default.
LambdaInvoke target;
var schedule = new Schedule(this, "Schedule", new ScheduleProps {
Schedule = ScheduleExpression.Rate(Duration.Hours(12)),
Target = target,
TimeWindow = TimeWindow.Flexible(Duration.Hours(10))
});
Visit <a href="https://docs.aws.amazon.com/scheduler/latest/UserGuide/managing-schedule-flexible-time-windows.html">Configuring flexible time windows</a> for more details.
Error-handling
You can configure how your schedule handles failures, when EventBridge Scheduler is unable to deliver an event successfully to a target, by using two primary mechanisms: a retry policy, and a dead-letter queue (DLQ).
A retry policy determines the number of times EventBridge Scheduler must retry a failed event, and how long to keep an unprocessed event.
A DLQ is a standard Amazon SQS queue EventBridge Scheduler uses to deliver failed events to, after the retry policy has been exhausted. You can use a DLQ to troubleshoot issues with your schedule or its downstream target. If you've configured a retry policy for your schedule, EventBridge Scheduler delivers the dead-letter event after exhausting the maximum number of retries you set in the retry policy.
Function fn;
var dlq = new Queue(this, "DLQ", new QueueProps {
QueueName = "MyDLQ"
});
var target = new LambdaInvoke(fn, new ScheduleTargetBaseProps {
DeadLetterQueue = dlq,
MaxEventAge = Duration.Minutes(1),
RetryAttempts = 3
});
Overriding Target Properties
If you wish to reuse the same target in multiple schedules, you can override target properties like input
,
retryAttempts
and maxEventAge
when creating a Schedule using the targetOverrides
parameter:
LambdaInvoke target;
var oneTimeSchedule = new Schedule(this, "Schedule", new ScheduleProps {
Schedule = ScheduleExpression.Rate(Duration.Hours(12)),
Target = target,
TargetOverrides = new ScheduleTargetProps {
Input = ScheduleTargetInput.FromText("Overriding Target Input"),
MaxEventAge = Duration.Seconds(180),
RetryAttempts = 5
}
});
Monitoring
You can monitor Amazon EventBridge Scheduler using CloudWatch, which collects raw data and processes it into readable, near real-time metrics. EventBridge Scheduler emits a set of metrics for all schedules, and an additional set of metrics for schedules that have an associated dead-letter queue (DLQ). If you configure a DLQ for your schedule, EventBridge Scheduler publishes additional metrics when your schedule exhausts its retry policy.
Metrics for all schedules
Class Schedule
provides static methods for accessing all schedules metrics with default configuration,
such as metricAllErrors
for viewing errors when executing targets.
new Alarm(this, "SchedulesErrorAlarm", new AlarmProps {
Metric = Schedule.MetricAllErrors(),
Threshold = 0,
EvaluationPeriods = 1
});
Metrics for a Group
To view metrics for a specific group you can use methods on class Group
:
var group = new Group(this, "Group", new GroupProps {
GroupName = "MyGroup"
});
new Alarm(this, "MyGroupErrorAlarm", new AlarmProps {
Metric = group.MetricTargetErrors(),
EvaluationPeriods = 1,
Threshold = 0
});
// Or use default group
var defaultGroup = Group.FromDefaultGroup(this, "DefaultGroup");
new Alarm(this, "DefaultGroupErrorAlarm", new AlarmProps {
Metric = defaultGroup.MetricTargetErrors(),
EvaluationPeriods = 1,
Threshold = 0
});
See full list of metrics and their description at Monitoring Using CloudWatch Metrics in the AWS Event Bridge Scheduler User Guide.
Classes
ContextAttribute | (experimental) Represents a field in the event pattern. |
CronOptionsWithTimezone | (experimental) Options to configure a cron expression. |
Group | |
GroupProps | |
Schedule | (experimental) An EventBridge Schedule. |
ScheduleExpression | (experimental) ScheduleExpression for EventBridge Schedule. |
ScheduleProps | (experimental) Construction properties for |
ScheduleTargetConfig | (experimental) Config of a Schedule Target used during initialization of Schedule. |
ScheduleTargetInput | (experimental) The text, or well-formed JSON, passed to the target of the schedule. |
ScheduleTargetProps | |
TimeWindow | (experimental) A time window during which EventBridge Scheduler invokes the schedule. |
Interfaces
ICronOptionsWithTimezone | (experimental) Options to configure a cron expression. |
IGroup | |
IGroupProps | |
ISchedule | (experimental) Interface representing a created or an imported |
IScheduleProps | (experimental) Construction properties for |
IScheduleTarget | (experimental) Interface representing a Event Bridge Schedule Target. |
IScheduleTargetConfig | (experimental) Config of a Schedule Target used during initialization of Schedule. |
IScheduleTargetProps |