Example offhours policy¶
Resource Scheduling Offhours¶
Custodian provides for time based filters, that allow for taking periodic action on a resource, with resource schedule customization based on tag values. A common use is offhours scheduling for asgs and instances.
Flexible offhours scheduling with opt-in, opt-out selection, and timezone support.
Resume during offhours support.
Can be combined with other filters to get a particular set ( resources with tag, vpc, etc).
Can be combined with arbitrary actions
Can omit a set of dates such as public holidays.
We provide an onhour and offhour time filter, each should be used in a different policy, they support the same configuration options:
weekends: default true, whether to leave resources off for the weekend
weekends-only: default false, whether to turn the resource off only on the weekend
default_tz: which timezone to utilize when evaluating time (REQUIRED)
fallback-schedule: If a resource doesn’t support tagging or doesn’t provide a tag you can supply a default schedule that will be used. When the tag is provided this will be ignored. See ScheduleParser Time Specifications.
tag: which resource tag name to use for per-resource configuration (schedule and timezone overrides and opt-in/opt-out); default is
opt-out: Determines the behavior for resources which do not have a tag matching the one specified for tag. Values can be either
false(the default) where the policy operates on an opt-in basis and resources must have the tag in order to be acted on by the policy, or
truewhere the policy operates on an opt-out basis, and resources without the tag are acted on by the policy.
onhour: the default time to start/run resources, specified as 0-23
offhour: the default time to stop/suspend resources, specified as 0-23
skip-days: a list of dates to skip. Dates must use format YYYY-MM-DD
skip-days-from: a list of dates to skip stored at a url. expr, format, and url must be passed as parameters. Same syntax as
value_from. Can not specify both skip-days-from and skip-days.
This example policy overrides most of the defaults for an offhour policy:
policies: - name: offhours-stop resource: ec2 filters: - type: offhour weekends: false default_tz: pt tag: downtime opt-out: true onhour: 8 offhour: 20
Tag Based Configuration¶
Resources can use a special tag to override the default configuration on a
per-resource basis. Note that the name of the tag is configurable via the
tag option in the policy; the examples below use the default tag name,
The value of the tag must be one of the following:
(empty) or on - An empty tag value or a value of “on” implies night and weekend offhours using the default time zone configured in the policy (tz=est if unspecified) and the default onhour and offhour values configured in the policy.
off - If offhours is configured to run in opt-out mode, this tag can be specified to disable offhours on a given instance. If offhours is configured to run in opt-in mode, this tag will have no effect (the resource will still be opted out).
a semicolon-separated string composed of one or more of the following components, which override the defaults specified in the policy:
tz=<timezone>to evaluate with a resource-specific timezone, where
<timezone>is either one of the supported timezone aliases defined in
pt) or the name of a geographic timezone identifier in [IANA’s tzinfo database](https://www.iana.org/time-zones), such as
Americas/Los_Angeles. (Note all timezone aliases are referenced to a locality to ensure taking into account local daylight savings time, if applicable.)
on=(time spec)matching time specifications supported by
c7n.filters.offhours.ScheduleParseras described in the next section.
ScheduleParser Time Specifications¶
Each time specification follows the format
(days,hours). Multiple time
specifications can be combined in square-bracketed lists, i.e.
# up mon-fri from 7am-7pm; eastern time off=(M-F,19);on=(M-F,7) # up mon-fri from 6am-9pm; up sun from 10am-6pm; pacific time off=[(M-F,21),(U,18)];on=[(M-F,6),(U,10)];tz=pt
M, T, W, H, F, S, U
0, 1, 2, …, 22, 23
Days can be specified in a range (ex. M-F).
Turn ec2 instances on and off
policies: - name: offhours-stop resource: ec2 filters: - type: offhour actions: - stop - name: offhours-start resource: ec2 filters: - type: onhour actions: - start
Here’s doing the same with auto scale groups
policies: - name: asg-offhours-stop resource: asg filters: - offhour actions: - suspend - name: asg-onhours-start resource: asg filters: - onhour actions: - resume
Additional policy examples and resource-type-specific information can be seen in the EC2 Offhours and ASG Offhours use cases.
Resume During Offhours¶
These policies are evaluated hourly; during each run (once an hour), cloud-custodian will act on only the resources tagged for that exact hour. In other words, if a resource has an offhours policy of stopping/suspending at 23:00 Eastern daily and starting/resuming at 06:00 Eastern daily, and you run cloud-custodian once an hour via Lambda, that resource will only be stopped once a day sometime between 23:00 and 23:59, and will only be started once a day sometime between 06:00 and 06:59. If the current hour does not exactly match the hour specified in the policy, nothing will be done at all.
As a result of this, if custodian stops an instance or suspends an ASG and you need to start/resume it, you can safely do so manually and custodian won’t touch it again until the next day.
ElasticBeanstalk, EFS and Other Services with Tag Value Restrictions¶
A number of AWS services have restrictions on the characters that can be used
in tag values, such as ElasticBeanstalk and EFS. In particular, these services do not allow
parenthesis, square brackets, commas, or semicolons, or empty tag values. This
proves to be problematic with the tag-based schedule configuration described
above. The best current workaround is to define a separate policy with a unique
tag name for each unique schedule that you want to use, and then tag
resources with that tag name and a value of
on. Note that this can only be
used in opt-in mode, not opt-out.
Another option is to escape the tag value with the following mapping, generated with the char’s unicode number “u” + hex(ord(the_char))[2:]. This works for GCP resources as well.
( and ) as u28 and u29
[ and ] as u5b and u5d
, as u2c
; as u3b
= as u3d
/ as u2f
# off=(M-F,18);tz=Australia/Sydney offu3du28M-Fu2c18u29u3btzu3dAustraliau2fSydney # off=[(M-F,18),(S,13)] off=u5bu28M-Fu2c18u29u2cu28Su2c13u29u5d
In order to properly implement support for public holidays, make sure to include either skip-days or skip-days-from with your policy. This list should contain all of the public holidays you wish to address and must use YYYY-MM-DD syntax for its dates. If the date the policy is being run on matches any one of those dates, the policy will not return any resources. These dates include year as many holidays vary from year to year so year is required to prevent errors. A sample policy that would not start stopped instances on a public holiday might look like:
policies: - name: onhour-morning-start-skip-holidays resource: ec2 filters: - type: onhour tag: custodian_downtime default_tz: et onhour: 6 skip-days: ['2017-12-25'] actions: - start