From 7debbe4438862d8a181441b9f0e0aff4f4f607c6 Mon Sep 17 00:00:00 2001 From: Janet Kuo Date: Fri, 26 Aug 2016 16:23:16 -0700 Subject: [PATCH] Create a ref doc for scheduled jobs --- _data/reference.yml | 2 + docs/user-guide/scheduled-jobs.md | 180 ++++++++++++++++++++++++++++++ docs/user-guide/sj.yaml | 18 +++ 3 files changed, 200 insertions(+) create mode 100644 docs/user-guide/scheduled-jobs.md create mode 100644 docs/user-guide/sj.yaml diff --git a/_data/reference.yml b/_data/reference.yml index 939081a971919..4c4aa5adcf3e0 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -220,6 +220,8 @@ toc: path: /docs/user-guide/horizontal-pod-autoscaling/ - title: Jobs path: /docs/user-guide/jobs/ + - title: Scheduled Jobs + path: /docs/user-guide/scheduled-jobs/ - title: Resource Quotas path: /docs/admin/resource-quota/ - title: Replica Sets diff --git a/docs/user-guide/scheduled-jobs.md b/docs/user-guide/scheduled-jobs.md new file mode 100644 index 0000000000000..b96014a6d103f --- /dev/null +++ b/docs/user-guide/scheduled-jobs.md @@ -0,0 +1,180 @@ +--- +assignees: +- erictune +- soltysh +- janetkuo + +--- + +* TOC +{:toc} + +## What is a _Scheduled Job_? + +A _Scheduled Job_ manages time based [Jobs](/docs/user-guide/jobs/), namely: + +* Once at a specified point in time +* Repeatedly at a specified point in time + +One ScheduledJob object is like one line of a _crontab_ (cron table) file. It runs a job periodically +on a given schedule, written in [Cron](https://en.wikipedia.org/wiki/Cron) format. + +A typical use case is: + +* Schedule a job execution at a given point in time. +* Create a periodic job, e.g. database backup, sending emails. + +### Prerequisites + +You need a working Kubernetes cluster at version >= 1.4, with batch/v2alpha1 API turned on by passing +`--runtime-config=batch/v2alpha1` while bringing up the API server (see [Turn on or off an API version +for your cluster](/docs/admin/cluster-management/#turn-on-or-off-an-api-version-for-your-cluster) for +more). You cannot use Scheduled Jobs on a hosted Kubernetes provider that has disabled alpha resources. + +## Creating a Scheduled Job + +Here is an example Scheduled Job. Every minute, it runs a simple job to print current time and then say +hello. + +{% include code.html language="yaml" file="sj.yaml" ghlink="/docs/user-guide/sj.yaml" %} + +Run the example scheduled job by downloading the example file and then running this command: + +```shell +$ kubectl create -f ./sj.yaml +scheduledjob "hello" created +``` + +Alternatively, use `kubectl run` to create a scheduled job without writing full config: + +```shell +$ kubectl run hello --schedule="0/1 * * * ?" --restart=OnFailure --image=busybox -- /bin/sh -c "date; echo Hello from the Kubernetes cluster" +scheduledjob "hello" created +``` + +After creating the scheduled job, get its status using this command: + +```shell +$ kubectl get scheduledjob hello +NAME SCHEDULE SUSPEND ACTIVE LAST-SCHEDULE +hello 0/1 * * * ? False 0 +``` + +As you can see above, there's no active job yet, and no job has been scheduled, either. + +Watch for the job to be created in around one minute: + +```shell +$ kubectl get jobs --watch +NAME DESIRED SUCCESSFUL AGE +hello-4111706356 1 1 2s +``` + +Now you've seen one running job scheduled by "hello". We can stop watching it and get the scheduled job again: + +```shell +$ kubectl get scheduledjob hello +NAME SCHEDULE SUSPEND ACTIVE LAST-SCHEDULE +hello 0/1 * * * ? False 0 Mon, 29 Aug 2016 14:34:00 -0700 +``` + +You should see that "hello" successfully scheduled a job at the time specified in `LAST-SCHEDULE`. There are +currently 0 active jobs, meaning that the job that's scheduled is completed or failed. + +Now, find the pods created by the job last scheduled and view the standard output of one of the pods. Note that +your job name and pod name would be different. + +```shell +# Replace "hello-4111706356" with the job name in your system +$ pods=$(kubectl get pods --selector=job-name=hello-4111706356 --output=jsonpath={.items..metadata.name}) + +$ echo $pods +hello-4111706356-o9qcm + +$ kubectl logs $pods +Mon Aug 29 21:34:09 UTC 2016 +Hello from the Kubernetes cluster +``` + +## Deleting a Scheduled Job + +Once you don't need a scheduled job anymore, simply delete it with `kubectl`: + +```shell +$ kubectl delete scheduledjob hello +scheduledjob "hello" deleted +``` + +This stops new jobs from being created. However, running jobs won't be stopped, and no jobs or their pods will +be deleted. To clean up those jobs and pods, you need to list all jobs created by the scheduled job, and delete them all: + +```shell +$ kubectl get jobs +NAME DESIRED SUCCESSFUL AGE +hello-1201907962 1 1 11m +hello-1202039034 1 1 8m +... + +$ kubectl delete jobs hello-1201907962 hello-1202039034 ... +job "hello-1201907962" deleted +job "hello-1202039034" deleted +... +``` + +Once the jobs are deleted, the pods created by them are deleted as well. Note that all jobs created by scheduled +job "hello" will be prefixed "hello-". You can delete them at once with `kubectl delete jobs --all`, if you want to +delete all jobs in the current namespace (not just the ones created by "hello".) + +## Scheduled Job Limitations + +A scheduled job creates a job object _about_ once per execution time of its 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 them. Therefore, jobs should be _idempotent_. + +The job is responsible for retrying pods, parallelism among pods it creates, and determining the success or failure +of the set of pods. A scheduled job does not examine pods at all. + +## Writing a Scheduled Job Spec + +As with all other Kubernetes configs, a scheduled job needs `apiVersion`, `kind`, and `metadata` fields. For general +information about working with config files, see [deploying applications](/docs/user-guide/deploying-applications), +[configuring containers](/docs/user-guide/configuring-containers), and +[using kubectl to manage resources](/docs/user-guide/working-with-resources) documents. + +A scheduled job also needs a [`.spec` section](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status). + +**Note:** All modifications to a scheduled job, especially its `.spec`, will be applied only to the next run. + +### Schedule + +The `.spec.schedule` is a required field of the `.spec`. It takes a [Cron](https://en.wikipedia.org/wiki/Cron) format +string, e.g. `0 * * * *` or `@hourly`, as schedule time of its jobs to be created and executed. + +### Job Template + +The `.spec.jobTemplate` is another required field of the `.spec`. It is a job template. It has exactly the same schema +as a [Job](/docs/user-guide/jobs), except it is nested and does not have an `apiVersion` or `kind`, see +[Writing a Job Spec](/docs/user-guide/jobs/#writing-a-job-spec). + +### Starting Deadline Seconds + +The `.spec.startingDeadlineSeconds` field is optional. It stands for the deadline (in seconds) for starting the job +if it misses its scheduled time for any reason. Missed jobs executions will be counted as failed ones. If not specified, +there's no deadline. + +### Concurrency Policy + +The `.spec.concurrencyPolicy` field is also optional. It specifies how to treat concurrent executions of a job +created by this scheduled job. Only one of the following concurrent policies may be specified: + +* `Allow` (default): allows concurrently running jobs +* `Forbid`: forbids concurrent runs, skipping next run if previous hasn't finished yet +* `Replace`: cancels currently running job and replaces it with a new one + +Note that concurrency policy only applies to the jobs created by the same scheduled job. If there are multiple +scheduled jobs, their respective jobs are always allowed to run concurrently. + +### Suspend + +The `.spec.suspend` field is also optional. If set to `true`, all subsequent executions will be suspended. It does not +apply to already started executions. Defaults to false. diff --git a/docs/user-guide/sj.yaml b/docs/user-guide/sj.yaml new file mode 100644 index 0000000000000..1b22b7f340bab --- /dev/null +++ b/docs/user-guide/sj.yaml @@ -0,0 +1,18 @@ +apiVersion: batch/v2alpha1 +kind: ScheduledJob +metadata: + name: hello +spec: + schedule: 0/1 * * * ? + jobTemplate: + spec: + template: + spec: + containers: + - name: hello + image: busybox + args: + - /bin/sh + - -c + - date; echo Hello from the Kubernetes cluster + restartPolicy: OnFailure