Merge pull request #345 from soltysh/rename_cronjob
Rename ScheduledJob to CronJobs
This commit is contained in:
Maciej Szulik
GitHub
commit
ff598e480e
|
|
@ -1,8 +1,8 @@
|
|||
# ScheduledJob Controller
|
||||
# CronJob Controller (previously ScheduledJob)
|
||||
|
||||
## Abstract
|
||||
|
||||
A proposal for implementing a new controller - ScheduledJob controller - which
|
||||
A proposal for implementing a new controller - CronJob controller - which
|
||||
will be responsible for managing time based jobs, namely:
|
||||
* once at a specified point in time,
|
||||
* repeatedly at a specified point in time.
|
||||
|
|
@ -23,20 +23,20 @@ There are also similar solutions available, already:
|
|||
|
||||
## Motivation
|
||||
|
||||
ScheduledJobs are needed for performing all time-related actions, namely backups,
|
||||
CronJobs are needed for performing all time-related actions, namely backups,
|
||||
report generation and the like. Each of these tasks should be allowed to run
|
||||
repeatedly (once a day/month, etc.) or once at a given point in time.
|
||||
|
||||
|
||||
## Design Overview
|
||||
|
||||
Users create a ScheduledJob object. One ScheduledJob object
|
||||
Users create a CronJob object. One CronJob object
|
||||
is like one line of a crontab file. It has a schedule of when to run,
|
||||
in [Cron](https://en.wikipedia.org/wiki/Cron) format.
|
||||
|
||||
|
||||
The ScheduledJob controller creates a Job object [Job](job.md)
|
||||
about once per execution time of the scheduled (e.g. once per
|
||||
The CronJob controller creates a Job object [Job](job.md)
|
||||
about once per execution time of the schedule (e.g. once per
|
||||
day for a daily schedule.) We say "about" because there are certain
|
||||
circumstances where two jobs might be created, or no job might be
|
||||
created. We attempt to make these rare, but do not completely prevent
|
||||
|
|
@ -44,45 +44,45 @@ them. Therefore, Jobs should be idempotent.
|
|||
|
||||
The Job object is responsible for any retrying of Pods, and any parallelism
|
||||
among pods it creates, and determining the success or failure of the set of
|
||||
pods. The ScheduledJob does not examine pods at all.
|
||||
pods. The CronJob does not examine pods at all.
|
||||
|
||||
|
||||
### ScheduledJob resource
|
||||
### CronJob resource
|
||||
|
||||
The new `ScheduledJob` object will have the following contents:
|
||||
The new `CronJob` object will have the following contents:
|
||||
|
||||
```go
|
||||
// ScheduledJob represents the configuration of a single scheduled job.
|
||||
type ScheduledJob struct {
|
||||
// CronJob represents the configuration of a single cron job.
|
||||
type CronJob struct {
|
||||
TypeMeta
|
||||
ObjectMeta
|
||||
|
||||
// Spec is a structure defining the expected behavior of a job, including the schedule.
|
||||
Spec ScheduledJobSpec
|
||||
Spec CronJobSpec
|
||||
|
||||
// Status is a structure describing current status of a job.
|
||||
Status ScheduledJobStatus
|
||||
Status CronJobStatus
|
||||
}
|
||||
|
||||
// ScheduledJobList is a collection of scheduled jobs.
|
||||
type ScheduledJobList struct {
|
||||
// CronJobList is a collection of cron jobs.
|
||||
type CronJobList struct {
|
||||
TypeMeta
|
||||
ListMeta
|
||||
|
||||
Items []ScheduledJob
|
||||
Items []CronJob
|
||||
}
|
||||
```
|
||||
|
||||
The `ScheduledJobSpec` structure is defined to contain all the information how the actual
|
||||
The `CronJobSpec` structure is defined to contain all the information how the actual
|
||||
job execution will look like, including the `JobSpec` from [Job API](job.md)
|
||||
and the schedule in [Cron](https://en.wikipedia.org/wiki/Cron) format. This implies
|
||||
that each ScheduledJob execution will be created from the JobSpec actual at a point
|
||||
that each CronJob execution will be created from the JobSpec actual at a point
|
||||
in time when the execution will be started. This also implies that any changes
|
||||
to ScheduledJobSpec will be applied upon subsequent execution of a job.
|
||||
to CronJobSpec will be applied upon subsequent execution of a job.
|
||||
|
||||
```go
|
||||
// ScheduledJobSpec describes how the job execution will look like and when it will actually run.
|
||||
type ScheduledJobSpec struct {
|
||||
// CronJobSpec describes how the job execution will look like and when it will actually run.
|
||||
type CronJobSpec struct {
|
||||
|
||||
// Schedule contains the schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
|
||||
Schedule string
|
||||
|
|
@ -99,12 +99,12 @@ type ScheduledJobSpec struct {
|
|||
Suspend bool
|
||||
|
||||
// JobTemplate is the object that describes the job that will be created when
|
||||
// executing a ScheduledJob.
|
||||
// executing a CronJob.
|
||||
JobTemplate *JobTemplateSpec
|
||||
}
|
||||
|
||||
// JobTemplateSpec describes of the Job that will be created when executing
|
||||
// a ScheduledJob, including its standard metadata.
|
||||
// a CronJob, including its standard metadata.
|
||||
type JobTemplateSpec struct {
|
||||
ObjectMeta
|
||||
|
||||
|
|
@ -119,7 +119,7 @@ type JobTemplateSpec struct {
|
|||
type ConcurrencyPolicy string
|
||||
|
||||
const (
|
||||
// AllowConcurrent allows ScheduledJobs to run concurrently.
|
||||
// AllowConcurrent allows CronJobs to run concurrently.
|
||||
AllowConcurrent ConcurrencyPolicy = "Allow"
|
||||
|
||||
// ForbidConcurrent forbids concurrent runs, skipping next run if previous
|
||||
|
|
@ -131,13 +131,13 @@ const (
|
|||
)
|
||||
```
|
||||
|
||||
`ScheduledJobStatus` structure is defined to contain information about scheduled
|
||||
`CronJobStatus` structure is defined to contain information about cron
|
||||
job executions. The structure holds a list of currently running job instances
|
||||
and additional information about overall successful and unsuccessful job executions.
|
||||
|
||||
```go
|
||||
// ScheduledJobStatus represents the current state of a Job.
|
||||
type ScheduledJobStatus struct {
|
||||
// CronJobStatus represents the current state of a Job.
|
||||
type CronJobStatus struct {
|
||||
// Active holds pointers to currently running jobs.
|
||||
Active []ObjectReference
|
||||
|
||||
|
|
@ -159,7 +159,7 @@ Users must use a generated selector for the job.
|
|||
TODO for beta: forbid manual selector since that could cause confusing between
|
||||
subsequent jobs.
|
||||
|
||||
### Running ScheduledJobs using kubectl
|
||||
### Running CronJobs using kubectl
|
||||
|
||||
A user should be able to easily start a Scheduled Job using `kubectl` (similarly
|
||||
to running regular jobs). For example to run a job with a specified schedule,
|
||||
|
|
@ -178,21 +178,21 @@ In the above example:
|
|||
|
||||
## Fields Added to Job Template
|
||||
|
||||
When the controller creates a Job from the JobTemplateSpec in the ScheduledJob, it
|
||||
When the controller creates a Job from the JobTemplateSpec in the CronJob, it
|
||||
adds the following fields to the Job:
|
||||
|
||||
- a name, based on the ScheduledJob's name, but with a suffix to distinguish
|
||||
- a name, based on the CronJob's name, but with a suffix to distinguish
|
||||
multiple executions, which may overlap.
|
||||
- the standard created-by annotation on the Job, pointing to the SJ that created it
|
||||
The standard key is `kubernetes.io/created-by`. The value is a serialized JSON object, like
|
||||
`{ "kind":"SerializedReference","apiVersion":"v1","reference":{"kind":"ScheduledJob","namespace":"default",`
|
||||
`{ "kind":"SerializedReference","apiVersion":"v1","reference":{"kind":"CronJob","namespace":"default",`
|
||||
`"name":"nightly-earnings-report","uid":"5ef034e0-1890-11e6-8935-42010af0003e","apiVersion":...`
|
||||
This serialization contains the UID of the parent. This is used to match the Job to the SJ that created
|
||||
it.
|
||||
|
||||
## Updates to ScheduledJobs
|
||||
## Updates to CronJobs
|
||||
|
||||
If the schedule is updated on a ScheduledJob, it will:
|
||||
If the schedule is updated on a CronJob, it will:
|
||||
- continue to use the Status.Active list of jobs to detect conflicts.
|
||||
- try to fulfill all recently-passed times for the new schedule, by starting
|
||||
new jobs. But it will not try to fulfill times prior to the
|
||||
|
|
@ -202,16 +202,16 @@ If the schedule is updated on a ScheduledJob, it will:
|
|||
- Example: If you have a schedule to run every hour, change that to 30-minutely, at 31 minutes past the hour,
|
||||
one run will be started immediately for the starting time that has just passed.
|
||||
|
||||
If the job template of a ScheduledJob is updated, then future executions use the new template
|
||||
If the job template of a CronJob is updated, then future executions use the new template
|
||||
but old ones still satisfy the schedule and are not re-run just because the template changed.
|
||||
|
||||
If you delete and replace a ScheduledJob with one of the same name, it will:
|
||||
If you delete and replace a CronJob with one of the same name, it will:
|
||||
- not use any old Status.Active, and not consider any existing running or terminated jobs from the previous
|
||||
ScheduledJob (with a different UID) at all when determining coflicts, what needs to be started, etc.
|
||||
CronJob (with a different UID) at all when determining coflicts, what needs to be started, etc.
|
||||
- If there is an existing Job with the same time-based hash in its name (see below), then
|
||||
new instances of that job will not be able to be created. So, delete it if you want to re-run.
|
||||
with the same name as conflicts.
|
||||
- not "re-run" jobs for "start times" before the creation time of the new ScheduledJobJob object.
|
||||
- not "re-run" jobs for "start times" before the creation time of the new CronJobJob object.
|
||||
- not consider executions from the previous UID when making decisions about what executions to
|
||||
start, or status, etc.
|
||||
- lose the history of the old SJ.
|
||||
|
|
@ -223,11 +223,11 @@ To preserve status, you can suspend the old one, and make one with a new name, o
|
|||
|
||||
### Starting Jobs in the face of controller failures
|
||||
|
||||
If the process with the scheduledJob controller in it fails,
|
||||
and takes a while to restart, the scheduledJob controller
|
||||
If the process with the cronJob controller in it fails,
|
||||
and takes a while to restart, the cronJob controller
|
||||
may miss the time window and it is too late to start a job.
|
||||
|
||||
With a single scheduledJob controller process, we cannot give
|
||||
With a single cronJob controller process, we cannot give
|
||||
very strong assurances about not missing starting jobs.
|
||||
|
||||
With a suggested HA configuration, there are multiple controller
|
||||
|
|
@ -254,10 +254,10 @@ There are three problems here:
|
|||
|
||||
Multiple jobs might be created in the following sequence:
|
||||
|
||||
1. scheduled job controller sends request to start Job J1 to fulfill start time T.
|
||||
1. cron job controller sends request to start Job J1 to fulfill start time T.
|
||||
1. the create request is accepted by the apiserver and enqueued but not yet written to etcd.
|
||||
1. scheduled job controller crashes
|
||||
1. new scheduled job controller starts, and lists the existing jobs, and does not see one created.
|
||||
1. cron job controller crashes
|
||||
1. new cron job controller starts, and lists the existing jobs, and does not see one created.
|
||||
1. it creates a new one.
|
||||
1. the first one eventually gets written to etcd.
|
||||
1. there are now two jobs for the same start time.
|
||||
|
|
@ -286,24 +286,24 @@ This is too hard to do for the alpha version. We will await user
|
|||
feedback to see if the "at most once" property is needed in the beta version.
|
||||
|
||||
This is awkward but possible for a containerized application ensure on it own, as it needs
|
||||
to know what ScheduledJob name and Start Time it is from, and then record the attempt
|
||||
to know what CronJob name and Start Time it is from, and then record the attempt
|
||||
in a shared storage system. We should ensure it could extract this data from its annotations
|
||||
using the downward API.
|
||||
|
||||
## Name of Jobs
|
||||
|
||||
A ScheduledJob creates one Job at each time when a Job should run.
|
||||
A CronJob creates one Job at each time when a Job should run.
|
||||
Since there may be concurrent jobs, and since we might want to keep failed
|
||||
non-overlapping Jobs around as a debugging record, each Job created by the same ScheduledJob
|
||||
non-overlapping Jobs around as a debugging record, each Job created by the same CronJob
|
||||
needs a distinct name.
|
||||
|
||||
To make the Jobs from the same ScheduledJob distinct, we could use a random string,
|
||||
in the way that pods have a `generateName`. For example, a scheduledJob named `nightly-earnings-report`
|
||||
To make the Jobs from the same CronJob distinct, we could use a random string,
|
||||
in the way that pods have a `generateName`. For example, a cronJob named `nightly-earnings-report`
|
||||
in namespace `ns1` might create a job `nightly-earnings-report-3m4d3`, and later create
|
||||
a job called `nightly-earnings-report-6k7ts`. This is consistent with pods, but
|
||||
does not give the user much information.
|
||||
|
||||
Alternatively, we can use time as a uniquifier. For example, the same scheduledJob could
|
||||
Alternatively, we can use time as a uniquifier. For example, the same cronJob could
|
||||
create a job called `nightly-earnings-report-2016-May-19`.
|
||||
However, for Jobs that run more than once per day, we would need to represent
|
||||
time as well as date. Standard date formats (e.g. RFC 3339) use colons for time.
|
||||
|
|
@ -312,7 +312,7 @@ will annoy some users.
|
|||
|
||||
Also, date strings are much longer than random suffixes, which means that
|
||||
the pods will also have long names, and that we are more likely to exceed the
|
||||
253 character name limit when combining the scheduled-job name,
|
||||
253 character name limit when combining the cron-job name,
|
||||
the time suffix, and pod random suffix.
|
||||
|
||||
One option would be to compute a hash of the nominal start time of the job,
|
||||
|
|
@ -331,5 +331,5 @@ Below are the possible future extensions to the Job controller:
|
|||
types of resources. This relates to the work happening in [#18215](https://issues.k8s.io/18215).
|
||||
|
||||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||
[]()
|
||||
[]()
|
||||
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
||||
Loading…
Reference in New Issue