Credentials Install the Scheduler CLI Command structure Common arguments Available commands create-period create-schedule delete-period delete-schedule describe-periods describe-schedules describe-schedule-usage update-period update-schedule help

Scheduler CLI

The Instance Scheduler on AWS command line interface (CLI) allows you 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, refer to Configuration and credential file settings 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.

Note

If you specify a profile using the profile-name argument, the profile you specify must have these permissions. For more information about the profile-name argument, refer to Common Arguments.

Install the Scheduler CLI

Download and unzip the scheduler CLI package.
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.
`--profile-name <profilename>`	The name of the profile to use to run commands. If no profile name is specified, the default profile is used.
`--query`	A JMESPath expression that controls the command output. For more information on controlling output, refer to 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

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 n^th 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 n^th month.

Required: No

--monthdays

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 n^th 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

--use-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

--ssm-maintenance-window

Adds an AWS Systems Manager maintenance window as a running period to an Amazon EC2 instance schedule. To use this command, you must use the use-maintenance-window command.

Type: String

Required: No

--do-not-stop-new-instances

Do not stop an instance the first time it is tagged if it is running outside of a running period

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, or an AWS Systems Manager maintenance window as a running period to an Amazon EC2 instance schedule

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, refer to the create period command.

Important

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, refer to the create schedule command.

Important

If you do not specify an argument, that argument will be removed from the schedule.

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

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Additional resources

Solution resources