Merge pull request #1575 from buildkite/SUP-3626-configurable-scheduled-scaling

Allow scheduled scale up/down actions for MinSize

Author: petetomasik

README.md

@@ -92,6 +92,60 @@ To enable resource limits with custom values, include these parameters in your C
 - Resource limits are disabled by default
 - Values can be specified as percentages or absolute values (for memory-related parameters)
 
+## Scheduled Scaling
+
+The Elastic CI Stack supports time-based scaling to automatically adjust the minimum number of instances based on your team's working hours. This feature helps optimize costs by scaling down during off-hours while allowing users the ability to proactively scale up capacity ahead of expected increasing capacity requirements.
+
+### Configuration Parameters
+
+| Parameter                | Description                                          | Default              |
+|--------------------------|------------------------------------------------------|----------------------|
+| `EnableScheduledScaling` | Enable scheduled scaling actions                     | `false`              |
+| `ScheduleTimezone`       | Timezone for scheduled actions                       | `UTC`                |
+| `ScaleUpSchedule`        | Cron expression for scaling up                       | `0 8 * * MON-FRI`    |
+| `ScaleUpMinSize`         | MinSize when scaling up                              | `1`                  |
+| `ScaleDownSchedule`      | Cron expression for scaling down                     | `0 18 * * MON-FRI`   |
+| `ScaleDownMinSize`       | MinSize when scaling down                            | `0`                  |
+
+### Example Configuration
+
+To enable scheduled scaling that maintains a minimum of 10 ASG instances during business hours (8 AM - 6 PM, Eastern Time) and 2 ASG instances during off-hours:
+
+```json
+{
+  "Parameters": {
+    "EnableScheduledScaling": "true",
+    "ScheduleTimezone": "America/New_York",
+    "ScaleUpSchedule": "0 8 * * MON-FRI",
+    "ScaleUpMinSize": "10",
+    "ScaleDownSchedule": "0 18 * * MON-FRI",
+    "ScaleDownMinSize": "2"
+  }
+}
+```
+
+### Schedule Format
+
+Scheduled scaling uses [AWS Auto Scaling cron expressions](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-scheduled-scaling.html#scheduled-scaling-cron) with the format:
+```
+minute hour day-of-month month day-of-week
+```
+
+Common examples:
+- `0 8 * * MON-FRI` - 8:00 AM on weekdays
+- `0 18 * * MON-FRI` - 6:00 PM on weekdays
+- `0 9 * * SAT` - 9:00 AM on Saturdays
+- `30 7 * * 1-5` - 7:30 AM Monday through Friday (using numbers)
+
+### Timezone Support
+
+The `ScheduleTimezone` parameter supports [IANA timezone names](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-scheduled-scaling.html#scheduled-scaling-timezone) such as:
+- `America/New_York` (Eastern Time)
+- `America/Los_Angeles` (Pacific Time)
+- `Europe/London` (Greenwich Mean Time)
+- `Asia/Tokyo` (Japan Standard Time)
+- `UTC` (Coordinated Universal Time)
+
 ## Development
 
 To get started with customizing your own stack, or contributing fixes and features:

templates/aws-stack.yml

@@ -129,6 +129,12 @@ Metadata:
         - ScalerEventSchedulePeriod
         - ScalerMinPollInterval
         - ScalerEnableExperimentalElasticCIMode
+        - EnableScheduledScaling
+        - ScheduleTimezone
+        - ScaleUpSchedule
+        - ScaleUpMinSize
+        - ScaleDownSchedule
+        - ScaleDownMinSize
 
       - Label:
           default: Cost Allocation Configuration
@@ -230,6 +236,45 @@ Parameters:
         - "false"
     Default: "false"
 
+  EnableScheduledScaling:
+    Description: Enable scheduled scaling to automatically adjust MinSize based on time-based schedules
+    Type: String
+    AllowedValues:
+        - "true"
+        - "false"
+    Default: "false"
+
+  ScheduleTimezone:
+    Description: "Timezone for scheduled scaling actions (only used when EnableScheduledScaling is true). See AWS documentation for supported formats: https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-scheduled-scaling.html#scheduled-scaling-timezone (America/New_York, UTC, Europe/London, etc.)"
+    Type: String
+    Default: "UTC"
+
+  ScaleUpSchedule:
+    Description: "Cron expression for when to scale up (only used when EnableScheduledScaling is true). See AWS documentation for format details: https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-scheduled-scaling.html#scheduled-scaling-cron (\"0 8 * * MON-FRI\" for 8 AM weekdays)"
+    Type: String
+    Default: "0 8 * * MON-FRI"
+    AllowedPattern: '^[0-9*,-/]+ [0-9*,-/]+ [0-9*,-/]+ [0-9*,-/]+ [0-9A-Za-z*,-/]+$'
+    ConstraintDescription: "Must be a valid cron expression (5 fields: minute hour day-of-month month day-of-week)"
+
+  ScaleUpMinSize:
+    Description: MinSize to set when the ScaleUpSchedule is triggered (applied at the time specified in ScaleUpSchedule, only used when EnableScheduledScaling is true). Cannot exceed MaxSize.
+    Type: Number
+    Default: 1
+    MinValue: 0
+
+  ScaleDownSchedule:
+    Description: "Cron expression for when to scale down (only used when EnableScheduledScaling is true). See AWS documentation for format details: https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-scheduled-scaling.html#scheduled-scaling-cron (\"0 18 * * MON-FRI\" for 6 PM weekdays)"
+    Type: String
+    Default: "0 18 * * MON-FRI"
+    AllowedPattern: '^[0-9*,-/]+ [0-9*,-/]+ [0-9*,-/]+ [0-9*,-/]+ [0-9A-Za-z*,-/]+$'
+    ConstraintDescription: "Must be a valid cron expression (5 fields: minute hour day-of-month month day-of-week)"
+
+  ScaleDownMinSize:
+    Description: MinSize to set when the ScaleDownSchedule is triggered (applied at the time specified in ScaleDownSchedule, only used when EnableScheduledScaling is true)
+    Type: Number
+    Default: 0
+    MinValue: 0
+
   ScaleOutCooldownPeriod:
     Description: Cooldown period in seconds before allowing another scale-out event
     Type: Number
@@ -1130,6 +1175,9 @@ Conditions:
         - !Equals [ !Ref RootVolumeType, "io2" ]
         - !Equals [ !Ref RootVolumeType, "gp3" ]
 
+    EnableScheduledScaling:
+      !Equals [ !Ref EnableScheduledScaling, "true" ]
+
 Mappings:
   ECRManagedPolicy:
     none                  : { Policy: '' }
@@ -1992,6 +2040,26 @@ Resources:
       AutoScalingReplacingUpdate:
         WillReplace: true
 
+  ScheduledScaleUpAction:
+    Condition: EnableScheduledScaling
+    Type: AWS::AutoScaling::ScheduledAction
+    Properties:
+      AutoScalingGroupName: !Ref AgentAutoScaleGroup
+      ScheduledActionName: !Sub "${AWS::StackName}-ScaleUp"
+      Recurrence: !Ref ScaleUpSchedule
+      MinSize: !Ref ScaleUpMinSize
+      TimeZone: !Ref ScheduleTimezone
+
+  ScheduledScaleDownAction:
+    Condition: EnableScheduledScaling
+    Type: AWS::AutoScaling::ScheduledAction
+    Properties:
+      AutoScalingGroupName: !Ref AgentAutoScaleGroup
+      ScheduledActionName: !Sub "${AWS::StackName}-ScaleDown"
+      Recurrence: !Ref ScaleDownSchedule
+      MinSize: !Ref ScaleDownMinSize
+      TimeZone: !Ref ScheduleTimezone
+
   AsgProcessSuspenderRole:
     Type: AWS::IAM::Role
     Properties: