ec2-instance-running-scheduler 0.3.6 → 0.4.0

package/API.md

@@ -10,7 +10,11 @@ Each schedule invokes the function with `Params` (`TagKey`, `TagValues`, `Mode`)
 the Resource Groups Tagging API and EC2 APIs; Slack notifications use the secret named in {@link Secrets.slackSecretName}.
 
 Per-instance wait timeouts are configured via {@link EC2InstanceRunningSchedulerProps.resourceWait}
-and enforced in the handler before the Durable execution timeout. Optional CloudWatch failure
+and enforced in the handler before the Durable execution timeout. Lambda memory, invoke timeout,
+and map concurrency are set via {@link EC2InstanceRunningSchedulerProps.runtime}; Durable
+execution timeout and history retention via {@link EC2InstanceRunningSchedulerProps.durable};
+log retention via {@link EC2InstanceRunningSchedulerProps.logGroup}. Start/stop IAM is limited
+to instances tagged as {@link TargetResource}. Optional CloudWatch failure
 detection is available via {@link EC2InstanceRunningSchedulerProps.failureDetection}.
 
 #### Initializers <a name="Initializers" id="ec2-instance-running-scheduler.EC2InstanceRunningScheduler.Initializer"></a>
@@ -25,7 +29,7 @@ new EC2InstanceRunningScheduler(scope: Construct, id: string, props: EC2Instance
 | --- | --- | --- |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduler.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | - Parent construct. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduler.Initializer.parameter.id">id</a></code> | <code>string</code> | - Construct id. |
-| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduler.Initializer.parameter.props">props</a></code> | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps">EC2InstanceRunningSchedulerProps</a></code> | - Target tags, schedules, Slack secret, schedule enable flag, optional {@link ResourceWaitLimits}, and optional {@link FailureDetectionAlarms}. |
+| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduler.Initializer.parameter.props">props</a></code> | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps">EC2InstanceRunningSchedulerProps</a></code> | - Target tags, schedules, Slack secret, schedule enable flag, optional {@link ResourceWaitLimits}, {@link RunningSchedulerRuntimeProps}, {@link RunningSchedulerDurableProps}, {@link RunningSchedulerLogGroupProps}, and optional {@link FailureDetectionAlarms}. |
 
 ---
 
@@ -49,7 +53,7 @@ Construct id.
 
 - *Type:* <a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps">EC2InstanceRunningSchedulerProps</a>
 
-Target tags, schedules, Slack secret, schedule enable flag, optional {@link ResourceWaitLimits}, and optional {@link FailureDetectionAlarms}.
+Target tags, schedules, Slack secret, schedule enable flag, optional {@link ResourceWaitLimits}, {@link RunningSchedulerRuntimeProps}, {@link RunningSchedulerDurableProps}, {@link RunningSchedulerLogGroupProps}, and optional {@link FailureDetectionAlarms}.
 
 ---
 
@@ -170,8 +174,10 @@ Failure detection alarms, when {@link EC2InstanceRunningSchedulerProps.failureDe
 CDK stack that deploys the EC2 instance running scheduler (EventBridge Scheduler + Durable Lambda).
 
 Wires {@link EC2InstanceRunningScheduler} with targeting, schedules, secrets, scheduling toggle,
-and optional {@link FailureDetectionAlarms}. Does not expose {@link ResourceWaitLimits }; use the
-construct directly when custom per-instance wait limits are required.
+and optional {@link FailureDetectionAlarms}. Does not expose {@link ResourceWaitLimits },
+{@link RunningSchedulerRuntimeProps }, {@link RunningSchedulerDurableProps }, or
+{@link RunningSchedulerLogGroupProps }; use the construct directly when custom runtime,
+wait, durable, or log group settings are required.
 
 #### Initializers <a name="Initializers" id="ec2-instance-running-scheduler.EC2InstanceRunningScheduleStack.Initializer"></a>
 
@@ -1362,9 +1368,12 @@ const eC2InstanceRunningSchedulerProps: EC2InstanceRunningSchedulerProps = { ...
 | --- | --- | --- |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.secrets">secrets</a></code> | <code><a href="#ec2-instance-running-scheduler.Secrets">Secrets</a></code> | Secrets (e.g. Slack) used for notifications. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.targetResource">targetResource</a></code> | <code><a href="#ec2-instance-running-scheduler.TargetResource">TargetResource</a></code> | Tag-based targeting for EC2 instances to start/stop. |
+| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.durable">durable</a></code> | <code><a href="#ec2-instance-running-scheduler.RunningSchedulerDurableProps">RunningSchedulerDurableProps</a></code> | Durable Execution timeout and history retention. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.enableScheduling">enableScheduling</a></code> | <code>boolean</code> | Whether EventBridge Scheduler rules are enabled. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.failureDetection">failureDetection</a></code> | <code><a href="#ec2-instance-running-scheduler.FailureDetectionAlarms">FailureDetectionAlarms</a></code> | Optional CloudWatch alarms and log-based metrics for failure detection. |
+| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.logGroup">logGroup</a></code> | <code><a href="#ec2-instance-running-scheduler.RunningSchedulerLogGroupProps">RunningSchedulerLogGroupProps</a></code> | CloudWatch Logs retention and removal policy for the function log group. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.resourceWait">resourceWait</a></code> | <code><a href="#ec2-instance-running-scheduler.ResourceWaitLimits">ResourceWaitLimits</a></code> | Per-instance wait limits for the running scheduler Lambda. |
+| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.runtime">runtime</a></code> | <code><a href="#ec2-instance-running-scheduler.RunningSchedulerRuntimeProps">RunningSchedulerRuntimeProps</a></code> | Lambda memory, invoke timeout, and per-invocation instance concurrency. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.startSchedule">startSchedule</a></code> | <code><a href="#ec2-instance-running-scheduler.Schedule">Schedule</a></code> | Cron schedule for starting instances. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.stopSchedule">stopSchedule</a></code> | <code><a href="#ec2-instance-running-scheduler.Schedule">Schedule</a></code> | Cron schedule for stopping instances. |
 
@@ -1394,6 +1403,19 @@ Tag-based targeting for EC2 instances to start/stop.
 
 ---
 
+##### `durable`<sup>Optional</sup> <a name="durable" id="ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.durable"></a>
+
+```typescript
+public readonly durable: RunningSchedulerDurableProps;
+```
+
+- *Type:* <a href="#ec2-instance-running-scheduler.RunningSchedulerDurableProps">RunningSchedulerDurableProps</a>
+- *Default:* executionTimeout 2 hours, retentionPeriod 1 day
+
+Durable Execution timeout and history retention.
+
+---
+
 ##### `enableScheduling`<sup>Optional</sup> <a name="enableScheduling" id="ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.enableScheduling"></a>
 
 ```typescript
@@ -1423,6 +1445,19 @@ Set `enabled: true` to create alarms; optionally pass `alarmTopic` for SNS notif
 
 ---
 
+##### `logGroup`<sup>Optional</sup> <a name="logGroup" id="ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.logGroup"></a>
+
+```typescript
+public readonly logGroup: RunningSchedulerLogGroupProps;
+```
+
+- *Type:* <a href="#ec2-instance-running-scheduler.RunningSchedulerLogGroupProps">RunningSchedulerLogGroupProps</a>
+- *Default:* RetentionDays.THREE_MONTHS, RemovalPolicy.DESTROY
+
+CloudWatch Logs retention and removal policy for the function log group.
+
+---
+
 ##### `resourceWait`<sup>Optional</sup> <a name="resourceWait" id="ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.resourceWait"></a>
 
 ```typescript
@@ -1436,6 +1471,19 @@ Per-instance wait limits for the running scheduler Lambda.
 
 ---
 
+##### `runtime`<sup>Optional</sup> <a name="runtime" id="ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.runtime"></a>
+
+```typescript
+public readonly runtime: RunningSchedulerRuntimeProps;
+```
+
+- *Type:* <a href="#ec2-instance-running-scheduler.RunningSchedulerRuntimeProps">RunningSchedulerRuntimeProps</a>
+- *Default:* 512 MB, 15 minutes, {@link DEFAULT_MAX_CONCURRENCY } (10)
+
+Lambda memory, invoke timeout, and per-invocation instance concurrency.
+
+---
+
 ##### `startSchedule`<sup>Optional</sup> <a name="startSchedule" id="ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.startSchedule"></a>
 
 ```typescript
@@ -1464,7 +1512,9 @@ Cron schedule for stopping instances.
 
 Props for the EC2 instance running schedule CDK stack.
 
-> [{@link EC2InstanceRunningSchedulerProps } for construct-level options not exposed here (e.g. `resourceWait`).]({@link EC2InstanceRunningSchedulerProps } for construct-level options not exposed here (e.g. `resourceWait`).)
+> [{@link EC2InstanceRunningSchedulerProps } for construct-level options not exposed here
+(e.g. `resourceWait`, `runtime`, `durable`, `logGroup`).]({@link EC2InstanceRunningSchedulerProps } for construct-level options not exposed here
+(e.g. `resourceWait`, `runtime`, `durable`, `logGroup`).)
 
 #### Initializer <a name="Initializer" id="ec2-instance-running-scheduler.EC2InstanceRunningScheduleStackProps.Initializer"></a>
 
@@ -1893,6 +1943,7 @@ const resourceWaitLimits: ResourceWaitLimits = { ... }
 | --- | --- | --- |
 | <code><a href="#ec2-instance-running-scheduler.ResourceWaitLimits.property.maxElapsedSeconds">maxElapsedSeconds</a></code> | <code>number</code> | Maximum wall-clock seconds spent waiting for a single instance to stabilize. |
 | <code><a href="#ec2-instance-running-scheduler.ResourceWaitLimits.property.maxLoopCount">maxLoopCount</a></code> | <code>number</code> | Maximum describe/wait loop iterations per instance. |
+| <code><a href="#ec2-instance-running-scheduler.ResourceWaitLimits.property.statusChangeWaitSeconds">statusChangeWaitSeconds</a></code> | <code>number</code> | Seconds to wait between describe iterations after start/stop or while transitioning. |
 
 ---
 
@@ -1922,6 +1973,70 @@ Maximum describe/wait loop iterations per instance.
 
 ---
 
+##### `statusChangeWaitSeconds`<sup>Optional</sup> <a name="statusChangeWaitSeconds" id="ec2-instance-running-scheduler.ResourceWaitLimits.property.statusChangeWaitSeconds"></a>
+
+```typescript
+public readonly statusChangeWaitSeconds: number;
+```
+
+- *Type:* number
+- *Default:* {@link DEFAULT_RESOURCE_WAIT_LIMITS.statusChangeWaitSeconds } (20)
+
+Seconds to wait between describe iterations after start/stop or while transitioning.
+
+Lower values detect state changes sooner; higher values reduce DescribeInstances calls.
+
+---
+
+### RunningSchedulerDurableProps <a name="RunningSchedulerDurableProps" id="ec2-instance-running-scheduler.RunningSchedulerDurableProps"></a>
+
+Durable Execution timeout and history retention for the running scheduler Lambda.
+
+#### Initializer <a name="Initializer" id="ec2-instance-running-scheduler.RunningSchedulerDurableProps.Initializer"></a>
+
+```typescript
+import { RunningSchedulerDurableProps } from 'ec2-instance-running-scheduler'
+
+const runningSchedulerDurableProps: RunningSchedulerDurableProps = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#ec2-instance-running-scheduler.RunningSchedulerDurableProps.property.executionTimeout">executionTimeout</a></code> | <code>aws-cdk-lib.Duration</code> | Maximum duration of a durable execution. |
+| <code><a href="#ec2-instance-running-scheduler.RunningSchedulerDurableProps.property.retentionPeriod">retentionPeriod</a></code> | <code>aws-cdk-lib.Duration</code> | How long to retain durable execution history. |
+
+---
+
+##### `executionTimeout`<sup>Optional</sup> <a name="executionTimeout" id="ec2-instance-running-scheduler.RunningSchedulerDurableProps.property.executionTimeout"></a>
+
+```typescript
+public readonly executionTimeout: Duration;
+```
+
+- *Type:* aws-cdk-lib.Duration
+- *Default:* Duration.hours(2)
+
+Maximum duration of a durable execution.
+
+Increase when many instances are processed with long per-instance waits.
+
+---
+
+##### `retentionPeriod`<sup>Optional</sup> <a name="retentionPeriod" id="ec2-instance-running-scheduler.RunningSchedulerDurableProps.property.retentionPeriod"></a>
+
+```typescript
+public readonly retentionPeriod: Duration;
+```
+
+- *Type:* aws-cdk-lib.Duration
+- *Default:* Duration.days(1)
+
+How long to retain durable execution history.
+
+---
+
 ### RunningSchedulerFailureDetectionProps <a name="RunningSchedulerFailureDetectionProps" id="ec2-instance-running-scheduler.RunningSchedulerFailureDetectionProps"></a>
 
 Props for {@link RunningSchedulerFailureDetection}.
@@ -1980,6 +2095,120 @@ Running scheduler Lambda to monitor.
 
 ---
 
+### RunningSchedulerLogGroupProps <a name="RunningSchedulerLogGroupProps" id="ec2-instance-running-scheduler.RunningSchedulerLogGroupProps"></a>
+
+CloudWatch Logs settings for the running scheduler function log group.
+
+#### Initializer <a name="Initializer" id="ec2-instance-running-scheduler.RunningSchedulerLogGroupProps.Initializer"></a>
+
+```typescript
+import { RunningSchedulerLogGroupProps } from 'ec2-instance-running-scheduler'
+
+const runningSchedulerLogGroupProps: RunningSchedulerLogGroupProps = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#ec2-instance-running-scheduler.RunningSchedulerLogGroupProps.property.removalPolicy">removalPolicy</a></code> | <code>aws-cdk-lib.RemovalPolicy</code> | Removal policy for the log group. |
+| <code><a href="#ec2-instance-running-scheduler.RunningSchedulerLogGroupProps.property.retention">retention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | How long to retain application logs. |
+
+---
+
+##### `removalPolicy`<sup>Optional</sup> <a name="removalPolicy" id="ec2-instance-running-scheduler.RunningSchedulerLogGroupProps.property.removalPolicy"></a>
+
+```typescript
+public readonly removalPolicy: RemovalPolicy;
+```
+
+- *Type:* aws-cdk-lib.RemovalPolicy
+- *Default:* RemovalPolicy.DESTROY
+
+Removal policy for the log group.
+
+---
+
+##### `retention`<sup>Optional</sup> <a name="retention" id="ec2-instance-running-scheduler.RunningSchedulerLogGroupProps.property.retention"></a>
+
+```typescript
+public readonly retention: RetentionDays;
+```
+
+- *Type:* aws-cdk-lib.aws_logs.RetentionDays
+- *Default:* RetentionDays.THREE_MONTHS
+
+How long to retain application logs.
+
+---
+
+### RunningSchedulerRuntimeProps <a name="RunningSchedulerRuntimeProps" id="ec2-instance-running-scheduler.RunningSchedulerRuntimeProps"></a>
+
+Lambda invoke settings and bounded parallelism for the running scheduler function.
+
+Increase {@link memorySize} and {@link maxConcurrency} when a single invocation targets
+many instances or regions.
+
+#### Initializer <a name="Initializer" id="ec2-instance-running-scheduler.RunningSchedulerRuntimeProps.Initializer"></a>
+
+```typescript
+import { RunningSchedulerRuntimeProps } from 'ec2-instance-running-scheduler'
+
+const runningSchedulerRuntimeProps: RunningSchedulerRuntimeProps = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#ec2-instance-running-scheduler.RunningSchedulerRuntimeProps.property.maxConcurrency">maxConcurrency</a></code> | <code>number</code> | Maximum number of instances processed in parallel by the durable `map`. |
+| <code><a href="#ec2-instance-running-scheduler.RunningSchedulerRuntimeProps.property.memorySize">memorySize</a></code> | <code>number</code> | Memory allocated to the running scheduler Lambda, in MB. |
+| <code><a href="#ec2-instance-running-scheduler.RunningSchedulerRuntimeProps.property.timeout">timeout</a></code> | <code>aws-cdk-lib.Duration</code> | Invoke timeout for the Lambda function (not the durable execution timeout). |
+
+---
+
+##### `maxConcurrency`<sup>Optional</sup> <a name="maxConcurrency" id="ec2-instance-running-scheduler.RunningSchedulerRuntimeProps.property.maxConcurrency"></a>
+
+```typescript
+public readonly maxConcurrency: number;
+```
+
+- *Type:* number
+- *Default:* {@link DEFAULT_MAX_CONCURRENCY } (10)
+
+Maximum number of instances processed in parallel by the durable `map`.
+
+---
+
+##### `memorySize`<sup>Optional</sup> <a name="memorySize" id="ec2-instance-running-scheduler.RunningSchedulerRuntimeProps.property.memorySize"></a>
+
+```typescript
+public readonly memorySize: number;
+```
+
+- *Type:* number
+- *Default:* 512
+
+Memory allocated to the running scheduler Lambda, in MB.
+
+---
+
+##### `timeout`<sup>Optional</sup> <a name="timeout" id="ec2-instance-running-scheduler.RunningSchedulerRuntimeProps.property.timeout"></a>
+
+```typescript
+public readonly timeout: Duration;
+```
+
+- *Type:* aws-cdk-lib.Duration
+- *Default:* Duration.minutes(15)
+
+Invoke timeout for the Lambda function (not the durable execution timeout).
+
+AWS Lambda's maximum invoke timeout is 15 minutes. Durable waits can continue
+beyond this via {@link RunningSchedulerDurableProps.executionTimeout}.
+
+---
+
 ### Schedule <a name="Schedule" id="ec2-instance-running-scheduler.Schedule"></a>
 
 Cron-style schedule configuration for start/stop actions.
@@ -2087,6 +2316,10 @@ Name of the Secrets Manager secret containing Slack token and channel.
 
 Defines which EC2 instances are targeted by tag key and values.
 
+Instances must already have this tag. IAM allows `ec2:StartInstances` /
+`ec2:StopInstances` only on instances in the stack account and region whose
+`aws:ResourceTag/<tagKey>` matches one of {@link TargetResource.tagValues}.
+
 #### Initializer <a name="Initializer" id="ec2-instance-running-scheduler.TargetResource.Initializer"></a>
 
 ```typescript

package/README.md

@@ -4,6 +4,7 @@
 [![npm](https://img.shields.io/npm/v/ec2-instance-running-scheduler?style=flat-square)](https://www.npmjs.com/package/ec2-instance-running-scheduler)
 [![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/release.yml?branch=main&label=release&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/actions/workflows/release.yml)
 [![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler?sort=semver&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/releases)
+
 [![View on Construct Hub](https://constructs.dev/badge?package=ec2-instance-running-scheduler)](https://constructs.dev/packages/ec2-instance-running-scheduler)
 
 AWS CDK construct library that starts and stops EC2 instances on a cron schedule using **EventBridge Scheduler** and a **Durable Execution Lambda**. The handler discovers instances with the **Resource Groups Tagging API**, issues start/stop, **waits until each instance reaches a stable target state** (durable `step` / `wait`), processes **multiple instances in parallel** (bounded concurrency), and posts **Slack** summary and per-instance thread messages using a secret from **Secrets Manager**. The Lambda emits **structured application logs** alongside JSON platform logs.
@@ -13,15 +14,17 @@ AWS CDK construct library that starts and stops EC2 instances on a cron schedule
 - **Tag-based targeting** – Select EC2 instances by tag key and values (e.g. `Schedule` / `YES`) via `tag:GetResources`.
 - **EventBridge Scheduler** – Separate cron rules for start and stop, with per-rule timezone (`aws-cdk-lib` `TimeZone`).
 - **Durable Lambda** – One Lambda with AWS Lambda Durable Execution (`step`, `wait`, `map`, child contexts per instance) for long-running workflows without Step Functions.
-- **Stable-state waiting** – After start/stop, the function waits (20 seconds between attempts) and re-describes instances until `running` (start mode) or `stopped` (stop mode).
-- **Configurable wait limits** – Per-instance **max loop count** and **max elapsed time** via `resourceWait` (default: 90 loops / 1800 seconds). Failures use explicit `ResourceWaitFailed:*` messages instead of running until the Durable execution timeout (construct default: 2 hours).
-- **Validated environment variables** – The bundled handler parses env vars with **strict-env-resolver** (`StrictEnvResolver`). `SLACK_SECRET_NAME` is required; wait limits must be **finite positive numbers** (`> 0`).
+- **Stable-state waiting** – After start/stop, the function waits (`resourceWait.statusChangeWaitSeconds`, default **20** seconds between attempts) and re-describes instances until `running` (start mode) or `stopped` (stop mode).
+- **Configurable wait limits** – Per-instance **max loop count**, **max elapsed time**, and **status-change wait interval** via `resourceWait` (default: 90 loops / 1800 seconds / 20 seconds). Failures use explicit `ResourceWaitFailed:*` messages instead of running until the Durable execution timeout (construct default: 2 hours; override with `durable.executionTimeout`).
+- **Configurable Lambda runtime** – Memory, invoke timeout, and bounded instance concurrency via `runtime` (default: **512 MB** / **15 minutes** / **maxConcurrency 10**). Durable execution timeout and history retention via `durable` (default: **2 hours** / **1 day**).
+- **Configurable logs** – Log group retention and removal policy via `logGroup` (default: **3 months**, `RemovalPolicy.DESTROY`).
+- **Validated environment variables** – The bundled handler parses env vars with **strict-env-resolver** (`StrictEnvResolver`). `SLACK_SECRET_NAME` is required; wait limits and `maxConcurrency` must be **positive integers** (`>= 1`).
 - **Slack notifications** – Parent message plus threaded updates per instance; credentials from Secrets Manager JSON (`token`, `channel`). The construct sets **`SLACK_SECRET_NAME`** on the function.
 - **Structured logging** – Durable execution **`ctx.logger`** for traceable JSON application logs (invocation, describe/start/stop/wait loops, wait limit errors, Slack steps, completion).
 - **Optional failure detection** – CloudWatch alarms and log-based metrics for Lambda errors, instance wait failures (`ResourceWaitFailed`), Slack post failures, and other handler `ERROR` logs. Optional SNS notifications via a caller-supplied topic (`failureDetection.alarmTopic`).
 - **Scheduling toggle** – Enable or disable both schedules without removing the stack (`enableScheduling`).
 - **Configurable schedules** – Optional cron overrides for start and stop (`minute`, `hour`, `week`, `timezone`); sensible defaults if omitted.
-- **IAM and observability** – EC2 and tagging API permissions, Slack secret read grant, **Parameters and Secrets Lambda Extension**, JSON logging, and a dedicated log group (construct defaults).
+- **IAM and observability** – Start/stop is limited to EC2 instances in the stack account/region whose tags match `targetResource`. Slack secret read grant, **Parameters and Secrets Lambda Extension**, JSON logging, and a dedicated log group (override retention and removal policy via `logGroup`).
 
 ## Installation
 
@@ -50,6 +53,7 @@ Use the **construct** `EC2InstanceRunningScheduler` when embedding the scheduler
 ```typescript
 import * as cdk from 'aws-cdk-lib';
 import { TimeZone } from 'aws-cdk-lib';
+import * as logs from 'aws-cdk-lib/aws-logs';
 import * as sns from 'aws-cdk-lib/aws-sns';
 import { EC2InstanceRunningScheduler } from 'ec2-instance-running-scheduler';
 
@@ -82,6 +86,20 @@ new EC2InstanceRunningScheduler(stack, 'EC2InstanceRunningScheduler', {
   resourceWait: {
     maxLoopCount: 120,
     maxElapsedSeconds: 3600,
+    statusChangeWaitSeconds: 15,
+  },
+  runtime: {
+    memorySize: 1024,
+    timeout: cdk.Duration.minutes(15),
+    maxConcurrency: 20,
+  },
+  durable: {
+    executionTimeout: cdk.Duration.hours(4),
+    retentionPeriod: cdk.Duration.days(7),
+  },
+  logGroup: {
+    retention: logs.RetentionDays.ONE_YEAR,
+    removalPolicy: cdk.RemovalPolicy.RETAIN,
   },
   failureDetection: {
     enabled: true,
@@ -90,7 +108,7 @@ new EC2InstanceRunningScheduler(stack, 'EC2InstanceRunningScheduler', {
 });
 ```
 
-Use the **stack** `EC2InstanceRunningScheduleStack` when deploying the scheduler as its own stack. It accepts the same **targeting, schedules, secrets, enable flag, and failure detection** as the construct (plus standard `StackProps` such as `env`). For **`resourceWait`**, use the construct directly or extend the stack in your app.
+Use the **stack** `EC2InstanceRunningScheduleStack` when deploying the scheduler as its own stack. It accepts the same **targeting, schedules, secrets, enable flag, and failure detection** as the construct (plus standard `StackProps` such as `env`). For **`resourceWait`**, **`runtime`**, **`durable`**, and **`logGroup`**, use the construct directly or extend the stack in your app.
 
 ```typescript
 import * as cdk from 'aws-cdk-lib';
@@ -134,6 +152,27 @@ new EC2InstanceRunningScheduleStack(app, 'EC2InstanceRunningScheduleStack', {
 });
 ```
 
+## Tag instances before scheduling
+
+The scheduler only starts and stops EC2 instances that **already** have the tag key and one of the tag values in `targetResource`. Tag instances in the same account and region as the stack **before** enabling schedules.
+
+**AWS CLI**
+
+```bash
+aws ec2 create-tags \
+  --resources i-0123456789abcdef0 \
+  --tags Key=Schedule,Value=YES
+```
+
+**Console** – EC2 → Instances → select the instance → Tags → Add `Schedule` = `YES` (or your `tagKey` / `tagValues`).
+
+IAM for `ec2:StartInstances` and `ec2:StopInstances` is limited to:
+
+- instance ARNs in the stack **account** and **region** (`arn:...:ec2:<region>:<account>:instance/*`)
+- instances whose `aws:ResourceTag/<tagKey>` matches one of `tagValues`
+
+An instance without the tag is not discovered by `tag:GetResources`, and start/stop is denied even if an instance ID is known. `tag:GetResources` and `ec2:DescribeInstances` still use `Resource: *` because those APIs do not support resource-level permissions or resource-tag conditions.
+
 EventBridge Scheduler invokes the Lambda with `Params.TagKey`, `Params.TagValues`, and `Params.Mode` (`Start` or `Stop`); the construct wires this for you. The function environment includes:
 
 | Variable | Source | Purpose |
@@ -141,8 +180,10 @@ EventBridge Scheduler invokes the Lambda with `Params.TagKey`, `Params.TagValues
 | `SLACK_SECRET_NAME` | `secrets.slackSecretName` | Secrets Manager secret for Slack (required) |
 | `PROCESS_RESOURCE_MAX_LOOP_COUNT` | `resourceWait.maxLoopCount` (default `90`) | Max describe/wait iterations per instance |
 | `PROCESS_RESOURCE_MAX_ELAPSED_SECONDS` | `resourceWait.maxElapsedSeconds` (default `1800`) | Max wall-clock seconds waiting for one instance |
+| `PROCESS_RESOURCE_STATUS_CHANGE_WAIT_SECONDS` | `resourceWait.statusChangeWaitSeconds` (default `20`) | Seconds between describe/wait iterations |
+| `PROCESS_RESOURCES_MAX_CONCURRENCY` | `runtime.maxConcurrency` (default `10`) | Max instances processed in parallel |
 
-When you set wait limits via `resourceWait`, the construct writes them as decimal integer strings. At invocation the handler parses them with **strict-env-resolver**; each value must be a **finite number greater than zero**. Missing `SLACK_SECRET_NAME` or invalid env values cause `StrictEnvValidationError` at the start of an invocation.
+When you set wait limits via `resourceWait` or concurrency via `runtime.maxConcurrency`, the construct writes them as decimal integer strings. At invocation the handler parses them with **strict-env-resolver**; each value must be a **positive integer** (`>= 1`). Missing `SLACK_SECRET_NAME` or invalid env values cause `StrictEnvValidationError` at the start of an invocation.
 
 ## Options
 
@@ -156,16 +197,21 @@ When you set wait limits via `resourceWait`, the construct writes them as decima
 | `stopSchedule` | `Schedule` | No | Cron for stopping instances (default: `5 19 ? * MON-FRI *` in `Etc/UTC`). |
 | `enableScheduling` | `boolean` | No | Whether both scheduler rules are enabled (default: `true`). |
 | `resourceWait` | `ResourceWaitLimits` | No | Per-instance wait caps (see below). |
+| `runtime` | `RunningSchedulerRuntimeProps` | No | Lambda memory, invoke timeout, and map concurrency. |
+| `durable` | `RunningSchedulerDurableProps` | No | Durable execution timeout and history retention. |
+| `logGroup` | `RunningSchedulerLogGroupProps` | No | Function log group retention and removal policy. |
 | `failureDetection` | `FailureDetectionAlarms` | No | Optional CloudWatch alarms and log-based metrics (see below). |
 
 ### EC2InstanceRunningScheduleStack
 
-Includes `targetResource`, `secrets`, `startSchedule`, `stopSchedule`, `enableScheduling`, `failureDetection`, and standard `StackProps`. Does **not** expose `resourceWait`; use `EC2InstanceRunningScheduler` when you need custom wait limits.
+Includes `targetResource`, `secrets`, `startSchedule`, `stopSchedule`, `enableScheduling`, `failureDetection`, and standard `StackProps`. Does **not** expose `resourceWait`, `runtime`, `durable`, or `logGroup`; use `EC2InstanceRunningScheduler` when you need custom wait, Lambda, Durable, or log settings.
 
 ### TargetResource
 
-- `tagKey` – Tag key used to select instances (e.g. `Schedule`).
-- `tagValues` – Tag values that must match (e.g. `['YES']`).
+- `tagKey` – Tag key used to select instances (e.g. `Schedule`). Required on each target instance before schedules run.
+- `tagValues` – Tag values that must match (e.g. `['YES']`). At least one value is required.
+
+See [Tag instances before scheduling](#tag-instances-before-scheduling).
 
 ### Schedule
 
@@ -180,13 +226,32 @@ Includes `targetResource`, `secrets`, `startSchedule`, `stopSchedule`, `enableSc
 
 ### ResourceWaitLimits
 
-Written to `PROCESS_RESOURCE_MAX_LOOP_COUNT` and `PROCESS_RESOURCE_MAX_ELAPSED_SECONDS` on the running scheduler Lambda.
+Written to `PROCESS_RESOURCE_MAX_LOOP_COUNT`, `PROCESS_RESOURCE_MAX_ELAPSED_SECONDS`, and `PROCESS_RESOURCE_STATUS_CHANGE_WAIT_SECONDS` on the running scheduler Lambda.
 
 - `maxLoopCount` – Maximum describe/wait loop iterations per instance (default: **90**). Must be a positive integer when set.
 - `maxElapsedSeconds` – Maximum wall-clock seconds spent waiting for one instance to stabilize (default: **1800**, 30 minutes). Must be a positive integer when set.
+- `statusChangeWaitSeconds` – Seconds between describe iterations after start/stop or while transitioning (default: **20**). Must be a positive integer when set.
 
 When a limit is exceeded during waiting, the handler throws an error with prefix `ResourceWaitFailed:` (`MaxLoopCountExceeded`, `MaxElapsedTimeExceeded`, or `UnexpectedInstanceState` for unknown EC2 states).
 
+### RunningSchedulerRuntimeProps
+
+Lambda invoke settings. Written `maxConcurrency` to `PROCESS_RESOURCES_MAX_CONCURRENCY`.
+
+- `memorySize` – Memory in MB (default: **512**). Must be a positive integer when set.
+- `timeout` – Lambda invoke timeout (default: **15 minutes**). AWS maximum is 15 minutes; durable waits continue under `durable.executionTimeout`.
+- `maxConcurrency` – Max instances processed in parallel (default: **10**). Must be a positive integer when set. Increase with instance count.
+
+### RunningSchedulerDurableProps
+
+- `executionTimeout` – Maximum durable execution duration (default: **2 hours**). Increase when many instances wait in sequence of batches.
+- `retentionPeriod` – Durable execution history retention (default: **1 day**).
+
+### RunningSchedulerLogGroupProps
+
+- `retention` – CloudWatch Logs retention (default: **`RetentionDays.THREE_MONTHS`**).
+- `removalPolicy` – Log group removal policy (default: **`RemovalPolicy.DESTROY`**).
+
 ### FailureDetectionAlarms
 
 Optional operational failure detection. Alarms are created only when `enabled` is `true`.
@@ -209,7 +274,7 @@ Custom metrics are published under the `EC2InstanceRunningScheduler` namespace.
 
 - **Node.js** ≥ 20.0.0 (for developing or synthesizing CDK apps that depend on this package).
 - **aws-cdk-lib** ^2.232.0 and **constructs** ^10.5.1 (peer dependencies).
-- **AWS** – EventBridge Scheduler; Lambda with **Durable Execution** (Node.js **24.x** runtime in the construct; Durable Execution requires a supported Node.js runtime in your region), a **live alias**, **Parameters and Secrets Lambda Extension**; EC2 (`DescribeInstances`, `StartInstances`, `StopInstances`); Resource Groups Tagging API (`tag:GetResources`); Secrets Manager. The deployed function uses **arm64**, Durable Execution IAM policies, a 2-hour Durable execution timeout (construct default), and a bundled handler that loads secrets via **aws-lambda-secret-fetcher** (^0.6) and parses env vars via **strict-env-resolver** (^0.5). Secret fetch runs only inside Lambda (requires runtime `AWS_SESSION_TOKEN` and the extension layer); the library retries transient extension errors including cold-start "not ready" responses.
+- **AWS** – EventBridge Scheduler; Lambda with **Durable Execution** (Node.js **24.x** runtime in the construct; Durable Execution requires a supported Node.js runtime in your region), a **live alias**, **Parameters and Secrets Lambda Extension**; EC2 (`DescribeInstances`, `StartInstances`, `StopInstances`); Resource Groups Tagging API (`tag:GetResources`); Secrets Manager. The deployed function uses **arm64**, Durable Execution IAM policies, a 2-hour Durable execution timeout (construct default), and a bundled handler that loads secrets via **aws-lambda-secret-fetcher** (^0.7) and parses env vars via **strict-env-resolver** (^0.6). Secret fetch runs only inside Lambda (requires runtime `AWS_SESSION_TOKEN` and the extension layer); the library retries transient extension errors including cold-start "not ready" responses.
 
 ## License