feat(scheduler): start and end time for schedule construct

packages/@aws-cdk/aws-scheduler-alpha/README.md

@@ -138,6 +138,21 @@ new Schedule(this, 'Schedule', {
 });
 ```
 
+### 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 startDate and endDate.
+These values must follow the format `yyyy-MM-ddTHH:mm:ss.SSSZ`.
+
+```ts
+declare const target: targets.LambdaInvoke;
+
+new Schedule(this, 'Schedule', {
+    schedule: ScheduleExpression.rate(cdk.Duration.hours(12)),
+    target: target,
+    startDate: '2023-01-01T00:00:00.000Z',
+    endDate: '2023-02-01T00:00:00.000Z',
+});
+```
 
 ## Scheduler Targets
 

packages/@aws-cdk/aws-scheduler-alpha/lib/schedule.ts

@@ -114,6 +114,26 @@ export interface ScheduleProps {
    * @default - All events in Scheduler are encrypted with a key that AWS owns and manages.
    */
   readonly key?: kms.IKey;
+
+  /**
+   * The date, in UTC, after which the schedule can begin invoking its target.
+   * EventBridge Scheduler ignores startDate for one-time schedules.
+   *
+   * Specify an absolute time in the ISO 8601 format. For example, 2020-12-01T00:00:00.000Z.
+   *
+   * @default - no value
+   */
+  readonly startDate?: string;
+
+  /**
+   * The date, in UTC, before which the schedule can invoke its target.
+   * EventBridge Scheduler ignores endDate for one-time schedules.
+   *
+   * Specify an absolute time in the ISO 8601 format. For example, 2020-12-01T00:00:00.000Z.
+   *
+   * @default - no value
+   */
+  readonly endDate?: string;
 }
 
 /**
@@ -213,6 +233,8 @@ export class Schedule extends Resource implements ISchedule {
     return this.metricAll('InvocationsSentToDeadLetterCount_Truncated_MessageSizeExceeded', props);
   }
 
+  private static readonly ISO8601_REGEX = /^(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])\.[0-9]{3}(Z)?$/;
+
   /**
    * The schedule group associated with this schedule.
    */
@@ -254,6 +276,8 @@ export class Schedule extends Resource implements ISchedule {
 
     this.retryPolicy = targetConfig.retryPolicy;
 
+    this.validateTimeFrame(props.startDate, props.endDate);
+
     const resource = new CfnSchedule(this, 'Resource', {
       name: this.physicalName,
       flexibleTimeWindow: { mode: 'OFF' },
@@ -276,6 +300,8 @@ export class Schedule extends Resource implements ISchedule {
         sageMakerPipelineParameters: targetConfig.sageMakerPipelineParameters,
         sqsParameters: targetConfig.sqsParameters,
       },
+      startDate: props.startDate,
+      endDate: props.endDate,
     });
 
     this.scheduleName = this.getResourceNameAttribute(resource.ref);
@@ -306,4 +332,22 @@ export class Schedule extends Resource implements ISchedule {
     const isEmptyPolicy = Object.values(policy).every(value => value === undefined);
     return !isEmptyPolicy ? policy : undefined;
   }
-}
+
+  private validateTimeFrame(startDate?: string, endDate?: string) {
+    if (startDate && !Schedule.ISO8601_REGEX.test(startDate)) {
+      throw new Error(`startDate needs to follow the format yyyy-MM-ddTHH:mm:ss.SSSZ but got ${startDate}`);
+    }
+    if (endDate && !Schedule.ISO8601_REGEX.test(endDate)) {
+      throw new Error(`endDate needs to follow the format yyyy-MM-ddTHH:mm:ss.SSSZ but got ${endDate}`);
+    }
+
+    if (startDate && endDate) {
+      const start = new Date(startDate);
+      const end = new Date(endDate);
+
+      if (end <= start) {
+        throw new Error(`startDate must come before the endDate but got startDate: ${startDate}, endDate: ${endDate}`);
+      }
+    }
+  }
+}

packages/@aws-cdk/aws-scheduler-alpha/test/integ.schedule.js.snapshot/aws-cdk-scheduler-schedule.template.json

@@ -348,6 +348,38 @@
      }
     }
    }
+  },
+  "ScheduleWithTimeFrameC1C8BDCC": {
+   "Type": "AWS::Scheduler::Schedule",
+   "Properties": {
+    "EndDate": "2025-10-01T00:00:00.000Z",
+    "FlexibleTimeWindow": {
+     "Mode": "OFF"
+    },
+    "ScheduleExpression": "rate(12 hours)",
+    "ScheduleExpressionTimezone": "Etc/UTC",
+    "StartDate": "2024-04-15T06:30:00.000Z",
+    "State": "ENABLED",
+    "Target": {
+     "Arn": {
+      "Fn::GetAtt": [
+       "Function76856677",
+       "Arn"
+      ]
+     },
+     "Input": "\"Input Text\"",
+     "RetryPolicy": {
+      "MaximumEventAgeInSeconds": 180,
+      "MaximumRetryAttempts": 3
+     },
+     "RoleArn": {
+      "Fn::GetAtt": [
+       "Role1ABCC5F0",
+       "Arn"
+      ]
+     }
+    }
+   }
   }
  },
  "Parameters": {

packages/@aws-cdk/aws-scheduler-alpha/test/integ.schedule.ts

@@ -90,6 +90,13 @@ new scheduler.Schedule(stack, 'CustomerKmsSchedule', {
   key,
 });
 
+new scheduler.Schedule(stack, 'ScheduleWithTimeFrame', {
+  schedule: expression,
+  target: target,
+  startDate: `${new Date().getFullYear() + 1}-04-15T06:30:00.000Z`,
+  endDate: `${new Date().getFullYear() + 2}-10-01T00:00:00.000Z`,
+});
+
 new IntegTest(app, 'integtest-schedule', {
   testCases: [stack],
 });