Solution components
Scheduler configuration table
When deployed, the Instance Scheduler on AWS creates an Amazon DynamoDB table that contains global configuration settings. To modify these global configuration settings after the solution is deployed, update the AWS CloudFormation stack. Do not modify these values in the DynamoDB table. If you modify the values in the DynamoDB table, you will create a conflict between the stored parameters in the stack and the values in the table.
Global configuration items contain a type attribute with a value of config in the configuration table. Schedules and periods contain
type attributes with values of schedule and
period, respectively. You can add, update, or remove
schedules and periods from the configuration table using the DynamoDB console or the solution’s
command line interface.
Schedules
Schedules specify when Amazon Elastic Compute Cloud (Amazon EC2) and Amazon Relational Database Service (Amazon RDS) instances should run. Each schedule must have a unique name, which is used as the tag value that identifies the schedule you want to apply to the tagged resource.
Periods
Each schedule must contain at least one period that defines the time(s) the instance should run. A schedule can contain more than one period. When more than one period is used in a schedule, the Instance Scheduler will apply the appropriate start action when at least one of the period rules is true. For more information, refer to Period Rules.
Time zone
You can also specify a time zone for the schedule. If you do not specify a time zone,
the schedule will use the default time zone you specify when you launch the solution. For a
list of acceptable time zone values, refer to the TZ column of the
List of TZ
Database Time Zones
Hibernate field
The hibernate field allows you to use hibernation for stopped Amazon EC2
instances. Your EC2 instances will have an Amazon Machine Image (AMI) when the hibernate
field is set to true. For more information, refer to Hibernate your On-Demand
or Reserved Linux instance in the Amazon Elastic Compute Cloud
User
Guide for Linux
Instances. Hibernation saves the contents from the instance memory
(RAM) to your Amazon Elastic Block Store (Amazon EBS) root volume. If this field is set to true,
instances are hibernated when the solution stops them.
If you set the solution to use hibernation, but your instances are not enabled for hibernation or they do not meet the hibernation prerequisites, the solution logs a warning and the instances are stopped without hibernation. For more information, refer to Hibernate your On-Demand or Reserved Linux instance in the Amazon Elastic Compute Cloud User Guide for Linux instances.
Enforced field
Schedules contain an enforced field that allows you to prevent an instance from being manually started outside of a running period, or manually stopped during a running period. If this field is set to true and a user manually starts an instance outside of a running period, the solution will stop the instance. If this field is set to true, it also restarts an instance if it was manually stopped during a running period.
Retain running field
The retain_running field prevents the solution from stopping an instance at the end of a running period if the instance was manually started before the beginning of the period. For example, if an instance with a period that runs from 9 am to 5 pm is manually started before 9 am, the solution will not stop the instance at 5 pm.
SSM maintenance window field
The ssm-maintenance-window field allows you to automatically add an
AWS Systems Manager maintenance window as a running period to a schedule. When you specify the name of
a maintenance window that exists in the same account and AWS Region as your deployed stack
to schedule your Amazon EC2 instances, the solution will start the instance before the start of
the maintenance window and stop the instance at the end of the maintenance window if no
other running period specifies that the instance should run, and if the maintenance event is
completed.
The solution uses the AWS Lambda frequency you specified during initial configuration to determine how long before the maintenance window to start your instance. If you set the Frequency AWS CloudFormation parameter to 10 minutes or less, the solution will start the instance 10 minutes before the maintenance window. If you set the frequency to greater than 10 minutes, the scheduler will start the instance the same number of minutes as the frequency you specified. For example, if you set the frequency to 30 minutes, the scheduler will start the instance 30 minutes before the maintenance window.
The CloudFormation parameter Enable
SSM Maintenance windows in the solution stack should be set
to Yes and the stack should be updated, so that the solution will start loading
the SSM maintenance window into the DynamoDB table, which will be used when the AWS Lambda
function runs.
For more information, refer to AWS Systems Manager Maintenance Windows in the AWS Systems Manager user guide.
Override status field
Schedules also contain an override_status field that allows you to temporarily override the solution’s start and stop actions. If you set the field to running, the solution will start but not stop the applicable instance. The instance will run until you stop it manually. If you set the field to stopped, the solution will stop but not start the applicable instance. The instance will not run until you manually start it.
Note that if you set the override_status field to running but use the enforced field to prevent an instance from being manually started outside of a running period, the solution will stop the instance. If you set the override_status field to stopped but use the enforced field to prevent an instance from being manually stopped during a running period, the solution will restart the instance.
Instance type
For Amazon EC2 instances only, a schedule allows you to specify an optional instance type for each period in a schedule. When you specify an instance type in the period, the solution will start the Amazon EC2 instance with the applicable instance type.
To specify an instance type, use the syntax <period-name>@<instance-type>. For example, weekends@t2.nano. Note that if you specify an instance type for a period that schedules Amazon EC2 instances and Amazon RDS instances, the instance type will be ignored for Amazon RDS instances.
If the instance type of a running instance is different than the instance type specified for the period, the solution will stop the running instance and restart the instance with the specified instance type, if the specified instance type is compatible with the instance configuration of the running instance. For more information, refer to Compatibility for Resizing Instances in the Amazon EC2 User Guide for Linux Instances.
Schedule definitions
The Instance Scheduler configuration table in Amazon DynamoDB contains schedule definitions. A schedule definition can contain the following fields:
| Field | Description | |
|---|---|---|
description |
An optional description of the schedule. | |
hibernate |
Choose whether to hibernate Amazon EC2 instances running Amazon Linux. When this field is set to true, the scheduler will hibernate instances when it stops them. Note that your instances must turn on hibernation and must meet the hibernation prerequisites. |
|
enforced |
Choose whether to enforce the schedule. When this field is set to true, the scheduler will stop a running instance if it is manually started outside of the running period or it will start an instance if it is stopped manually during the running period. |
|
name |
The name used to identify the schedule. This name must be unique. | |
override_status |
When this field is set to running, the instance will be started but not stopped until you stop it manually. When this field is set to stopped, the instance will be stopped but not started until you start it manually. |
|
periods |
The name of the periods that are used in this schedule. Enter the name(s) exactly as it appears in the period You can also specify an instance type for the period using the syntax <period-name>@<instance-type>. For example, |
|
retain_running |
Choose whether to prevent the solution from stopping an instance at the end of a running period if the instance was manually started before the beginning of the period. | |
ssm_maintenance_window |
Choose whether to add an AWS Systems Manager maintenance window as a running period. Enter the name of a maintenance window. To use this field, you must also set the |
|
stop_new_instances |
Choose whether to stop an instance the first time it is tagged if it is running outside of the running period. By default, this field is set to true. |
|
timezone |
The time zone the schedule will use. If no time zone
is specified, the default time zone (UTC) is used. For a list of acceptable time
zone values, refer to the TZ column of the List of TZ
Database Time Zones |
|
use_maintenance_window |
Choose whether to add an Amazon RDS maintenance window as a running period to an Amazon RDS instance schedule, or to add an AWS Systems Manager maintenance window as a running period to an Amazon EC2 instance schedule. For more information, refer to Amazon RDS Maintenance Window and SSM Maintenance Window Field. | |
use_metrics |
Choose whether to turn on CloudWatch metrics at the schedule level. This field overwrites the CloudWatch metrics setting you specified at deployment. Enabling this feature will incur charges of $0.90/month per schedule or scheduled service. |
|
Period rules
Period rules contain conditions that allow you to set the specific hours, days, and months an instance will run. A period rule can contain multiple conditions, but all conditions must be true for the Instance Scheduler on AWS to apply the appropriate start or stop action.
Start and stop times
The begintime and endtime fields define when the Instance
Scheduler will start and stop instances. If you specify a start time only, the instance must
be stopped manually. Note that if you specify a value in the weekdays field, the solution uses that value to determine when to
stop the instance. For example, if you specify a begintime of 9 am with no
endtime and a weekdays value of Monday through Friday, the
instance will be stopped at 11:59 pm at the end of each day unless you have scheduled an
adjacent period.
Similarly, if you specify a stop time only, the instance must be started manually. If you don’t specify either time, the solution uses the days of the week, days of the month, or months rules to start and stop instances.
The begintime and endtime values for your period must be in
the time zone specified in the schedule. If you do not specify a time zone in the schedule,
the solution will use the time zone specified when you launch the solution.
If your schedule contains multiple periods, we recommend that you specify both a
begintime and endtime in your period. If no time is specified,
this solution will use the time specified in the other periods to determine when to start
and stop your instances. For example, if in one period you specify a begintime
of 9 am with no endtime because you want the instance to run until you manually
stop it, Instance Scheduler on AWS will stop the instance at 00:00 am the following day. The
solution will evaluate whether to keep the instance started or stopped until it finds
another period for that specific day.
If you start an instance before the specified start time, the instance will run until the end of the running period. For example, a user might define a period that starts an instance daily at 9 am and stops that instance at 5 pm.
Figure 2: 9-5 scheduled start and stop
If the user manually starts that instance at 5 am, the solution will stop the instance at 5 pm. Note that if you use the retain running field, the solution will not stop the instance at 5 pm.
Figure 3: 5AM manual start
If you stop an instance before the specified stop time, the instance will not run until the beginning of the next running period. Continuing from the previous example, if the user stops the instance at 1 pm on Wednesday, the solution will not start the instance until 9 am on Thursday.
Figure 4: 5PM scheduled stop
Adjacent periods
The solution will not stop running instances if the schedule contains two adjacent
running periods. For example, if you have a schedule with one period with an
endtime of 11:59 pm and another period with a begintime of
midnight the following day, the solution will not stop running instances, if there are no
weekdays, monthdays, or months rules that stop the
instances.
To implement a schedule that runs instances from 9 am Monday to 5 pm Friday, the solution requires three periods. The first period runs applicable instances from 9 am to 11:59 pm Monday. The second period runs the instances from midnight Tuesday to 11:59 pm Thursday. The third period runs the instances from midnight Friday to 5 pm Friday. For more information, refer to Sample schedule.
Days of the week
The weekdays field defines which days during the week an instance will run.
You can specify a list of days, a range of days, the nth
occurrence of that day in a month, or the last occurrence of that day in a month. The
solution supports abbreviated day names (Mon) and numbers (0). For more information, refer
to Step 2.
Days of the month
The monthdays field defines which days during the month an instance will
run. You can specify a list of days, a range of days, every nth
day of the month, the last day of the month, or the nearest weekday to a specific date. For
more information, refer to Step 2.
Months
The months field defines which months an instance will run. You can specify
a list of months, a range of months, or every nth month. The
solution supports abbreviated month names (Jan) and numbers (1). For more information, refer
to Step 2.
Period definitions
The Instance Scheduler configuration table in Amazon DynamoDB contains period definitions. A period definition can contain the following fields. Note that some fields support Cron non-standard characters
| Field | Description | |
|---|---|---|
You must specify at least one of the following items: |
||
begintime |
The time, in HH:MM format, that the instance will start. | |
description |
An optional description of the period rule | |
endtime |
The time, in HH:MM format, that the instance will stop. | |
months |
Enter a comma-delimited list of months, or a hyphenated range of months, during which the instance will run. For example, enter Jan/3 or 1/3 to run an instance every third month starting in January. Enter Jan-Jul/2 to run every other month from January to July.
|
|
monthdays |
Enter a comma-delimited list of days of the month, or a hyphenated range of days, during which the instance will run. For example, enter You can also schedule an instance to run every nth day of the month or every nth day of the month in a range. For example, enter Enter |
|
name |
The name used to identify the period rule. This name must be unique. | |
weekdays |
Enter a comma-delimited list of days of the week, or a range of days of the week, during which the instance will run. For example, enter You can also schedule an instance to run every nth occurrence of a weekday in the month. For example, enter Enter a day and |
|
When a period rule contains multiple conditions, note that all conditions must be true
for the Instance Scheduler on AWS to apply the appropriate action. For example, a period
rule that contains a weekdays field with a value of Mon#1 and a
months field with a value of Jan/3 will apply the action on the
first Monday of the quarter.
Cross-account instance scheduling
This solution includes a template (instance-scheduler-remote) that creates the AWS Identity and Access Management (IAM) roles necessary to start and stop instances in secondary accounts. You can review and modify permissions in the remote template before you launch the stack.
To apply automated start-stop schedules to resources in secondary accounts, launch the
main solution template (instance-scheduler) in the primary account. Then, launch
the remote template (instance-scheduler-remote) in each applicable secondary
account. When each remote stack is launched, it creates a cross-account role Amazon Resource
Name (ARN). Update the main solution stack with each cross-account role ARN by entering the
appropriate ARN(s) in the Cross-account roles parameter to
allow the solution to perform start and stop actions on instances in the secondary
accounts.
AWS Systems Manager Parameter Store
You can use AWS Systems Manager Parameter Store to store cross-account role ARNs. You can store
cross-account ARNs as a list parameter where every item is an ARN, or as a string parameter
that contains a comma-delimited list of ARNs. The parameter has the format
{param: where the name is the name of the
parameter in the parameter store. name}
To leverage this feature, you must launch the Instance Scheduler stack in the same account as your parameter store.
Automated tagging
The Instance Scheduler can automatically add tags to all instances it starts or stops. You can specify a list of tag names or tagname=tagvalue pairs in the Started tags and Stopped tags parameters. The solution also includes macros that allow you to add variable information to the tags:
{scheduler}: The name of the scheduler stack{year}: The year (four digits){month}: The month (two digits){day}: The day (two digits){hour}: The hour (two digits, 24-hour format){minute}: The minute (two digits){timezone}: The time zone
The following table gives examples of different inputs and the resulting tags.
| Example Parameter Input | Instance Scheduler Tag |
|---|---|
ScheduleMessage=Started by scheduler {scheduler} |
ScheduleMessage=Started by scheduler MyScheduler |
ScheduleMessage=Started on {year}/{month}/{day} |
ScheduleMessage=Started on 2017/07/06 |
ScheduleMessage=Started on {year}/{month}/{day} at {hour}:{minute} |
ScheduleMessage=Started on 2017/07/06 at 09:00 |
ScheduleMessage=Started on {year}/{month}/{day} at {hour}:{minute} {timezone} |
ScheduleMessage=Started on 2017/07/06 at 09:00 UTC |
When you use the Started tags parameter, the tags are automatically deleted when the scheduler stops the instance. When you use the Stopped tags parameter, the tags are automatically deleted when the instance is started.
Scheduler command line interface
The solution includes a command line interface (CLI) that provides commands for configuring schedules and periods. The CLI allows customers to estimate cost savings for a given schedule. The cost estimates provided by the schedule CLI are for approximation purposes only. For more information about configuring and using the scheduler CLI, refer to Scheduler CLI.
