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

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

@@ -138,6 +138,20 @@ 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 `start` and `end`.
+
+```ts
+declare const target: targets.LambdaInvoke;
+
+new Schedule(this, 'Schedule', {
+    schedule: ScheduleExpression.rate(cdk.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
 

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

@@ -114,6 +114,22 @@ 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 start for one-time schedules.
+   *
+   * @default - no value
+   */
+  readonly start?: Date;
+
+  /**
+   * The date, in UTC, before which the schedule can invoke its target.
+   * EventBridge Scheduler ignores end for one-time schedules.
+   *
+   * @default - no value
+   */
+  readonly end?: Date;
 }
 
 /**
@@ -254,6 +270,8 @@ export class Schedule extends Resource implements ISchedule {
 
     this.retryPolicy = targetConfig.retryPolicy;
 
+    this.validateTimeFrame(props.start, props.end);
+
     const resource = new CfnSchedule(this, 'Resource', {
       name: this.physicalName,
       flexibleTimeWindow: { mode: 'OFF' },
@@ -276,6 +294,8 @@ export class Schedule extends Resource implements ISchedule {
         sageMakerPipelineParameters: targetConfig.sageMakerPipelineParameters,
         sqsParameters: targetConfig.sqsParameters,
       },
+      startDate: props.start?.toISOString(),
+      endDate: props.end?.toISOString(),
     });
 
     this.scheduleName = this.getResourceNameAttribute(resource.ref);
@@ -306,4 +326,10 @@ export class Schedule extends Resource implements ISchedule {
     const isEmptyPolicy = Object.values(policy).every(value => value === undefined);
     return !isEmptyPolicy ? policy : undefined;
   }
-}
+
+  private validateTimeFrame(start?: Date, end?: Date) {
+    if (start && end && start >= end) {
+      throw new Error(`start must precede end, got start: ${start.toISOString()}, end: ${end.toISOString()}`);
+    }
+  }
+}

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,14 @@ new scheduler.Schedule(stack, 'CustomerKmsSchedule', {
   key,
 });
 
+const currentYear = new Date().getFullYear();
+new scheduler.Schedule(stack, 'ScheduleWithTimeFrame', {
+  schedule: expression,
+  target: target,
+  start: new Date(`${currentYear + 1}-04-15T06:30:00.000Z`),
+  end: new Date(`${currentYear + 2}-10-01T00:00:00.000Z`),
+});
+
 new IntegTest(app, 'integtest-schedule', {
   testCases: [stack],
 });

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

@@ -128,4 +128,37 @@ describe('Schedule', () => {
       },
     });
   });
-});
+
+  describe('schedule timeFrame', () => {
+    test.each([
+      { StartDate: '2023-04-15T06:20:00.000Z', EndDate: '2023-10-01T00:00:00.000Z' },
+      { StartDate: '2023-04-15T06:25:00.000Z' },
+      { EndDate: '2023-10-01T00:00:00.000Z' },
+    ])('schedule can set start and end', (timeFrame) => {
+      new Schedule(stack, 'TestSchedule', {
+        schedule: expr,
+        target: new SomeLambdaTarget(func, role),
+        start: timeFrame.StartDate ? new Date(timeFrame.StartDate) : undefined,
+        end: timeFrame.EndDate ? new Date(timeFrame.EndDate) : undefined,
+      });
+
+      Template.fromStack(stack).hasResourceProperties('AWS::Scheduler::Schedule', {
+        ...timeFrame,
+      });
+    });
+
+    test.each([
+      { start: '2023-10-01T00:00:00.000Z', end: '2023-10-01T00:00:00.000Z' },
+      { start: '2023-10-01T00:00:00.000Z', end: '2023-09-01T00:00:00.000Z' },
+    ])('throw error when start does not come before end', ({ start, end }) => {
+      expect(() => {
+        new Schedule(stack, 'TestSchedule', {
+          schedule: expr,
+          target: new SomeLambdaTarget(func, role),
+          start: new Date(start),
+          end: new Date(end),
+        });
+      }).toThrow(`start must precede end, got start: ${start}, end: ${end}`);
+    });
+  });
+});