mirror of https://github.com/k3s-io/k3s
ScheduledJob controller proposal
Maciej Szulik
parent
da8b85e5c7
commit
10de4c2d51
|
|
@ -0,0 +1,225 @@
|
|||
<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
|
||||
|
||||
<!-- BEGIN STRIP_FOR_RELEASE -->
|
||||
|
||||
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||
width="25" height="25">
|
||||
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||
width="25" height="25">
|
||||
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||
width="25" height="25">
|
||||
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||
width="25" height="25">
|
||||
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||
width="25" height="25">
|
||||
|
||||
<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
|
||||
|
||||
If you are using a released version of Kubernetes, you should
|
||||
refer to the docs that go with that version.
|
||||
|
||||
Documentation for other releases can be found at
|
||||
[releases.k8s.io](http://releases.k8s.io).
|
||||
</strong>
|
||||
--
|
||||
|
||||
<!-- END STRIP_FOR_RELEASE -->
|
||||
|
||||
<!-- END MUNGE: UNVERSIONED_WARNING -->
|
||||
|
||||
# ScheduledJob Controller
|
||||
|
||||
## Abstract
|
||||
|
||||
A proposal for implementing a new controller - ScheduledJob 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.
|
||||
|
||||
There is already a discussion regarding this subject:
|
||||
* Distributed CRON jobs [#2156](https://issues.k8s.io/2156)
|
||||
|
||||
There are also similar solutions available, already:
|
||||
* [Mesos Chronos](https://github.com/mesos/chronos)
|
||||
* [Quartz](http://quartz-scheduler.org/)
|
||||
|
||||
|
||||
## Use Cases
|
||||
|
||||
1. Be able to schedule a job execution at a given point in time.
|
||||
1. Be able to create a periodic job, eg. database backup, sending emails.
|
||||
|
||||
|
||||
## Motivation
|
||||
|
||||
ScheduledJobs 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.
|
||||
|
||||
|
||||
## Implementation
|
||||
|
||||
### ScheduledJob resource
|
||||
|
||||
The ScheduledJob controller relies heavily on the [Job API](job.md)
|
||||
for running actual jobs, on top of which it adds information regarding the date
|
||||
and time part according to [Cron](https://en.wikipedia.org/wiki/Cron) format.
|
||||
|
||||
The new `ScheduledJob` object will have the following contents:
|
||||
|
||||
```go
|
||||
// ScheduledJob represents the configuration of a single scheduled job.
|
||||
type ScheduledJob struct {
|
||||
TypeMeta
|
||||
ObjectMeta
|
||||
|
||||
// Spec is a structure defining the expected behavior of a job, including the schedule.
|
||||
Spec ScheduledJobSpec
|
||||
|
||||
// Status is a structure describing current status of a job.
|
||||
Status ScheduledJobStatus
|
||||
}
|
||||
|
||||
// ScheduledJobList is a collection of scheduled jobs.
|
||||
type ScheduledJobList struct {
|
||||
TypeMeta
|
||||
ListMeta
|
||||
|
||||
Items []ScheduledJob
|
||||
}
|
||||
```
|
||||
|
||||
The `ScheduledJobSpec` 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
|
||||
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.
|
||||
|
||||
```go
|
||||
// ScheduledJobSpec describes how the job execution will look like and when it will actually run.
|
||||
type ScheduledJobSpec struct {
|
||||
|
||||
// Schedule contains the schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
|
||||
Schedule string
|
||||
|
||||
// Optional deadline in seconds for starting the job if it misses scheduled
|
||||
// time for any reason. Missed jobs executions will be counted as failed ones.
|
||||
StartingDeadlineSeconds *int64
|
||||
|
||||
// ConcurrencyPolicy specifies how to treat concurrent executions of a Job.
|
||||
ConcurrencyPolicy ConcurrencyPolicy
|
||||
|
||||
// Suspend flag tells the controller to suspend subsequent executions, it does
|
||||
// not apply to already started executions. Defaults to false.
|
||||
Suspend bool
|
||||
|
||||
// JobTemplate is the object that describes the job that will be created when
|
||||
// executing a ScheduledJob.
|
||||
JobTemplate *JobTemplateSpec
|
||||
}
|
||||
|
||||
// JobTemplateSpec describes of the Job that will be created when executing
|
||||
// a ScheduledJob, including its standard metadata.
|
||||
type JobTemplateSpec struct {
|
||||
ObjectMeta
|
||||
|
||||
// Specification of the desired behavior of the job.
|
||||
Spec JobSpec
|
||||
}
|
||||
|
||||
// ConcurrencyPolicy describes how the job will be handled.
|
||||
// Only one of the following concurrent policies may be specified.
|
||||
// If none of the following policies is specified, the default one
|
||||
// is AllowConcurrent.
|
||||
type ConcurrencyPolicy string
|
||||
|
||||
const (
|
||||
// AllowConcurrent allows ScheduledJobs to run concurrently.
|
||||
AllowConcurrent ConcurrencyPolicy = "Allow"
|
||||
|
||||
// ForbidConcurrent forbids concurrent runs, skipping next run if previous
|
||||
// hasn't finished yet.
|
||||
ForbidConcurrent ConcurrencyPolicy = "Forbid"
|
||||
|
||||
// ReplaceConcurrent cancels currently running job and replaces it with a new one.
|
||||
ReplaceConcurrent ConcurrencyPolicy = "Replace"
|
||||
)
|
||||
```
|
||||
|
||||
`ScheduledJobStatus` structure is defined to contain information about scheduled
|
||||
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 {
|
||||
// Active holds pointers to currently running jobs.
|
||||
Active []ObjectReference
|
||||
|
||||
// Successful tracks the overall amount of successful completions of this job.
|
||||
Successful int64
|
||||
|
||||
// Failed tracks the overall amount of failures of this job.
|
||||
Failed int64
|
||||
|
||||
// LastScheduleTime keeps information of when was the last time the job was successfully scheduled.
|
||||
LastScheduleTime Time
|
||||
}
|
||||
```
|
||||
|
||||
### Modifications to Job resource
|
||||
|
||||
In order to distinguish Job runs, we need to add `UniqueLabelKey` field to `JobSpec`.
|
||||
This field will be used for creating unique label selectors.
|
||||
|
||||
```go
|
||||
type JobSpec {
|
||||
|
||||
//...
|
||||
|
||||
// Key of the selector that is added to prevent concurrently running Jobs
|
||||
// selecting their pods.
|
||||
// Users can set this to an empty string to indicate that the system should
|
||||
// not add any selector and label. If unspecified, system uses
|
||||
// "scheduledjob.kubernetes.io/podTemplateHash".
|
||||
// Value of this key is hash of ScheduledJobSpec.PodTemplateSpec.
|
||||
// No label is added if this is set to an empty string.
|
||||
UniqueLabelKey *string
|
||||
}
|
||||
```
|
||||
|
||||
Although at Job level empty string is perfectly valid, `ScheduledJob` cannot have
|
||||
empty selector, it needs to be defined, either by user or generated automatically.
|
||||
For this to happen, validation will be tightened at ScheduledJob level for this
|
||||
field to be either nil or non-empty string.
|
||||
|
||||
### Running ScheduledJobs 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,
|
||||
a user should be able to type something simple like:
|
||||
|
||||
```
|
||||
kubectl run pi --image=perl --restart=OnFailure --runAt="0 14 21 7 *" -- perl -Mbignum=bpi -wle 'print bpi(2000)'
|
||||
```
|
||||
|
||||
In the above example:
|
||||
|
||||
* `--restart=OnFailure` implies creating a job instead of replicationController.
|
||||
* `--runAt="0 14 21 7 *"` implies the schedule with which the job should be run, here
|
||||
July 7th, 2pm. This value will be validated according to the same rules which
|
||||
apply to `.spec.schedule`.
|
||||
|
||||
|
||||
## Future evolution
|
||||
|
||||
Below are the possible future extensions to the Job controller:
|
||||
* Be able to specify workflow template in `.spec` field. This relates to the work
|
||||
happening in [#18827](https://issues.k8s.io/18827).
|
||||
* Be able to specify more general template in `.spec` field, to create arbitrary
|
||||
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