Reference: Cron and rate expressions for Systems Manager

When you create a State Manager association or a maintenance window in AWS Systems Manager, you specify a schedule for when the window or the association should run. You can specify a schedule as either a time-based entry, called a cron expression, or a frequency-based entry, called a rate expression.

General information about cron and rate expressions

The following information applies to cron and rate expressions for both maintenance windows and associations.

Cron and rate expressions for associations

This section includes examples of cron and rate expressions for State Manager associations. Before you create one of these expressions, be aware of the following information:

Associations support cron expressions that include a day of the week and the number sign (#) to designate the nth day of a month to run an association. Here is an example that runs a cron schedule on the third Tuesday of every month at 23:30 UTC:

cron(30 23 ? * TUE#3 *)

Here is an example that runs on the second Thursday of every month at midnight UTC:

cron(0 0 ? * THU#2 *)

Associations also support the (L) sign to indicate the last X day of the month. Here is an example that runs a cron schedule on the last Tuesday of every month at midnight UTC:

cron(0 0 ? * 3L *)

To further control when an association runs, for example if you want to run an association two days after patch Tuesday, you can specify an offset. An offset defines how many days to wait after the scheduled day to run an association. For example, if you specified a cron schedule of cron(0 0 ? * THU#2 *), you could specify the number 3 in the Schedule offset field to run the association each Sunday after the second Thursday of the month.

To use offsets, you must either choose the Apply association only at the next specified Cron interval option in the console or you must specify the use --apply-only-at-cron-interval parameter from the command line. This option tells State Manager not to run an association immediately after you create it.

The following table presents cron examples for associations.

Here are some rate examples for associations.

AWS CLI examples for associations

To create State Manager associations using the AWS CLI, you include the --schedule-expression parameter with a cron or rate expression. The following examples use the AWS CLI on a local Linux machine.

aws ssm create-association \
    --association-name "My-Cron-Association" \
    --schedule-expression "cron(0 2 ? * SUN *)" \
    --targets Key=tag:ServerRole,Values=WebServer \
    --name AWS-UpdateSSMAgent

aws ssm create-association \
    --association-name "My-Rate-Association" \
    --schedule-expression "rate(7 days)" \
    --targets Key=tag:ServerRole,Values=WebServer \
    --name AWS-UpdateSSMAgent

aws ssm create-association \
    --association-name "My-Rate-Association" \
    --schedule-expression "at(2020-07-07T15:55:00)" \
    --targets Key=tag:ServerRole,Values=WebServer \
    --name AWS-UpdateSSMAgent \
    --apply-only-at-cron-interval

Cron and rate expressions for maintenance windows

This section includes examples of cron and rate expressions for maintenance windows.

Unlike State Manager associations, maintenance windows support all cron and rate expressions. This includes support for values in the seconds field.

For example, the following 6-field cron expression runs a maintenance window at 9:30 AM every day.

cron(30 09 ? * * *)

By adding a value to the Seconds field, the following 7-field cron expression runs a maintenance window at 9:30:24 AM every day.

cron(24 30 09 ? * * *)

The following table provides additional 6-field cron examples for maintenance windows.

The following table provides rate examples for maintenance windows.

AWS CLI examples for maintenance windows

To create maintenance windows using the AWS CLI, you include the --schedule parameter with a cron or rate expression or a timestamp. The following examples use the AWS CLI on a local Linux machine.

aws ssm create-maintenance-window \
    --name "My-Cron-Maintenance-Window" \
    --allow-unassociated-targets \
    --schedule "cron(0 16 ? * TUE *)" \
    --schedule-timezone "America/Los_Angeles" \
    --start-date 2021-01-01T00:00:00-08:00 \
    --end-date 2021-06-30T00:00:00-08:00 \
    --duration 4 \
    --cutoff 1

aws ssm create-maintenance-window \
    --name "My-Rate-Maintenance-Window" \
    --allow-unassociated-targets \
    --schedule "rate(7 days)" \
    --duration 4 \
    --schedule-timezone "America/Los_Angeles" \
    --cutoff 1

aws ssm create-maintenance-window \
    --name "My-TimeStamp-Maintenance-Window" \
    --allow-unassociated-targets \
    --schedule "at(2021-07-07T13:15:30)" \
    --duration 4 \
    --schedule-timezone "America/Los_Angeles" \
    --cutoff 1