How do I use Instance Scheduler with CloudFormation to schedule EC2 instances?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

To automate the deployment of the AWS Instance Scheduler, use CloudFormation templates.

Note: If you use the Instance Scheduler for Amazon EC2 instances with an encrypted Amazon Elastic Block Store (Amazon EBS), then your instances won't start. You must add the key policy to the AWS Key Management Service (AWS KMS) key to allow the key user role to use this key.

Install the Instance Scheduler

Install the Instance Scheduler. Then, to verify that the installation is successful, run the following command:

$ scheduler-cli --version

Create a CloudFormation stack with the Instance Scheduler template

To deploy an AWS Lambda function, Amazon DynamoDB table, Amazon EventBridge rule, and Amazon CloudWatch custom metrics, complete the following steps:

1. Open the AWS Management Console.
2. Open the CloudFormation console with the Instance Scheduler template. By default, the template launches in the US East (N. Virginia) Region. Or, go to the Step 1. Launch the instance scheduler hub stack page, and then choose Launch Solution.
   In the navigation bar, select the AWS Region where you want to launch your stack with the template, and then choose Next.
   For Stack name, name your stack.
   For Instance Scheduler TagName, you can keep the default value as Schedule, or customize it.
   For Frequency, choose a frequency in minutes to run your scheduler. For example, you can choose 5 minutes.
   Note: The frequency is the number of minutes that pass before EventBridge initiates the Lambda function again for the Instance Scheduler. If you have a large number of instances, then use the highest frequency possible to avoid throttling. If the frequency isn't often enough for your needs, then you can adjust the Frequency property later.
   For Enable CloudWatch Metrics, choose Yes.
   For Enable CloudWatch Logs, choose Yes.
   (Optional) For Started tags, enter state=started.
   (Optional) For Stopped tags, enter state=stopped.
   For cross-account scheduling, provide the Cross-account roles parameter. Enter the Amazon Resource Names (ARNs) for every role from the secondary accounts, separated by commas. If you aren't using cross-account scheduling, then keep the parameter empty.
3. Choose Next.
4. On the Options page, choose Next.
5. Review your settings, and then choose I acknowledge that AWS CloudFormation might create IAM resources.
6. Choose Create.

Create the periods

To create periods, you can use the Instance Scheduler CLI, DynamoDB console, or custom resources. For more information on time periods, see Start and stop times.

Use the Instance Scheduler CLI

Connect to the Instance Scheduler CLI, and then run the following create-period AWS CLI commands:

$ scheduler-cli create-period --stack your_stack_name --region aa-example-1 --name mon-fri-9-5 --begintime 9:00 --endtime 16:59 --weekdays mon-fri    
$ scheduler-cli create-period --stack your_stack_name --region aa-example-1 --name sat-9-12 --begintime 9:00 --endtime 11:59 --weekdays sat

Note: Replace your_stack_name with the stack name that you chose in step 2 and aa-example-1 with your Region.

Use the DynamoDB console

To create periods, complete the following steps:

1. Open the DynamoDB console.
2. Choose Tables, and then select the configuration table.
   Note: The Instance Scheduler template automatically creates both a state and configuration DynamoDB table. The state table stores the state of instances that the template stops and starts. The configuration table allows you to specify the periods and schedules for your requirements.
3. Choose Explore Table Items.
4. Choose Create Item.
5. Choose the JSON view, and then use the following JSON template:

   {    "type": {  
       "S": "period"  
     },  
     "name": {  
       "S": "mon-fri-9-5"  
     },  
     "begintime": {  
       "S": "9:00"  
     },  
     "endtime": {  
       "S": "16:59"  
     },  
     "weekdays": {  
       "SS": [  
         "mon-fri"  
       ]  
     }  
   }

   Note: The preceding JSON template creates the first period. Use a similar JSON template for the second period. Replace mon-fri-9-5 with your period name, 9:00 with your start time, and 16:59 with your end time.

Create a schedule

To create a schedule, you can use the Instance Scheduler CLI, DynamoDB console, or custom resources.

Use the Instance Scheduler CLI

To create a schedule, run the following create-schedule CLI command:

$ scheduler-cli create-schedule --stack your_stack_name --name m-f9-5-sat9-12 --region aa-example-1 --periods mon-fri-9-5,sat-9-12 --timezone UTC

Note: Replace your_stack_name with your stack name, aa-example-1 with your Region, and mon-fri-9-5,sat-9-12 with your schedule.

Use the DynamoDB console

To create a schedule, complete the following steps:

1. Open the DynamoDB console.
2. Choose Tables, and then select the configuration table.
3. Choose Explore Table Items.
4. Choose Create Item.
5. Choose the JSON view, and then use the following JSON template:

   {    "type": {  
       "S": "schedule"  
     },  
     "name": {  
       "S": "m-f9-5-sat9-12"  
     },  
     "timezone": {  
       "S": "UTC"  
     },  
     "periods": {  
       "SS": [  
         "mon-fri-9-5"  
       ]  
     }  
   }

Tag the instance and test the schedule

Tag instances

When you use a CloudFormation stack with the Instance Scheduler, you must define the Instance Scheduler TagName parameter. The default value for this parameter is Schedule.

The Instance Scheduler monitors tags on instances. If the instance tag key matches the defined scheduler tag, then the Instance Scheduler applies the schedule that's set for the instance tag value. For example, a tag's key is set to Schedule, and the value is set to m-f9-5-sat9-12. In this example, the instances start at 9 AM and stop at 5 PM on Monday through Friday. The instances also start at 9 AM and stop at 12 PM on Saturday.

Note: Tag keys and values are case sensitive. If you manually start instances outside the running period, then the Instance Scheduler doesn't stop running the instances. The Instance Scheduler also doesn't start an instance if you manually stop the instance during the running period, unless you enforce the schedule. For more information, see Schedule definitions.

Use predefined schedules

In addition to custom schedules, you can also use any of the predefined schedules from the configuration table. The following steps test the predefined schedule named running:

1. Open the Amazon EC2 console.
2. Choose the stopped instances that you want to tag.
3. Choose the Tags view, and then choose Manage Tags.
4. Choose Add Tag.
5. For Key, enter Schedule.
6. For Value, enter running.
7. Choose Save.
8. Refresh the Amazon EC2 console, and then wait for the Lambda function to initiate.
   Note: If the Lambda function initiates and runs without errors, then the Instance State displays as running. This depends on the schedule that you're testing. In the CloudWatch console, you can check CloudWatch metrics for Lambda invocations and errors.
9. Open the DynamoDB console.
10. Choose Tables, and then select the state table.
11. Choose the Explore Table Items, and then confirm that the tagged instance started.
    Important: You can be charged additional costs based on the frequency and duration of the Lambda function that you use. You can also be charged additional costs for the DynamoDB tables or EventBridge rules that you create.

Cross-account schedules

To use the Instance Scheduler to schedule instances in secondary accounts, deploy the aws-instance-scheduler-remote CloudFormation template. This template creates the role that allows the Instance Scheduler from the primary account to manage instances in the secondary account.

Note: You must provide the role's ARN as a parameter for the Instance Scheduler stack in the primary account. Make sure to create or update your Instance Scheduler stack with the correct parameter.

To launch the remote stack in secondary accounts, complete the following steps:

1. Open the AWS Management Console of the secondary account and launch the aws-instance-scheduler-remote CloudFormation template. You can also download the template for future use.

   Note: By default, the template launches in the US East (N. Virginia) Region.

2. In the navigation bar, select the Region where you want to launch your stack with the template, and then choose Next.

3. On the Select Template page, verify that you selected the correct template, and then choose Next.

4. On the Specify Details page, assign a name to your remote stack.

5. Under Parameters, review and modify the Primary account parameter. Enter the account number of the primary account.

6. Choose Next.

7. On the Options page, choose Next.

8. Review your settings, and then choose I acknowledge that AWS CloudFormation might create IAM resources.

9. Choose Create.

10. Choose the stack Outputs tab, and then copy the CrossAccountRole value.

11. From the primary account, select your CloudFormation stack, and then choose Update.

12. On the Update stack page, choose Use current template.

13. In the Cross-account roles parameter, paste the CrossAccountRole value.

14. Choose Next, and then choose I acknowledge that AWS CloudFormation might create IAM resources.

15. Choose Update Stack.