AWS Instance Scheduler
AWS Instance Scheduler

Appendix A: Scheduler CLI

The Instance Scheduler command line interface (CLI) allows customers to configure schedules and periods, and estimate cost savings for a given schedule.

Credentials

To use the scheduler CLI, you must have credentials for the AWS CLI. For more information, see Configuration and Credential Files in the AWS CLI User Guide.

Your credentials must have the following permissions:

  • lambda:InvokeFunction – To invoke the InstanceSchedulerMain function in the scheduler stack, and to update the schedule and period information in the scheduler configuration database from the command line

  • cloudformation:DescribeStackResource – To retrieve the physical resource ID of the AWS Lambda function from the stack to handle the CLI request

Requests made by the scheduler CLI and responses are logged in the AdminCliRequestHandler-yyyymmdd log stream.

Install the Scheduler CLI

  1. Download and unzip the scheduler CLI package.

  2. In the scheduler-cli directory, run the setup Python script:

    python setup.py install

Command Structure

The scheduler CLI uses a multipart structure on the command line. The next part specifies the scheduler CLI python script. The scheduler CLI has commands that specify the operations to perform on periods and schedules. The specific arguments for an operation can be specified on the command line in any order.

scheduler-cli <command> <arguments>

Common Arguments

The scheduler CLI supports the following arguments that all commands can use:

Argument Description
--stack <stackname>

The name of the scheduler stack

Important

This argument is required for all commands.

--region <regionname>

The region where the scheduler stack is deployed

Note

You must use this argument when the default configuration and credential files are not installed in the same region as the solution stack.

--query A JMESPath expression that controls the command output. For more information on controlling output, see Controlling Command Output from the AWS Command Line Interface in the AWS CLI User Guide.
--help Shows valid commands and arguments for the scheduler CLI. When used with a specific command, it shows valid subcommands and arguments for that command.
--version Shows the version number of the scheduler CLI

Available Commands

create-period

Description

Creates a period. A period must contain at least one of the following items: begintime, endtime, weekdays, months, or monthdays.

Arguments

--name

The name of the period

Type: String

Required: Yes

--description

A description of the period

Type: String

Required: No

--begintime

The time when the running period starts. If begintime and endtime are not specified, the running period is 00:00 – 23:59.

Type: String

Constraints: H:MM or HH:MM format

Required: No

--endtime

The time when the running period stop. If begintime and endtime are not specified, the running period is 00:00 – 23:59.

Type: String

Constraints: H:MM or HH:MM format

Required: No

--weekdays

The days of the week for the period

Type: String

Constraints: Comma-delimited list of abbreviated day names (mon) or numbers (0). Use – to specify a range. Use / to specify every nth day of the week.

Required: No

--months

The months of the period

Type: String

Constraints: Comma-delimited list of abbreviated months names (jan) or numbers (1). Use – to specify a range. Use / to specify every nth month.

Required: No

--monthsdays

The days of the month for the period

Type: String

Constraints: Comma-delimited list of abbreviated months names (jan) or numbers (1). Use – to specify a range. Use / to specify every nth day of the month.

Required: No

Example

$ scheduler-cli create-period --name "weekdays" --begintime 09:00 --endtime 18:00 --weekdays mon-fri --stack Scheduler { "Period": { "Name": "weekdays", "Endtime": "18:00", "Type": "period", "Begintime": "09:00", "Weekdays": [ "mon-fri" ] } }

create-schedule

Description

Creates a schedule

Arguments

--name

The name of the schedule

Type: String

Required: Yes

--description

A description of the schedule

Type: String

Required: No

--enforced

Enforces the scheduled state for the instance

Type: Boolean

Constraints: Value must be true or false. By default, this parameter is set to false.

Required: No

--metrics

Collect Amazon CloudWatch metrics

Type: Boolean

Constraints: Value must be true or false. By default, this parameter is set to false.

Required: No

--override-status

Overrides the status of an instance to keep the instance in the specified state

Type: String

Constraints: Acceptable values are running or stopped

Required: No

--periods

A list of running periods for the schedule. If multiple periods are specified, the solution will start an instance if one of the period rules is true.

Type: String

Constraints: Comma-delimited list of periods. Use <period-name>@<instance type> to specify an instance type for a period. For example, weekdays@t2.large.

Required: Yes (if override-status is not used)

--retain-running

Prevents an instance from being stopped by the solution at the end of a running period, if the instance was manually started before the beginning of the period

Type: Boolean

Required: No

--stop-new-instances

Stops an instance the first time it is tagged if it is running outside of a running period

Type: Boolean

Constraints: Values must be true or false. By default, this parameter is set to false.

Required: No

--timezone

The time zone the schedule will use

Type: Array of strings

Required: No (If this argument is not used, the default time zone from main solution stack is used.)

--use-maintenance-window

Add an Amazon RDS maintenance window as a running period to an Amazon RDS instance schedule

Type: Strings

Required: No

Example

$ scheduler-cli create-schedule --name LondonOfficeHours --periods weekdays,weekends --timezone Europe/London --stack Scheduler { "Schedule": { "Enforced": false, "Name": "LondonOfficeHours", "StopNewInstances": true, "Periods": [ "weekends", "weekdays" ], "Timezone": "Europe/London", "Type": "schedule" } }

delete-period

Description

Deletes an existing period

Arguments

--name

The name of the applicable period

Type: String

Required: Yes

Important

If the period is used in existing schedules, you must remove it from those schedules before you delete it.

Example

$ scheduler-cli delete-period --name weekdays --stack Scheduler { "Period": "weekdays" }

delete-schedule

Description

Deletes an existing schedule

Arguments

--name

The name of the applicable schedule

Type: String

Required: Yes

Example

$ scheduler-cli delete-schedule --name LondonOfficeHours --stack Scheduler { "Schedule": "LondonOfficeHours" }

describe-periods

Description

Lists the configured periods for the Instance Scheduler stack

Arguments

--name

The name of of a specific period you want described

Type: String

Required: No

Example

$ scheduler-cli describe-periods --stack Scheduler { "Periods": [ { "Name": "first-monday-in-quarter", "Months": [ "jan/3" ], "Type": "period", "Weekdays": [ "mon#1" ], "Description": "Every first Monday of each quarter" }, { "Description": "Office hours", "Weekdays": [ "mon-fri" ], "Begintime": "09:00", "Endtime": "17:00", "Type": "period", "Name": "office-hours" }, { "Name": "weekdays", "Endtime": "18:00", "Type": "period", "Weekdays": [ "mon-fri" ], "Begintime": "09:00" }, { "Name": "weekends", "Type": "period", "Weekdays": [ "sat-sun" ], "Description": "Days in weekend" } ] }

describe-schedules

Description

Lists the configured schedules for the Instance Scheduler stack

Arguments

--name

The name of of a specific schedule you want described

Type: String

Required: No

Example

$ scheduler-cli describe-schedules --stack Scheduler { "Schedules": [ { "OverrideStatus": "running", "Type": "schedule", "Name": "Running", "UseMetrics": false }, { "Timezone": "UTC", "Type": "schedule", "Periods": [ "working-days@t2.micro", "weekends@t2.nano" ], "Name": "scale-up-down" }, { "Timezone": "US/Pacific", "Type": "schedule", "Periods": [ "office-hours" ], "Name": "seattle-office-hours" }, { "OverrideStatus": "stopped", "Type": "schedule", "Name": "stopped", "UseMetrics": true } ] }

describe-schedule-usage

Description

Lists all the periods running within a schedule and calculates the billing hours for instances. Use this command to simulate a schedule to calculate potential savings, and running periods after creating or updating a schedule.

Arguments

--name

The name of the applicable schedule

Type: String

Required: Yes

--startdate

The start date of the period used for calculation. The default date is the current date.

Type: String

Required: No

--enddate

The end date of the period used for calculation. The default date is the current date.

Type: String

Required: No

Example

$ scheduler-cli describe-schedule-usage --stack InstanceScheduler --name seattle-office-hours { "Usage": { "2017-12-04": { "BillingHours": 8, "RunningPeriods": { "Office-hours": { "Begin": "12/04/17 09:00:00", "End": "12/04/17 17:00:00", "BillingHours": 8, "BillingSeconds": 28800 } }, "BillingSeconds": 28800 } }, "Schedule": "seattle-office-hours"

update-period

Description

Updates an existing period

Arguments

The update-period command supports the same arguments as the create-period command. For more information on the arguments, see the create period command.

Note that if you do not specify an argument, that argument will be removed from the period.

update-schedule

Description

Updates an existing schedule

Arguments

The update-schedule command supports the same arguments as the create-schedule command. For more information on the arguments, see the create schedule command.

Note that if you do not specify an argument, that argument will be removed from the period.

help

Description

Displays a list of valid commands and arguments for the scheduler CLI

Example

$ scheduler-cli --help usage: scheduler-cli [-h] [--version] {create-period,create-schedule,delete-period,delete-schedule,describe-periods,describe-schedule-usage,describe-schedules,update-period,update-schedule} ... optional arguments: -h, --help show this help message and exit --version show program's version number and exit subcommands: Valid subcommands {create-period,create-schedule,delete-period,delete-schedule,describe-periods,describe-schedule-usage,describe-schedules,update-period,update-schedule} Commands help create-period Creates a period create-schedule Creates a schedule delete-period Deletes a period delete-schedule Deletes a schedule describe-periods Describes configured periods describe-schedule-usage Calculates periods and billing hours in which instances are running describe-schedules Described configured schedules update-period Updates a period update-schedule Updates a schedule

When used with a specific command, the --help argument shows valid subcommands and arguments for that command.

Specific Command Example

$ scheduler-cli describe-schedules --help usage: scheduler-cli describe-schedules [-h] [--name NAME] [--query QUERY] [--region REGION] --stack STACK optional arguments: -h, --help show this help message and exit --name NAME Name of the schedule --query QUERY JMESPath query to transform or filter the result --region REGION Region in which the Instance Scheduler stack is deployed --stack STACK, -s STACK Name of the Instance Scheduler stack