You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
For information about writing a Job `.spec`, see [Writing a Job Spec](/docs/concepts/workloads/controllers/job/#writing-a-job-spec).
92
100
93
-
For example, the line below states that the task must be started every Friday at midnight, as well as on the 13th of each month at midnight:
101
+
### Deadline for delayed job start {#starting-deadline}
94
102
95
-
`0 0 13 * 5`
103
+
The `.spec.startingDeadlineSeconds` field is optional.
104
+
This field defines a deadline (in whole seconds) for starting the Job, if that Job misses its scheduled time
105
+
for any reason.
96
106
97
-
To generate CronJob schedule expressions, you can also use web tools like [crontab.guru](https://crontab.guru/).
107
+
After missing the deadline, the CronJob skips that instance of the Job (future occurrences are still scheduled).
108
+
For example, if you have a backup job that runs twice a day, you might allow it to start up to 8 hours late,
109
+
but no later, because a backup taken any later wouldn't be useful: you would instead prefer to wait for
110
+
the next scheduled run.
111
+
112
+
For Jobs that miss their configured deadline, Kubernetes treats them as failed Jobs.
113
+
If you don't specify `startingDeadlineSeconds` for a CronJob, the Job occurrences have no deadline.
114
+
115
+
If the `.spec.startingDeadlineSeconds` field is set (not null), the CronJob
116
+
controller measures the time between when a job is expected to be created and
117
+
now. If the difference is higher than that limit, it will skip this execution.
118
+
119
+
For example, if it is set to `200`, it allows a job to be created for up to 200
120
+
seconds after the actual schedule.
121
+
122
+
### Concurrency policy
123
+
124
+
The `.spec.concurrencyPolicy` field is also optional.
125
+
It specifies how to treat concurrent executions of a job that is created by this CronJob.
126
+
The spec may specify only one of the following concurrency policies:
127
+
128
+
*`Allow` (default): The CronJob allows concurrently running jobs
129
+
*`Forbid`: The CronJob does not allow concurrent runs; if it is time for a new job run and the
130
+
previous job run hasn't finished yet, the CronJob skips the new job run
131
+
*`Replace`: If it is time for a new job run and the previous job run hasn't finished yet, the
132
+
CronJob replaces the currently running job run with a new job run
133
+
134
+
Note that concurrency policy only applies to the jobs created by the same cron job.
135
+
If there are multiple CronJobs, their respective jobs are always allowed to run concurrently.
98
136
99
-
##Time zones
137
+
### Schedule suspension
100
138
101
-
For CronJobs with no time zone specified, the kube-controller-manager interprets schedules relative to its local time zone.
139
+
You can suspend execution of Jobs for a CronJob, by setting the optional `.spec.suspend` field
140
+
to true. The field defaults to false.
141
+
142
+
This setting does _not_ affect Jobs that the CronJob has already started.
143
+
144
+
If you do set that field to true, all subsequent executions are suspended (they remain
145
+
scheduled, but the CronJob controller does not start the Jobs to run the tasks) until
146
+
you unsuspend the CronJob.
147
+
148
+
{{< caution >}}
149
+
Executions that are suspended during their scheduled time count as missed jobs.
150
+
When `.spec.suspend` changes from `true` to `false` on an existing CronJob without a
151
+
[starting deadline](#starting-deadline), the missed jobs are scheduled immediately.
152
+
{{< /caution >}}
153
+
154
+
### Jobs history limits
155
+
156
+
The `.spec.successfulJobsHistoryLimit` and `.spec.failedJobsHistoryLimit` fields are optional.
157
+
These fields specify how many completed and failed jobs should be kept.
158
+
By default, they are set to 3 and 1 respectively. Setting a limit to `0` corresponds to keeping
159
+
none of the corresponding kind of jobs after they finish.
160
+
161
+
For another way to clean up jobs automatically, see [Clean up finished jobs automatically](/docs/concepts/workloads/controllers/job/#clean-up-finished-jobs-automatically).
162
+
163
+
### Time zones
164
+
165
+
For CronJobs with no time zone specified, the {{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}} interprets schedules relative to its local time zone.
@@ -107,16 +171,39 @@ you can specify a time zone for a CronJob (if you don't enable that feature gate
107
171
Kubernetes that does not have experimental time zone support, all CronJobs in your cluster have an unspecified
108
172
timezone).
109
173
110
-
When you have the feature enabled, you can set `spec.timeZone` to the name of a valid [time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). For example, setting
111
-
`spec.timeZone: "Etc/UTC"` instructs Kubernetes to interpret the schedule relative to Coordinated Universal Time.
174
+
When you have the feature enabled, you can set `.spec.timeZone` to the name of a valid [time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). For example, setting
175
+
`.spec.timeZone: "Etc/UTC"` instructs Kubernetes to interpret the schedule relative to Coordinated Universal Time.
176
+
177
+
{{< caution >}}
178
+
The implementation of the CronJob API in Kubernetes {{< skew currentVersion >}} lets you set
179
+
the `.spec.schedule` field to include a timezone; for example: `CRON_TZ=UTC * * * * *`
180
+
or `TZ=UTC * * * * *`.
181
+
182
+
Specifying a timezone that way is **not officially supported** (and never has been).
183
+
184
+
If you try to set a schedule that includes `TZ` or `CRON_TZ` timezone specification,
185
+
Kubernetes reports a [warning](/blog/2020/09/03/warnings/) to the client.
186
+
Future versions of Kubernetes might not implement that unofficial timezone mechanism at all.
187
+
{{< /caution >}}
112
188
113
189
A time zone database from the Go standard library is included in the binaries and used as a fallback in case an external database is not available on the system.
114
190
115
191
## CronJob limitations {#cron-job-limitations}
116
192
117
-
A cron job creates a job object _about_ once per execution time of its schedule. We say "about" because there
118
-
are certain circumstances where two jobs might be created, or no job might be created. We attempt to make these rare,
119
-
but do not completely prevent them. Therefore, jobs should be _idempotent_.
193
+
### Modifying a CronJob
194
+
By design, a CronJob contains a template for _new_ Jobs.
195
+
If you modify an existing CronJob, the changes you make will apply to new Jobs that
196
+
start to run after your modification is complete. Jobs (and their Pods) that have already
197
+
started continue to run without changes.
198
+
That is, the CronJob does _not_ update existing Jobs, even if those remain running.
199
+
200
+
### Job creation
201
+
202
+
A CronJob creates a Job object approximately once per execution time of its schedule.
203
+
The scheduling is approximate because there
204
+
are certain circumstances where two Jobs might be created, or no Job might be created.
205
+
Kubernetes tries to avoid those situations, but do not completely prevent them. Therefore,
206
+
the Jobs that you define should be _idempotent_.
120
207
121
208
If `startingDeadlineSeconds` is set to a large value or left unset (the default)
122
209
and if `concurrencyPolicy` is set to `Allow`, the jobs will always run
@@ -148,32 +235,16 @@ be down for the same period as the previous example (`08:29:00` to `10:21:00`,)
148
235
The CronJob is only responsible for creating Jobs that match its schedule, and
149
236
the Job in turn is responsible for the management of the Pods it represents.
150
237
151
-
## Controller version {#new-controller}
152
-
153
-
Starting with Kubernetes v1.21 the second version of the CronJob controller
154
-
is the default implementation. To disable the default CronJob controller
155
-
and use the original CronJob controller instead, pass the `CronJobControllerV2`
0 commit comments