Cron expressions
This topic describes the cron expressions that you can use in the Replicated KOTS Admin Console to schedule automatic update checks and automatic backups.
Supported installations
The following table lists where you can use cron expressions:
| Feature | Supported | Not supported |
|---|---|---|
| Automatic update checks. For more information, see Configure automatic updates. | KOTS in an existing cluster and kURL installations with outbound internet access | Embedded Cluster v2 and v3, and air gap installations |
| Automatic backups. For more information, see Schedule automatic backups in Create and schedule backups. | KOTS in an existing cluster, kURL, and Embedded Cluster v2 | Embedded Cluster v3 |
Embedded Cluster v3 does not use the KOTS Admin Console. For more information about scheduling backups for Embedded Cluster v3, see Create and manage backups in Back up and restore Embedded Cluster v3.
Syntax
<minute> <hour> <day-of-month> <month> <day-of-week>
Fields
The following table lists the required cron fields and supported values:
| Required Field | Allowed Values | Allowed Special Characters |
|---|---|---|
| Minute | 0 through 59 | , - * / |
| Hour | 0 through 23 | , - * / |
| Day-of-month | 1 through 31 | , - * ? / |
| Month | 1 through 12 or JAN through DEC | , - * / |
| Day-of-week | 0 through 6 or SUN through SAT, where 0 is Sunday | , - * ? / |
Special characters
KOTS uses the robfig/cron Go library to parse cron expressions.
The following table describes the supported special characters:
| Special Character | Description |
|---|---|
| Comma (,) | Specifies a list or multiple values, which can be consecutive or not. For example, 1,2,4 in the Day-of-week field signifies every Monday, Tuesday, and Thursday. |
| Dash (-) | Specifies a contiguous range. For example, 4-6 in the Month field signifies April through June. |
| Asterisk (*) | Specifies that all of the values for the field are used. For example, using * in the Month field means that all of the months are included in the schedule. |
| Slash (/) | Specifies increments. For example, */15 in the Minute field signifies every 15 minutes, and 0/4 in the Hour field signifies every 4 hours starting at midnight. |
| Question mark (?) | Equivalent to the asterisk (*). By convention, use ? in the Day-of-month or Day-of-week field to leave that field unrestricted. For example, enter 5 for Day-of-month and ? for Day-of-week to run on the 5th day of the month, regardless of which day of the week it is. |
Predefined schedules
You can use one of the following predefined schedule values instead of a cron expression:
| Schedule Value | Description | Equivalent Cron Expression |
|---|---|---|
| @yearly (or @annually) | Runs once a year, at midnight on January 1. | 0 0 1 1 * |
| @monthly | Runs once a month, at midnight on the first of the month. | 0 0 1 * * |
| @weekly | Runs once a week, at midnight on Sunday. | 0 0 * * 0 |
| @daily (or @midnight) | Runs once a day, at midnight. | 0 0 * * * |
| @hourly | Runs once an hour, at the beginning of the hour. | 0 * * * * |
| @never | Disables automatic update checks. Supported for automatic update checks only. This value can be useful when you are calling the API directly or are editing the KOTS configuration manually. | Not applicable |
| @default | Checks for updates every 4 hours, starting from when the Admin Console starts. This is the default schedule for automatic update checks. Supported for automatic update checks only. This value can be useful when you are calling the API directly or are editing the KOTS configuration manually. | Not applicable |
Intervals
You can also schedule the job to operate at fixed intervals, starting at the time the job is added or when cron is run:
@every DURATION
Replace DURATION with a string that is accepted by time.ParseDuration, with the exception of seconds. Seconds are not supported by KOTS. For more information about duration strings, see time.ParseDuration in the Go Time documentation.
As with standard cron expressions, the interval does not include the job runtime. For example, if a job is scheduled to run every 10 minutes, and the job takes 4 minutes to run, there are 6 minutes of idle time between each run.
Examples
The following examples show valid cron expressions:
-
At 11:30 AM every day:
30 11 * * * -
At 2:00 AM every Sunday:
0 2 * * 0 -
After 1 hour and 45 minutes, and then every interval following that:
@every 1h45m